[PATCH] drm/atomic-helper: Make zpos property kerneldoc less misleading

[PATCH] drm/atomic-helper: Make zpos property kerneldoc less misleading

[Thierry Reding]

From: Thierry Reding <treding@nvidia.com>

kerneldoc for drm_plane_create_zpos_property() says that the DRM core
will automatically calculate the normalized zpos values, but it doesn't
actually do that. Instead, drivers are supposed to explicitly call the
drm_atomic_normalize_zpos() function. Change the kerneldoc comment to
reflect that.

Signed-off-by: Thierry Reding <treding@nvidia.com>
---
 drivers/gpu/drm/drm_blend.c | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/drivers/gpu/drm/drm_blend.c b/drivers/gpu/drm/drm_blend.c
index 2e5e089dd912..4c62dff14893 100644
--- a/drivers/gpu/drm/drm_blend.c
+++ b/drivers/gpu/drm/drm_blend.c
@@ -214,9 +214,11 @@ EXPORT_SYMBOL(drm_rotation_simplify);
  * This function initializes generic mutable zpos property and enables support
  * for it in drm core. Drivers can then attach this property to planes to enable
  * support for configurable planes arrangement during blending operation.
- * Once mutable zpos property has been enabled, the DRM core will automatically
- * calculate &drm_plane_state.normalized_zpos values. Usually min should be set
- * to 0 and max to maximal number of planes for given crtc - 1.
+ * Drivers that attach a mutable zpos property to any plane should call the
+ * drm_atomic_normalize_zpos() helper during their implementation of
+ * &drm_mode_config_funcs.atomic_check(), which will update the normalized zpos
+ * values and store them in &drm_plane_state.normalized_zpos. Usually min
+ * should be set to 0 and max to maximal number of planes for given crtc - 1.
  *
  * If zpos of some planes cannot be changed (like fixed background or
  * cursor/topmost planes), driver should adjust min/max values and assign those
-- 
2.15.0

_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH] drm/atomic-helper: Make zpos property kerneldoc less misleading

[Daniel Vetter]

On Mon, Nov 20, 2017 at 09:16:39AM +0100, Thierry Reding wrote:
> From: Thierry Reding <treding@nvidia.com>
> 
> kerneldoc for drm_plane_create_zpos_property() says that the DRM core
> will automatically calculate the normalized zpos values, but it doesn't
> actually do that. Instead, drivers are supposed to explicitly call the
> drm_atomic_normalize_zpos() function. Change the kerneldoc comment to
> reflect that.
> 
> Signed-off-by: Thierry Reding <treding@nvidia.com>
> ---
>  drivers/gpu/drm/drm_blend.c | 8 +++++---
>  1 file changed, 5 insertions(+), 3 deletions(-)
> 
> diff --git a/drivers/gpu/drm/drm_blend.c b/drivers/gpu/drm/drm_blend.c
> index 2e5e089dd912..4c62dff14893 100644
> --- a/drivers/gpu/drm/drm_blend.c
> +++ b/drivers/gpu/drm/drm_blend.c
> @@ -214,9 +214,11 @@ EXPORT_SYMBOL(drm_rotation_simplify);
>   * This function initializes generic mutable zpos property and enables support
>   * for it in drm core. Drivers can then attach this property to planes to enable
>   * support for configurable planes arrangement during blending operation.
> - * Once mutable zpos property has been enabled, the DRM core will automatically
> - * calculate &drm_plane_state.normalized_zpos values. Usually min should be set
> - * to 0 and max to maximal number of planes for given crtc - 1.
> + * Drivers that attach a mutable zpos property to any plane should call the
> + * drm_atomic_normalize_zpos() helper during their implementation of
> + * &drm_mode_config_funcs.atomic_check(), which will update the normalized zpos
> + * values and store them in &drm_plane_state.normalized_zpos. Usually min
> + * should be set to 0 and max to maximal number of planes for given crtc - 1.

Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>

Maybe reference the commit that changed the code and forgot to update the
kerneldoc in the commit message.
-Daniel

>   *
>   * If zpos of some planes cannot be changed (like fixed background or
>   * cursor/topmost planes), driver should adjust min/max values and assign those
> -- 
> 2.15.0
> 

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

[PATCH v2] drm/atomic-helper: Make zpos property kerneldoc less misleading

[Thierry Reding]

From: Thierry Reding <treding@nvidia.com>

kerneldoc for drm_plane_create_zpos_property() says that the DRM core
will automatically calculate the normalized zpos values, but it doesn't
actually do that anymore since commit 38d868e41c4b ("drm: Don't force
all planes to be added to the state due to zpos"). Instead, drivers are
supposed to explicitly call the drm_atomic_normalize_zpos() function.
Change the kerneldoc comment to reflect that.

v2: reference the commit that introduced the kerneldoc unclarity

Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: Thierry Reding <treding@nvidia.com>
---
 drivers/gpu/drm/drm_blend.c | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/drivers/gpu/drm/drm_blend.c b/drivers/gpu/drm/drm_blend.c
index 2e5e089dd912..4c62dff14893 100644
--- a/drivers/gpu/drm/drm_blend.c
+++ b/drivers/gpu/drm/drm_blend.c
@@ -214,9 +214,11 @@ EXPORT_SYMBOL(drm_rotation_simplify);
  * This function initializes generic mutable zpos property and enables support
  * for it in drm core. Drivers can then attach this property to planes to enable
  * support for configurable planes arrangement during blending operation.
- * Once mutable zpos property has been enabled, the DRM core will automatically
- * calculate &drm_plane_state.normalized_zpos values. Usually min should be set
- * to 0 and max to maximal number of planes for given crtc - 1.
+ * Drivers that attach a mutable zpos property to any plane should call the
+ * drm_atomic_normalize_zpos() helper during their implementation of
+ * &drm_mode_config_funcs.atomic_check(), which will update the normalized zpos
+ * values and store them in &drm_plane_state.normalized_zpos. Usually min
+ * should be set to 0 and max to maximal number of planes for given crtc - 1.
  *
  * If zpos of some planes cannot be changed (like fixed background or
  * cursor/topmost planes), driver should adjust min/max values and assign those
-- 
2.15.0

_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel