[3/5] drm/docs: Document "scaling mode" property better

Commit Message

Daniel Vetter Feb. 19, 2018, 10:53 p.m. UTC

Move it out of the csv dungeon.

While at it add the missing link to the helper functions for setting
up the "panel rotation" property.

Also OCD how we list enum property values and their corresponding docs.
Going for a nest definition list seams cleanest, no need for also making
it an uordered list.

Cc: Sean Paul <[e-mail]>
Cc: Hans de Goede <[e-mail]>
Signed-off-by: Daniel Vetter <[e-mail]>
---
 Documentation/gpu/kms-properties.csv |  1 -
 drivers/gpu/drm/drm_connector.c      | 32 ++++++++++++++++++++++++++++----
 2 files changed, 28 insertions(+), 5 deletions(-)

Comments

Thierry Reding Feb. 20, 2018, 9:45 a.m. UTC | #1

On Mon, Feb 19, 2018 at 11:53:54PM +0100, Daniel Vetter wrote:
> Move it out of the csv dungeon.
> 
> While at it add the missing link to the helper functions for setting
> up the "panel rotation" property.
> 
> Also OCD how we list enum property values and their corresponding docs.
> Going for a nest definition list seams cleanest, no need for also making
> it an uordered list.
> 
> Cc: Sean Paul <[e-mail]>
> Cc: Hans de Goede <[e-mail]>
> Signed-off-by: Daniel Vetter <[e-mail]>
> ---
>  Documentation/gpu/kms-properties.csv |  1 -
>  drivers/gpu/drm/drm_connector.c      | 32 ++++++++++++++++++++++++++++----
>  2 files changed, 28 insertions(+), 5 deletions(-)

Reviewed-by: Thierry Reding <[e-mail]>

Patch

diff --git a/Documentation/gpu/kms-properties.csv b/Documentation/gpu/kms-properties.csv
index 927b65e14219..6b28b014cb7d 100644
--- a/Documentation/gpu/kms-properties.csv
+++ b/Documentation/gpu/kms-properties.csv
@@ -1,5 +1,4 @@ 
 Owner Module/Drivers,Group,Property Name,Type,Property Values,Object attached,Description/Restrictions
-,,“scaling mode”,ENUM,"{ ""None"", ""Full"", ""Center"", ""Full aspect"" }",Connector,"Supported by: amdgpu, gma500, i915, nouveau and radeon."
 ,DVI-I,“subconnector”,ENUM,"{ “Unknown”, “DVI-D”, “DVI-A” }",Connector,TBD
 ,,“select subconnector”,ENUM,"{ “Automatic”, “DVI-D”, “DVI-A” }",Connector,TBD
 ,TV,“subconnector”,ENUM,"{ ""Unknown"", ""Composite"", ""SVIDEO"", ""Component"", ""SCART"" }",Connector,TBD
diff --git a/drivers/gpu/drm/drm_connector.c b/drivers/gpu/drm/drm_connector.c
index 16b9c3810af2..b3cde897cd80 100644
--- a/drivers/gpu/drm/drm_connector.c
+++ b/drivers/gpu/drm/drm_connector.c
@@ -849,13 +849,13 @@  DRM_ENUM_NAME_FN(drm_get_content_protection_name, drm_cp_enum_list)
  *
  *	The value of this property can be one of the following:
  *
- *	- DRM_MODE_CONTENT_PROTECTION_UNDESIRED = 0
+ *	DRM_MODE_CONTENT_PROTECTION_UNDESIRED = 0
  *		The link is not protected, content is transmitted in the clear.
- *	- DRM_MODE_CONTENT_PROTECTION_DESIRED = 1
+ *	DRM_MODE_CONTENT_PROTECTION_DESIRED = 1
  *		Userspace has requested content protection, but the link is not
  *		currently protected. When in this state, kernel should enable
  *		Content Protection as soon as possible.
- *	- DRM_MODE_CONTENT_PROTECTION_ENABLED = 2
+ *	DRM_MODE_CONTENT_PROTECTION_ENABLED = 2
  *		Userspace has requested content protection, and the link is
  *		protected. Only the driver can set the property to this value.
  *		If userspace attempts to set to ENABLED, kernel will return
@@ -889,7 +889,31 @@  DRM_ENUM_NAME_FN(drm_get_content_protection_name, drm_cp_enum_list)
  *	INPUT_PROP_DIRECT) will still map 1:1 to the actual LCD panel
  *	coordinates, so if userspace rotates the picture to adjust for
  *	the orientation it must also apply the same transformation to the
- *	touchscreen input coordinates.
+ *	touchscreen input coordinates. This property is initialized by calling
+ *	drm_connector_init_panel_orientation_property().
+ *
+ * scaling mode:
+ *	This property defines how a non-native mode is upscaled to the native
+ *	mode of an LCD panel:
+ *
+ *	None:
+ *		No upscaling happens, scaling is left to the panel. Not all
+ *		drivers expose this mode.
+ *	Full:
+ *		The output is upscaled to the full resolution of the panel,
+ *		ignoring the aspect ratio.
+ *	Center:
+ *		No upscaling happens, the output is centered within the native
+ *		resolution the panel.
+ *	Full aspect:
+ *		The output is upscaled to maximize either the width or height
+ *		while retaining the aspect ratio.
+ *
+ *	This property should be set up by calling
+ *	drm_connector_attach_scaling_mode_property(). Note that drivers
+ *	can also expose this property to external outputs, in which case they
+ *	must support "None", which should be the default (since external screens
+ *	have a built-in scaler).
  */
 
 int drm_connector_create_standard_properties(struct drm_device *dev)