[PATCH v5 01/19] drm/atomic: Document atomic commit lifetime

[Thomas Zimmermann]

Hi,

I left a number of comments on the style of writing. Apart from that, 
it's great to have the lifetime documented.

Am 19.05.26 um 11:01 schrieb Maxime Ripard:
> How drm_atomic_commit and the various entity structures are allocated
> and freed isn't really trivial. Document it.
>
> Reviewed-by: Laurent Pinchart <laurent.pinchart+renesas at ideasonboard.com>
> Signed-off-by: Maxime Ripard <mripard at kernel.org>
> ---
>   Documentation/gpu/drm-kms.rst |  6 +++++
>   drivers/gpu/drm/drm_atomic.c  | 58 +++++++++++++++++++++++++++++++++++++++++++
>   2 files changed, 64 insertions(+)
>
> diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst
> index d22817fdf9aa..36d76e391074 100644
> --- a/Documentation/gpu/drm-kms.rst
> +++ b/Documentation/gpu/drm-kms.rst
> @@ -282,10 +282,16 @@ structure, ordering of committing state changes to hardware is sequenced using
>   :c:type:`struct drm_crtc_commit <drm_crtc_commit>`.
>   
>   Read on in this chapter, and also in :ref:`drm_atomic_helper` for more detailed
>   coverage of specific topics.
>   
> +Atomic State Lifetime
> +---------------------
> +
> +.. kernel-doc:: drivers/gpu/drm/drm_atomic.c
> +   :doc: state lifetime
> +
>   Handling Driver Private State
>   -----------------------------
>   
>   .. kernel-doc:: drivers/gpu/drm/drm_atomic.c
>      :doc: handling driver private state
> diff --git a/drivers/gpu/drm/drm_atomic.c b/drivers/gpu/drm/drm_atomic.c
> index 170de30c28ae..d98586d89bbe 100644
> --- a/drivers/gpu/drm/drm_atomic.c
> +++ b/drivers/gpu/drm/drm_atomic.c
> @@ -45,10 +45,68 @@
>   #include <drm/drm_colorop.h>
>   
>   #include "drm_crtc_internal.h"
>   #include "drm_internal.h"
>   
> +/**
> + * DOC: state lifetime
> + *
> + * &struct drm_atomic_commit represents an update to video pipeline

I'd say 'modeset pipeline'. Video sounds too much like V4L.

> + * state. It's a transient object that holds a state update as a
> + * collection of pointers to individual objects' states. &struct
> + * drm_atomic_commit has a much shorter lifetime than the objects'
> + * states, since it's only allocated while preparing, checking or
> + * committing the update, while object states are allocated when
> + * preparing the update and kept alive as long as they are active in the
> + * device.
> + *
> + * Their respective lifetimes are:
> + *
> + * - at reset time, the object reset implementation will allocate a new
> + *   default state and will store it in the object state pointer.

Using present seems more natural, e.g., 'allocates' and 'stores'

> + *
> + * - whenever a new update is needed:
> + *
> + *   + A new &struct drm_atomic_commit is allocated using
> + *     drm_atomic_commit_alloc().

Active form: "drm_atomic_commit_alloc() allocates a new instance of 
struct drm_atomic_commit."

IIRC the '&' needs to go before drm_atomic_commit.

> + *
> + *   + The current active state of all entities affected by the update
> + *     is copied into this new &struct drm_atomic_commit using
> + *     drm_atomic_get_plane_state(), drm_atomic_get_crtc_state(),
> + *     drm_atomic_get_connector_state(), or
> + *     drm_atomic_get_private_obj_state(). This new state can then be
> + *     modified.

Again use active form.  Mention which helper invokes the copying. I 
assume it's drm_atomic_commit_alloc() or the UAPI entry points.

> + *
> + *     At that point, &struct drm_atomic_commit stores three state
> + *     pointers for any affected entity: the "old" and "new" states, and
> + *     state_to_destroy. The old state is the state currently active in
> + *     the hardware, which is either the one initialized by reset() or a
> + *     newer one if a commit has been made. The new state is the state
> + *     we just allocated and we might eventually commit to the hardware.
> + *     The state_to_destroy points to the state we'll eventually have to
> + *     free when the drm_atomic_commit will be destroyed, and points to
> + *     the new state for now since the old state is still the active
> + *     state.

Ok, sounds good.

> + *
> + *   + After the state is populated, it is checked. If the check is

You mean, it populated the new commit with the updated states?

Where does the check happen?

Again, use active form. Like: 'After ... populated the new commit with 
the updated states, it checks by invoking atomic_check of all involved 
pipeline stages."

> + *     successful, the update is committed. Part of the commit is a call

Active form: "successful, ... commits the update."

> + *     to drm_atomic_helper_swap_state() which will turn the new states
> + *     into the active states. Doing so involves updating the object's
> + *     state pointer (&drm_crtc.state or similar) to point to the new
> + *     state, and state_to_destroy will now point to the old states,
> + *     that used to be active but aren't anymore.

The final sentence ""Doing so..." is serviceable. For splendid writing, 
you could write somethink like "After swapping states, each object's 
state pointer refers to the formerly new state. The state_to_destroy 
pointer refers to the formerly old state."

> + *
> + *   + When the commit is done, and when all references to our &struct
> + *     drm_atomic_commit are put, __drm_atomic_commit_free() is called.

Active form: "After commiting the new state to hardware, ... puts all 
references to strut drm_atomic_commit and calls __drm_atomic_commit_free()".

> + *     It will, in turn, call drm_atomic_commit_clear() that will free

Present form: "It calls ... the frees ... and ...."

Best regards
Thomas

> + *     all state_to_destroy (ie. old states), and finally free &struct
> + *     drm_atomic_commit instance.
> + *
> + *   + Now, we don't have any active &struct drm_atomic_commit anymore,
> + *     and only the entity active states remain allocated.
> + */
> +
>   void __drm_crtc_commit_free(struct kref *kref)
>   {
>   	struct drm_crtc_commit *commit =
>   		container_of(kref, struct drm_crtc_commit, ref);
>   
>

-- 
--
Thomas Zimmermann
Graphics Driver Developer
SUSE Software Solutions Germany GmbH
Frankenstr. 146, 90461 Nürnberg, Germany, www.suse.com
GF: Jochen Jaser, Andrew McDonald, Werner Knoblich, (HRB 36809, AG Nürnberg)