[PATCH 3/3] drm/doc: Document legacy_cursor_update better

[Daniel Vetter]

On Fri, Oct 23, 2020 at 02:39:25PM +0200, Daniel Vetter wrote:
> It's the horror and shouldn't be used. Realized we're not clear on
> this in a discussion with Rob about what msm is doing to better
> support async commits.
> 
> v2: Refine existing todo item to include this (Thomas)
> 
> Cc: Sean Paul <sean at poorly.run>
> Cc: Rob Clark <robdclark at gmail.com>
> Signed-off-by: Daniel Vetter <daniel.vetter at intel.com>
> Cc: Maarten Lankhorst <maarten.lankhorst at linux.intel.com>
> Cc: Maxime Ripard <mripard at kernel.org>
> Cc: Thomas Zimmermann <tzimmermann at suse.de>
> Cc: David Airlie <airlied at linux.ie>
> Cc: Daniel Vetter <daniel at ffwll.ch>

Pushed this one with Rob's irc-ack, since the functional changes will take
a bit longer to figure out.
-Daniel

> ---
>  Documentation/gpu/todo.rst |  4 ++++
>  include/drm/drm_atomic.h   | 12 +++++++++++-
>  2 files changed, 15 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/gpu/todo.rst b/Documentation/gpu/todo.rst
> index 700637e25ecd..6b224ef14455 100644
> --- a/Documentation/gpu/todo.rst
> +++ b/Documentation/gpu/todo.rst
> @@ -105,6 +105,10 @@ converted over to the new infrastructure.
>  One issue with the helpers is that they require that drivers handle completion
>  events for atomic commits correctly. But fixing these bugs is good anyway.
>  
> +Somewhat related is the legacy_cursor_update hack, which should be replaced with
> +the new atomic_async_check/commit functionality in the helpers in drivers that
> +still look at that flag.
> +
>  Contact: Daniel Vetter, respective driver maintainers
>  
>  Level: Advanced
> diff --git a/include/drm/drm_atomic.h b/include/drm/drm_atomic.h
> index d07c851d255b..413fd0ca56a8 100644
> --- a/include/drm/drm_atomic.h
> +++ b/include/drm/drm_atomic.h
> @@ -308,7 +308,6 @@ struct __drm_private_objs_state {
>   * struct drm_atomic_state - the global state object for atomic updates
>   * @ref: count of all references to this state (will not be freed until zero)
>   * @dev: parent DRM device
> - * @legacy_cursor_update: hint to enforce legacy cursor IOCTL semantics
>   * @async_update: hint for asynchronous plane update
>   * @planes: pointer to array of structures with per-plane data
>   * @crtcs: pointer to array of CRTC pointers
> @@ -336,6 +335,17 @@ struct drm_atomic_state {
>  	 * drm_atomic_crtc_needs_modeset().
>  	 */
>  	bool allow_modeset : 1;
> +	/**
> +	 * @legacy_cursor_update:
> +	 *
> +	 * Hint to enforce legacy cursor IOCTL semantics.
> +	 *
> +	 * WARNING: This is thoroughly broken and pretty much impossible to
> +	 * implement correctly. Drivers must ignore this and should instead
> +	 * implement &drm_plane_helper_funcs.atomic_async_check and
> +	 * &drm_plane_helper_funcs.atomic_async_commit hooks. New users of this
> +	 * flag are not allowed.
> +	 */
>  	bool legacy_cursor_update : 1;
>  	bool async_update : 1;
>  	/**
> -- 
> 2.28.0
> 

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch