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

[Ville Syrjälä]

On Tue, Apr 06, 2021 at 04:21:18PM -0300, Leandro Ribeiro wrote:
> 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.
>  	 */

Addfb2+modifiers predates the IN_FORMATS blob, so this doesn't
match reality.

>  	__u64 format_type_ptr;
>  };
> -- 
> 2.31.1
> 
> _______________________________________________
> dri-devel mailing list
> dri-devel at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/dri-devel

-- 
Ville Syrjälä
Intel