[PATCH v2] drm: document connector margin properties

[PATCH v2] drm: document connector margin properties

[Simon Ser]

Add docs for "{left,right,top,bottom} margin" properties.

v2:
- Mention the purpose: mitigate underscan on TVs
- Move out of analog TV section into standard props (Pekka)
- Mention HDMI AVI InfoFrames (Pekka, Ville)

Signed-off-by: Simon Ser <contact@emersion.fr>
Cc: Maxime Ripard <maxime@cerno.tech>
Cc: Daniel Vetter <daniel@ffwll.ch>
Cc: Pekka Paalanen <ppaalanen@gmail.com>
Cc: Noralf Trønnes <noralf@tronnes.org>
Cc: Mateusz Kwiatkowski <kfyatek+publicgit@gmail.com>
Cc: Ville Syrjälä <ville.syrjala@linux.intel.com>
---
 drivers/gpu/drm/drm_connector.c | 18 ++++++++++++++----
 1 file changed, 14 insertions(+), 4 deletions(-)

diff --git a/drivers/gpu/drm/drm_connector.c b/drivers/gpu/drm/drm_connector.c
index ffd65eddce42..a180f541736a 100644
--- a/drivers/gpu/drm/drm_connector.c
+++ b/drivers/gpu/drm/drm_connector.c
@@ -1446,6 +1446,20 @@ static const struct drm_prop_enum_list dp_colorspaces[] = {
  *	a firmware handled hotkey. Therefor userspace must not include the
  *	privacy-screen sw-state in an atomic commit unless it wants to change
  *	its value.
+ *
+ * left margin, right margin, top margin, bottom margin:
+ *	Add margins to the connector's viewport. This is typically used to
+ *	mitigate underscan on TVs.
+ *
+ *	The value is the size in pixels of the black border which will be
+ *	added. The attached CRTC's content will be scaled to fill the whole
+ *	area inside the margin.
+ *
+ *	The margins configuration might be sent to the sink, e.g. via HDMI AVI
+ *	InfoFrames.
+ *
+ *	Drivers can set up these properties by calling
+ *	drm_mode_create_tv_margin_properties().
  */
 
 int drm_connector_create_standard_properties(struct drm_device *dev)
@@ -1590,10 +1604,6 @@ EXPORT_SYMBOL(drm_connector_attach_dp_subconnector_property);
 
 /*
  * TODO: Document the properties:
- *   - left margin
- *   - right margin
- *   - top margin
- *   - bottom margin
  *   - brightness
  *   - contrast
  *   - flicker reduction
-- 
2.39.2

Re: [PATCH v2] drm: document connector margin properties

[Ville Syrjälä]

On Tue, Feb 28, 2023 at 12:32:04PM +0000, Simon Ser wrote:
> Add docs for "{left,right,top,bottom} margin" properties.
> 
> v2:
> - Mention the purpose: mitigate underscan on TVs
> - Move out of analog TV section into standard props (Pekka)
> - Mention HDMI AVI InfoFrames (Pekka, Ville)
> 
> Signed-off-by: Simon Ser <contact@emersion.fr>
> Cc: Maxime Ripard <maxime@cerno.tech>
> Cc: Daniel Vetter <daniel@ffwll.ch>
> Cc: Pekka Paalanen <ppaalanen@gmail.com>
> Cc: Noralf Trønnes <noralf@tronnes.org>
> Cc: Mateusz Kwiatkowski <kfyatek+publicgit@gmail.com>
> Cc: Ville Syrjälä <ville.syrjala@linux.intel.com>
> ---
>  drivers/gpu/drm/drm_connector.c | 18 ++++++++++++++----
>  1 file changed, 14 insertions(+), 4 deletions(-)
> 
> diff --git a/drivers/gpu/drm/drm_connector.c b/drivers/gpu/drm/drm_connector.c
> index ffd65eddce42..a180f541736a 100644
> --- a/drivers/gpu/drm/drm_connector.c
> +++ b/drivers/gpu/drm/drm_connector.c
> @@ -1446,6 +1446,20 @@ static const struct drm_prop_enum_list dp_colorspaces[] = {
>   *	a firmware handled hotkey. Therefor userspace must not include the
>   *	privacy-screen sw-state in an atomic commit unless it wants to change
>   *	its value.
> + *
> + * left margin, right margin, top margin, bottom margin:
> + *	Add margins to the connector's viewport. This is typically used to
> + *	mitigate underscan on TVs.

"used to mitigate overscan" or "used to underscan" would make
more sense to me.

> + *
> + *	The value is the size in pixels of the black border which will be
> + *	added. The attached CRTC's content will be scaled to fill the whole
> + *	area inside the margin.

Dunno if there should be something even more explicit here
about the CRTCs viewport/canvas/<whatever you call it> size
remaining unchaned, ie. still 'hdisplay x vdisplay'?

Another very open question is how these would interact with
the 'scaling mode' property/connectors that already scale
the passed in mode to whatever fixed size the panel needs.
In my i915 patches I totally sidestepped that question by
not registering the margin properties for eDP at all.

-- 
Ville Syrjälä
Intel

Re: [PATCH v2] drm: document connector margin properties

[Pekka Paalanen]

[-- Attachment #1: Type: text/plain, Size: 2375 bytes --]

On Tue, 28 Feb 2023 12:32:04 +0000
Simon Ser <contact@emersion.fr> wrote:

> Add docs for "{left,right,top,bottom} margin" properties.
> 
> v2:
> - Mention the purpose: mitigate underscan on TVs
> - Move out of analog TV section into standard props (Pekka)
> - Mention HDMI AVI InfoFrames (Pekka, Ville)
> 
> Signed-off-by: Simon Ser <contact@emersion.fr>
> Cc: Maxime Ripard <maxime@cerno.tech>
> Cc: Daniel Vetter <daniel@ffwll.ch>
> Cc: Pekka Paalanen <ppaalanen@gmail.com>
> Cc: Noralf Trønnes <noralf@tronnes.org>
> Cc: Mateusz Kwiatkowski <kfyatek+publicgit@gmail.com>
> Cc: Ville Syrjälä <ville.syrjala@linux.intel.com>
> ---
>  drivers/gpu/drm/drm_connector.c | 18 ++++++++++++++----
>  1 file changed, 14 insertions(+), 4 deletions(-)
> 
> diff --git a/drivers/gpu/drm/drm_connector.c b/drivers/gpu/drm/drm_connector.c
> index ffd65eddce42..a180f541736a 100644
> --- a/drivers/gpu/drm/drm_connector.c
> +++ b/drivers/gpu/drm/drm_connector.c
> @@ -1446,6 +1446,20 @@ static const struct drm_prop_enum_list dp_colorspaces[] = {
>   *	a firmware handled hotkey. Therefor userspace must not include the
>   *	privacy-screen sw-state in an atomic commit unless it wants to change
>   *	its value.
> + *
> + * left margin, right margin, top margin, bottom margin:
> + *	Add margins to the connector's viewport. This is typically used to
> + *	mitigate underscan on TVs.

I think it's overscan: scanning over and beyond the phosphor grid.

> + *
> + *	The value is the size in pixels of the black border which will be
> + *	added. The attached CRTC's content will be scaled to fill the whole
> + *	area inside the margin.
> + *
> + *	The margins configuration might be sent to the sink, e.g. via HDMI AVI
> + *	InfoFrames.
> + *
> + *	Drivers can set up these properties by calling
> + *	drm_mode_create_tv_margin_properties().
>   */
>  
>  int drm_connector_create_standard_properties(struct drm_device *dev)
> @@ -1590,10 +1604,6 @@ EXPORT_SYMBOL(drm_connector_attach_dp_subconnector_property);
>  
>  /*
>   * TODO: Document the properties:
> - *   - left margin
> - *   - right margin
> - *   - top margin
> - *   - bottom margin
>   *   - brightness
>   *   - contrast
>   *   - flicker reduction

With that one typo'ish fixed:
Acked-by: Pekka Paalanen <pekka.paalanen@collabora.com>


Thanks,
pq

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]