[PATCH 3/3] drm: document minimum kernel version for DRM_CLIENT_CAP_*

[Pekka Paalanen]

On Tue, 18 May 2021 11:14:52 +0000
Simon Ser <contact at emersion.fr> wrote:

> The kernel versions including the following commits are referenced:
> 
> DRM_CLIENT_CAP_STEREO_3D
> 61d8e3282541 ("drm: Add a STEREO_3D capability to the SET_CLIENT_CAP ioctl")
> 
> DRM_CLIENT_CAP_UNIVERSAL_PLANES
> 681e7ec73044 ("drm: Allow userspace to ask for universal plane list (v2)")
> c7dbc6c9ae5c ("drm: Remove command line guard for universal planes")
> 
> DRM_CLIENT_CAP_ATOMIC
> 88a48e297b3a ("drm: add atomic properties")
> 8b72ce158cf0 ("drm: Always enable atomic API")
> 
> DRM_CLIENT_CAP_ASPECT_RATIO
> 7595bda2fb43 ("drm: Add DRM client cap for aspect-ratio")
> 
> DRM_CLIENT_CAP_WRITEBACK_CONNECTORS
> d67b6a206507 ("drm: writeback: Add client capability for exposing writeback connectors")
> 
> Signed-off-by: Simon Ser <contact at emersion.fr>
> Cc: Daniel Vetter <daniel at ffwll.ch>
> Cc: Daniel Stone <daniels at collabora.com>
> Cc: Pekka Paalanen <ppaalanen at gmail.com>
> ---
>  include/uapi/drm/drm.h | 17 +++++++++++++++++
>  1 file changed, 17 insertions(+)
> 
> diff --git a/include/uapi/drm/drm.h b/include/uapi/drm/drm.h
> index 87878aea4526..ec2b122cdcc5 100644
> --- a/include/uapi/drm/drm.h
> +++ b/include/uapi/drm/drm.h
> @@ -780,6 +780,8 @@ struct drm_get_cap {
>   * If set to 1, the DRM core will expose the stereo 3D capabilities of the
>   * monitor by advertising the supported 3D layouts in the flags of struct
>   * drm_mode_modeinfo. See ``DRM_MODE_FLAG_3D_*``.
> + *
> + * This capability is always supported starting from kernel version 3.13.

Does this mean for all DRM drivers, or is it just that the definition
of the cap is recognised but it still depends per-driver if it actually
supports it?

This is always the hard question for me to figure out, and the more
interesting one.

I think adding "for all drivers" would make things much more clear,
like in the other cases you mention "atomic-capable drivers".

>   */
>  #define DRM_CLIENT_CAP_STEREO_3D	1
>  
> @@ -788,6 +790,9 @@ struct drm_get_cap {
>   *
>   * If set to 1, the DRM core will expose all planes (overlay, primary, and
>   * cursor) to userspace.
> + *
> + * This capability has been introduced in kernel version 3.15. Starting from
> + * kernel version 3.17, this capability is always supported.
>   */
>  #define DRM_CLIENT_CAP_UNIVERSAL_PLANES  2
>  
> @@ -797,6 +802,13 @@ struct drm_get_cap {
>   * If set to 1, the DRM core will expose atomic properties to userspace. This
>   * implicitly enables &DRM_CLIENT_CAP_UNIVERSAL_PLANES and
>   * &DRM_CLIENT_CAP_ASPECT_RATIO.

Wait, why does atomic turn on aspect ratio? That's surprising,
since I wouldn't think that atomic depends on aspect ratio features.

> + *
> + * If the driver doesn't support atomic mode-setting, enabling this capability
> + * will fail with -EOPNOTSUPP.
> + *
> + * This capability has been introduced in kernel version 4.0. Starting from
> + * kernel version 4.2, this capability is always supported for atomic-capable
> + * drivers.
>   */
>  #define DRM_CLIENT_CAP_ATOMIC	3
>  
> @@ -805,6 +817,8 @@ struct drm_get_cap {
>   *
>   * If set to 1, the DRM core will provide aspect ratio information in modes.
>   * See ``DRM_MODE_FLAG_PIC_AR_*``.
> + *
> + * This capability is always supported starting from kernel version 4.18.
>   */
>  #define DRM_CLIENT_CAP_ASPECT_RATIO    4
>  
> @@ -814,6 +828,9 @@ struct drm_get_cap {
>   * If set to 1, the DRM core will expose special connectors to be used for
>   * writing back to memory the scene setup in the commit. The client must enable
>   * &DRM_CLIENT_CAP_ATOMIC first.
> + *
> + * This capability is always supported for atomic-capable drivers starting from
> + * kernel version 4.19.
>   */
>  #define DRM_CLIENT_CAP_WRITEBACK_CONNECTORS	5
>  

These are really nice additions to help people figure out which ones
they would be happy to require unconditionally in userspace.

I just hope this won't encourage anyone to be testing for kernel
version instead of these caps, though.

Anyway,

Acked-by: Pekka Paalanen <pekka.paalanen at collabora.com>


Thanks,
pq
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 833 bytes
Desc: OpenPGP digital signature
URL: <https://lists.freedesktop.org/archives/dri-devel/attachments/20210520/18192429/attachment.sig>