drm: document standard connector properties

Submitted by Daniel Vetter on Nov. 17, 2016, 7:38 a.m.

Details

Message ID 20161117073823.32567-1-daniel.vetter@ffwll.ch
State New
Headers show
Series "drm: document standard connector properties" ( rev: 2 ) in DRI devel

Not browsing as part of any series.

Commit Message

Daniel Vetter Nov. 17, 2016, 7:38 a.m.
There's a really big pile of additional connector properties, a lot of
them standardized. But they're all for specific outputs (panels, TV,
scaling, ...) so I left them out for now since this is enough for a
start.

I typed this to give Manasi a place to add her new link status
property documentation.

v2: forgot to git add all the bits (Manasi).

Cc: Manasi Navare <manasi.d.navare@intel.com>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
---
 Documentation/gpu/drm-kms.rst   |  6 ++++++
 drivers/gpu/drm/drm_connector.c | 42 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 48 insertions(+)

Patch hide | download patch | download mbox

diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst
index 568f3c2b6e46..f19757b1736a 100644
--- a/Documentation/gpu/drm-kms.rst
+++ b/Documentation/gpu/drm-kms.rst
@@ -260,6 +260,12 @@  Property Types and Blob Property Support
 .. kernel-doc:: drivers/gpu/drm/drm_property.c
    :export:
 
+Standard Connector Properties
+-----------------------------
+
+.. kernel-doc:: drivers/gpu/drm/drm_connector.c
+   :doc: standard connector properties
+
 Plane Composition Properties
 ----------------------------
 
