[PATCH v2 2/2] drm/dumb-buffers: document abuses in the UAPI document

[Icenowy Zheng]

Although the current DRM_IOCTL_MODE_CREATE_DUMB interface design only
suits linear buffers, some current software abusing it for AFBC
framebuffers and existing KMS drivers with AFBC support seem to allow
such kind of abuse.

Mention it in the interface document, and clarifying that it's not
recommended.

Signed-off-by: Icenowy Zheng <zhengxingda@xxxxxxxxxxx>
---
Changes in v2:
- Move the line saying layout is always linear to the notice paragraph.
- Change the subject to software instead of driver.

 include/uapi/drm/drm_mode.h | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/include/uapi/drm/drm_mode.h b/include/uapi/drm/drm_mode.h
index cbbbfc1dfe2b8..3e46378379f45 100644
--- a/include/uapi/drm/drm_mode.h
+++ b/include/uapi/drm/drm_mode.h
@@ -1213,7 +1213,6 @@ struct drm_mode_crtc_page_flip_target {
  * or a variant thereof. The value often corresponds to the number of bits
  * per pixel for most modes, although there are exceptions. Each color mode
  * maps to a DRM format plus a number of modes with similar pixel layout.
- * Framebuffer layout is always linear.
  *
  * Support for all modes and formats is optional. Even if dumb-buffer
  * creation with a certain color mode succeeds, it is not guaranteed that
@@ -1253,9 +1252,13 @@ struct drm_mode_crtc_page_flip_target {
  * legacy user space. Please don't use them in new code. Other modes
  * are not support.
  *
+ * Framebuffer layout is always linear when allocated with this interface.
  * Do not attempt to allocate anything but linear framebuffer memory
  * with single-plane RGB data. Allocation of other framebuffer
  * layouts requires dedicated ioctls in the respective DRM driver.
+ * There exists userspace software exploiting this interface for
+ * framebuffers with non-linear layout, but this is incorrect usage with
+ * undefined behavior, and should not be replicated.
  */
 struct drm_mode_create_dumb {
 	__u32 height;
-- 
2.52.0