From 3100f2d24bf2b143d2d150e1770b1c5142838f3a Mon Sep 17 00:00:00 2001
From: Simon Ser <contact@emersion.fr>
Date: Thu, 21 May 2020 11:09:31 +0000
Subject: drm: add docs for standard CRTC properties
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Git-commit: e954f77f6330028ced7bac4ad22ea69ed64e5725
Patch-mainline: v5.9-rc1
References: jsc#SLE-12680, jsc#SLE-12880, jsc#SLE-12882, jsc#SLE-12883, jsc#SLE-13496, jsc#SLE-15322
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>
Reviewed-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Link: https://patchwork.freedesktop.org/patch/msgid/k52vYFBQ5ZO18TgZl3W8MgP6f4qu5Ncir7w-On8Dm0V2KTAcVkUoS7-IGPcvDJAXLsyJAUsD0QFJts3Dy0yWyHXVh85axrZkybh3MGGFhQc=@emersion.fr
Signed-off-by: Patrik Jakobsson <pjakobsson@suse.de>
---
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..f1216088f65f 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.
--
2.29.2