[PATCH 2/2] drm/doc: emphasize difference between plane formats and IN_FORMATS blob

[Leandro Ribeiro]

Emphasize how userspace should use the plane format list
(format_type_ptr) and the IN_FORMATS blob property.

Formats exposed in the plane format list (format_type_ptr) do not
require modifiers, and formats that are present in the IN_FORMATS blob
property support modifiers.

Note that these are not disjoint sets. If a format supports modifiers
but the driver can also handle it without a modifier, it should be
present in both the IN_FORMATS blob property and the plane format list.

Signed-off-by: Leandro Ribeiro <leandro.ribeiro at collabora.com>
---
 drivers/gpu/drm/drm_plane.c | 4 ++++
 include/uapi/drm/drm_mode.h | 3 +++
 2 files changed, 7 insertions(+)

diff --git a/drivers/gpu/drm/drm_plane.c b/drivers/gpu/drm/drm_plane.c
index 0dd43882fe7c..b48d9bd81a59 100644
--- a/drivers/gpu/drm/drm_plane.c
+++ b/drivers/gpu/drm/drm_plane.c
@@ -128,6 +128,10 @@
  *     pairs supported by this plane. The blob is a struct
  *     drm_format_modifier_blob. Without this property the plane doesn't
  *     support buffers with modifiers. Userspace cannot change this property.
+ *
+ *     To find out the list of buffer formats which are supported without a
+ *     modifier, userspace should not look at this blob property, but at the
+ *     formats list of the plane: &drm_mode_get_plane.format_type_ptr.
  */
 
 static unsigned int drm_num_planes(struct drm_device *dev)
diff --git a/include/uapi/drm/drm_mode.h b/include/uapi/drm/drm_mode.h
index 96fc9a6da608..4293800ec095 100644
--- a/include/uapi/drm/drm_mode.h
+++ b/include/uapi/drm/drm_mode.h
@@ -340,6 +340,9 @@ struct drm_mode_get_plane {
 	/**
 	 * @format_type_ptr: Pointer to ``__u32`` array of formats that are
 	 * supported by the plane. These formats do not require modifiers.
+	 *
+	 * To find out the list of formats that support modifiers, userspace
+	 * must use the plane IN_FORMATS blob property.
 	 */
 	__u64 format_type_ptr;
 };
-- 
2.31.1