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

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

[Simon Ser]

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@emersion.fr>
Cc: Daniel Vetter <daniel@ffwll.ch>
Cc: Daniel Stone <daniels@collabora.com>
Cc: Pekka Paalanen <ppaalanen@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.
  */
 #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.
+ *
+ * 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
 
-- 
2.31.1

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

[Daniel Vetter]

On Tue, May 18, 2021 at 11:14:52AM +0000, Simon Ser 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@emersion.fr>
> Cc: Daniel Vetter <daniel@ffwll.ch>
> Cc: Daniel Stone <daniels@collabora.com>
> Cc: Pekka Paalanen <ppaalanen@gmail.com>

On the series:

Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>

btw your threading is busted.
-Daniel
> ---
>  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.
>   */
>  #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.
> + *
> + * 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
>  
> -- 
> 2.31.1
> 
> 

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch

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

[Daniel Stone]

Hi Simon,

On Tue, 18 May 2021 at 12:15, Simon Ser <contact@emersion.fr> wrote:
> The kernel versions including the following commits are referenced:
> [...]

Thanks a lot for writing this up! I trust your ability to drive git
log/blame/describe so didn't bother double-checking the version
numbers. So this is:
Acked-by: Daniel Stone <daniels@collabora.com>

Cheers,
Daniel

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

[Pekka Paalanen]

[-- Attachment #1: Type: text/plain, Size: 4199 bytes --]

On Tue, 18 May 2021 11:14:52 +0000
Simon Ser <contact@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@emersion.fr>
> Cc: Daniel Vetter <daniel@ffwll.ch>
> Cc: Daniel Stone <daniels@collabora.com>
> Cc: Pekka Paalanen <ppaalanen@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@collabora.com>


Thanks,
pq

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

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

[Simon Ser]

On Thursday, May 20th, 2021 at 10:17 AM, Pekka Paalanen <ppaalanen@gmail.com> wrote:

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

Good point, done.

> > @@ -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.

Yes. I guess the motivation was to make sure new user-space can deal with
these?