diff --git a/drivers/gpu/drm/drm_connector.c b/drivers/gpu/drm/drm_connector.c
index b5c6a8ee831e..385efbc6a9ef 100644
--- a/drivers/gpu/drm/drm_connector.c
+++ b/drivers/gpu/drm/drm_connector.c
@@ -588,6 +588,48 @@  static const struct drm_prop_enum_list drm_tv_subconnector_enum_list[] = {
 DRM_ENUM_NAME_FN(drm_get_tv_subconnector_name,
 		 drm_tv_subconnector_enum_list)
 
+/**
+ * DOC: standard connector properties
+ *
+ * DRM connectors have a few standardized properties:
+ *
+ * EDID:
+ * 	Blob property which contains the current EDID read from the sink. This
+ * 	is useful to parse sink identification information like vendor, model
+ * 	and serial. Drivers should update this property by calling
+ * 	drm_mode_connector_update_edid_property(), usually after having parsed
+ * 	the EDID using drm_add_edid_modes(). Userspace cannot change this
+ * 	property.
+ * DPMS:
+ * 	Legacy property for setting the power state of the connector. For atomic
+ * 	drivers this is only provided for backwards compatibility with existing
+ * 	drivers, it remaps to controlling the "ACTIVE" property on the CRTC the
+ * 	connector is linked to. Drivers should never set this property directly,
+ * 	it is handled by the DRM core by calling the ->dpms() callback in
+ * 	&drm_connector_funcs. Atomic drivers should implement this hook using
+ * 	drm_atomic_helper_connector_dpms(). This is the only property standard
+ * 	connector property that userspace can change.
+ * PATH:
+ * 	Connector path property to identify how this sink is physically
+ * 	connected. Used by DP MST. This should be set by calling
+ * 	drm_mode_connector_set_path_property(), in the case of DP MST with the
+ * 	path property the MST manager created. Userspace cannot change this
+ * 	property.
+ * TILE:
+ * 	Connector tile group property to indicate how a set of DRM connector
+ * 	compose together into one logical screen. This is used by both high-res
+ * 	external screens (often only using a single cable, but exposing multiple
+ * 	DP MST sinks), or high-res integrated panels (like dual-link DSI).
+ * 	Drivers should update this property using
+ * 	drm_mode_connector_set_tile_property(). Userspace cannot change this
+ * 	property.
+ *
+ * Connectors also have one standardized atomic property:
+ *
+ * CRTC_ID:
+ * 	Mode object ID of the &drm_crtc this connector should be connected to.
+ */
+
 int drm_connector_create_standard_properties(struct drm_device *dev)
 {
 	struct drm_property *prop;

Comments

On 11/17/2016 01:08 PM, Daniel Vetter wrote:
> There's a really big pile of additional connector properties, a lot of
> them standardized. But they're all for specific outputs (panels, TV,
> scaling, ...) so I left them out for now since this is enough for a
> start.
>
> I typed this to give Manasi a place to add her new link status
> property documentation.
>
> v2: forgot to git add all the bits (Manasi).
>
> Cc: Manasi Navare <manasi.d.navare@intel.com>
> Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
> ---
>  Documentation/gpu/drm-kms.rst   |  6 ++++++
>  drivers/gpu/drm/drm_connector.c | 42 +++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 48 insertions(+)
>
> diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst
> index 568f3c2b6e46..f19757b1736a 100644
> --- a/Documentation/gpu/drm-kms.rst
> +++ b/Documentation/gpu/drm-kms.rst
> @@ -260,6 +260,12 @@ Property Types and Blob Property Support
>  .. kernel-doc:: drivers/gpu/drm/drm_property.c
>     :export:
>
> +Standard Connector Properties
> +-----------------------------
> +
> +.. kernel-doc:: drivers/gpu/drm/drm_connector.c
> +   :doc: standard connector properties
> +
>  Plane Composition Properties
>  ----------------------------
>
> diff --git a/drivers/gpu/drm/drm_connector.c b/drivers/gpu/drm/drm_connector.c
> index b5c6a8ee831e..385efbc6a9ef 100644
> --- a/drivers/gpu/drm/drm_connector.c
> +++ b/drivers/gpu/drm/drm_connector.c
> @@ -588,6 +588,48 @@ static const struct drm_prop_enum_list drm_tv_subconnector_enum_list[] = {
>  DRM_ENUM_NAME_FN(drm_get_tv_subconnector_name,
>  		 drm_tv_subconnector_enum_list)
>
> +/**
> + * DOC: standard connector properties
> + *
> + * DRM connectors have a few standardized properties:
> + *
> + * EDID:
> + * 	Blob property which contains the current EDID read from the sink. This
> + * 	is useful to parse sink identification information like vendor, model
> + * 	and serial. Drivers should update this property by calling
> + * 	drm_mode_connector_update_edid_property(), usually after having parsed
> + * 	the EDID using drm_add_edid_modes(). Userspace cannot change this
> + * 	property.
> + * DPMS:
> + * 	Legacy property for setting the power state of the connector. For atomic
> + * 	drivers this is only provided for backwards compatibility with existing
> + * 	drivers, it remaps to controlling the "ACTIVE" property on the CRTC the
> + * 	connector is linked to. Drivers should never set this property directly,
> + * 	it is handled by the DRM core by calling the ->dpms() callback in
> + * 	&drm_connector_funcs. Atomic drivers should implement this hook using
> + * 	drm_atomic_helper_connector_dpms(). This is the only property standard
> + * 	connector property that userspace can change.
> + * PATH:
> + * 	Connector path property to identify how this sink is physically
> + * 	connected. Used by DP MST. This should be set by calling
> + * 	drm_mode_connector_set_path_property(), in the case of DP MST with the
> + * 	path property the MST manager created. Userspace cannot change this
> + * 	property.
> + * TILE:
> + * 	Connector tile group property to indicate how a set of DRM connector
> + * 	compose together into one logical screen. This is used by both high-res
> + * 	external screens (often only using a single cable, but exposing multiple
> + * 	DP MST sinks), or high-res integrated panels (like dual-link DSI).
> + * 	Drivers should update this property using
> + * 	drm_mode_connector_set_tile_property(). Userspace cannot change this
> + * 	property.

This contradicts the comment on @tile_blob_ptr in drm_connector.h a bit w.r.t
high-res panels.

Maybe the comment here can say "...or high-res integrated panels which aren't
genlocked"


Archit

> + *
> + * Connectors also have one standardized atomic property:
> + *
> + * CRTC_ID:
> + * 	Mode object ID of the &drm_crtc this connector should be connected to.
> + */
> +
>  int drm_connector_create_standard_properties(struct drm_device *dev)
>  {
>  	struct drm_property *prop;
>