[PATCH v2] drm: add docs for standard CRTC properties

[Pekka Paalanen]

On Thu, 21 May 2020 11:09:31 +0000
Simon Ser <contact at emersion.fr> wrote:

> This patch adds docs for the ACTIVE and MODE_ID CRTC properties.
> 
> Signed-off-by: Simon Ser <contact at emersion.fr>
> Cc: Daniel Vetter <daniel.vetter at intel.com>
> Cc: Ville Syrjala <ville.syrjala at linux.intel.com>
> Cc: Pekka Paalanen <pekka.paalanen at collabora.co.uk>
> Cc: Michel Dänzer <michel at daenzer.net>
> Cc: Daniel Stone <daniel at fooishbar.org>
> ---
> 
> Thanks for the review Daniel! I rejiggered your suggestions a little to
> move some ACTIVE bits into the ACTIVE description.
> 
>  Documentation/gpu/drm-kms.rst |  6 ++++++
>  drivers/gpu/drm/drm_crtc.c    | 27 +++++++++++++++++++++++++++
>  2 files changed, 33 insertions(+)
> 
> diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst
> index 397314d08f77..975cfeb8a353 100644
> --- a/Documentation/gpu/drm-kms.rst
> +++ b/Documentation/gpu/drm-kms.rst
> @@ -460,6 +460,12 @@ HDMI Specific Connector Properties
>  .. kernel-doc:: drivers/gpu/drm/drm_connector.c
>     :doc: HDMI connector properties
>  
> +Standard CRTC Properties
> +------------------------
> +
> +.. kernel-doc:: drivers/gpu/drm/drm_crtc.c
> +   :doc: standard CRTC properties
> +
>  Plane Composition Properties
>  ----------------------------
>  
> diff --git a/drivers/gpu/drm/drm_crtc.c b/drivers/gpu/drm/drm_crtc.c
> index 4936e1080e41..fafb8d3c3235 100644
> --- a/drivers/gpu/drm/drm_crtc.c
> +++ b/drivers/gpu/drm/drm_crtc.c
> @@ -204,6 +204,33 @@ struct dma_fence *drm_crtc_create_fence(struct drm_crtc *crtc)
>  	return fence;
>  }
>  
> +/**
> + * DOC: standard CRTC properties
> + *
> + * DRM CRTCs have a few standardized properties:
> + *
> + * ACTIVE:
> + * 	Atomic property for setting the power state of the CRTC. When set to 1 the
> + * 	CRTC will actively display content. When set to 0 the CRTC will be powered
> + * 	off. There is no expectation that user-space will reset CRTC resources like
> + * 	the mode and planes when setting ACTIVE to 0.
> + *
> + * 	User-space can rely on an ACTIVE change to 1 to never fail an atomic test
> + * 	as long as no other property has changed. If a change to ACTIVE fails an
> + * 	atomic test, this is a driver bug. For this reason setting ACTIVE to 0 must
> + * 	not release internal resources (like reserved memory bandwidth or clock
> + * 	generators).
> + *
> + * 	Note that the legacy DPMS property on connectors is internally routed to
> + * 	control this property for atomic drivers.
> + * MODE_ID:
> + * 	Atomic property for setting the CRTC display timings. The value is the ID
> + * 	of a blob containing the DRM mode info. To disable the CRTC, user-space
> + * 	must set this property to 0.
> + *
> + * 	Setting MODE_ID to 0 will release reserved resources for the CRTC.
> + */
> +
>  /**
>   * drm_crtc_init_with_planes - Initialise a new CRTC object with
>   *    specified primary and cursor planes.

Really nice.

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

And the patch 1/2 R-b as well.

FWIW, as I cannot really check the kernel code is like this, but it
totally makes sense from userspace side. I didn't even know these
little details before.


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/20200525/b42df6c5/attachment.sig>