[PATCH 5/5] drm/todo: Add entry to rename drm_atomic_state

[Daniel Vetter]

On Mon, Dec 04, 2023 at 01:17:07PM +0100, Maxime Ripard wrote:
> The name of the structure drm_atomic_state is confusing. Let's add an
> entry to our todo list to rename it.
> 
> Signed-off-by: Maxime Ripard <mripard at kernel.org>
> ---
>  Documentation/gpu/todo.rst | 18 ++++++++++++++++++
>  1 file changed, 18 insertions(+)
> 
> diff --git a/Documentation/gpu/todo.rst b/Documentation/gpu/todo.rst
> index b62c7fa0c2bc..fe95aea89d67 100644
> --- a/Documentation/gpu/todo.rst
> +++ b/Documentation/gpu/todo.rst
> @@ -120,6 +120,24 @@ Contact: Daniel Vetter, respective driver maintainers
>  
>  Level: Advanced
>  
> +Rename drm_atomic_state
> +-----------------------
> +
> +The KMS framework uses two slightly different definitions for the ``state``
> +concept. For a given object (plane, CRTC, encoder, etc., so
> +``drm_$OBJECT_state``), the state is the entire state of that object. However,
> +at the device level, ``drm_atomic_state`` refers to a state update for a
> +limited number of objects.

That's a very generous description of my screw-up of calling a commit a
state and making a big mess out of a lot of concepts :-)

> +
> +The state isn't the entire device state anymore, but only the full state of

s/anymore// since it was always meant to be an incremental/partial
update/commit structure.

> +some objects in that device. This is confusing to newcomers, and
> +``drm_atomic_state`` should be renamed to something clearer like
> +``drm_atomic_update``.

My choice would be drm_atomic_commit, because that's what we're calling
these everywhere else in the code. See drm_crtc_commit for the per-crtc
tracking thing of a drm_atomic_commit. If you want update, there's quite a
lot of other things we also need to rename to the _update suffix.

Also this should have some pointers to the functions that need adjusting,
like drm_atomic_state_alloc|get/put/init/.... since without also renaming
those this is just going to create even more confusion.

With my comments addressed:

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

> +
> +Contact: Maxime Ripard <mripard at kernel.org>
> +
> +Level: Advanced
> +
>  Fallout from atomic KMS
>  -----------------------
>  
> -- 
> 2.43.0
> 

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