| Message ID | k52vYFBQ5ZO18TgZl3W8MgP6f4qu5Ncir7w-On8Dm0V2KTAcVkUoS7-IGPcvDJAXLsyJAUsD0QFJts3Dy0yWyHXVh85axrZkybh3MGGFhQc=@emersion.fr (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | [v2] drm: add docs for standard CRTC properties | expand |
On Thu, 21 May 2020 11:09:31 +0000 Simon Ser <contact@emersion.fr> wrote: > This patch adds docs for the ACTIVE and MODE_ID CRTC properties. > > Signed-off-by: Simon Ser <contact@emersion.fr> > Cc: Daniel Vetter <daniel.vetter@intel.com> > Cc: Ville Syrjala <ville.syrjala@linux.intel.com> > Cc: Pekka Paalanen <pekka.paalanen@collabora.co.uk> > Cc: Michel Dänzer <michel@daenzer.net> > Cc: Daniel Stone <daniel@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@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
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.
This patch adds docs for the ACTIVE and MODE_ID CRTC properties. Signed-off-by: Simon Ser <contact@emersion.fr> Cc: Daniel Vetter <daniel.vetter@intel.com> Cc: Ville Syrjala <ville.syrjala@linux.intel.com> Cc: Pekka Paalanen <pekka.paalanen@collabora.co.uk> Cc: Michel Dänzer <michel@daenzer.net> Cc: Daniel Stone <daniel@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(+)