[PATCH] drm/dumb-buffers: document that it's only for linear FB

[Icenowy Zheng]

The ioctl interfaces for dumb buffers currently only properly support
linear buffers.

Mention this in the documentation snippet of dumb-buffers source code,
which is referenced by drm-kms.rst and will end up in the built kernel
documentation.

Also mention the existence of current drivers abusing dumb buffers for
AFBC to reduce confusion about this.

Signed-off-by: Icenowy Zheng <zhengxingda@xxxxxxxxxxx>
---
 drivers/gpu/drm/drm_dumb_buffers.c | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/drivers/gpu/drm/drm_dumb_buffers.c b/drivers/gpu/drm/drm_dumb_buffers.c
index e2b62e5fb891b..06f74460adf62 100644
--- a/drivers/gpu/drm/drm_dumb_buffers.c
+++ b/drivers/gpu/drm/drm_dumb_buffers.c
@@ -57,7 +57,12 @@
  *
  * Note that dumb objects may not be used for gpu acceleration, as has been
  * attempted on some ARM embedded platforms. Such drivers really must have
- * a hardware-specific ioctl to allocate suitable buffer objects.
+ * a hardware-specific ioctl to allocate suitable buffer objects. They are
+ * also currently meant for only linear buffers, and using them with any
+ * modifier other than DRM_FORMAT_MOD_LINEAR is undefined behavior. There
+ * exist some KMS drivers abusing dumb objects for AFBC framebuffers, but this
+ * behavior is discouraged, only exists as a hack now and shouldn't be
+ * replicated.
  */
 
 static int drm_mode_align_dumb(struct drm_mode_create_dumb *args,
-- 
2.52.0