Re: [PATCH v3 01/20] drm/atomic: Document atomic state lifetime

Laurent Pinchart
2026-05-04T16:26:44Z

Hi Maxime,

Thank you for the patch.

On Fri, Apr 24, 2026 at 12:18:41PM +0200, Maxime Ripard wrote:
> How drm_atomic_state structures and the various entity structures are
> allocated and freed isn't really trivial. Document it.
>
> Signed-off-by: Maxime Ripard <mripard@kernel.org>
> ---
> Documentation/gpu/drm-kms.rst | 6 +++++
> drivers/gpu/drm/drm_atomic.c | 55 +++++++++++++++++++++++++++++++++++++++++++
> 2 files changed, 61 insertions(+)
>
> diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst
> index 2292e65f044c..017c7b196ed7 100644
> --- a/Documentation/gpu/drm-kms.rst
> +++ b/Documentation/gpu/drm-kms.rst
> @@ -280,10 +280,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 41c57063f3b4..253a00f450b0 100644
> --- a/drivers/gpu/drm/drm_atomic.c
> +++ b/drivers/gpu/drm/drm_atomic.c
> @@ -45,10 +45,65 @@
> #include <drm/drm_colorop.h>
>
> #include "drm_crtc_internal.h"
> #include "drm_internal.h"
>
> +/**
> + * DOC: state lifetime
> + *
> + * &struct drm_atomic_state represents an update to video pipeline
> + * state. Despite its confusing name, it's actually a transient object
> + * that holds a state update as a collection of pointers to individual
> + * objects' states. &struct drm_atomic_state 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.
> + *
> + * - whenever a new update is needed:
> + *
> + * + A new &struct drm_atomic_state is allocated using
> + * drm_atomic_state_alloc().
> + *
> + * + The current active state of affected entity is copied into this

s/affected entity/affected entities/

but maybe clearer, I'd write

+ The current active state of all entities affected by the update is
copied ...

> + * new &struct drm_atomic_state 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.
> + *
> + * At that point, &struct drm_atomic_state 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_state will be destroyed, and points to
> + * the new state for now since the old state is still the active
> + * state.
> + *
> + * + After the state is populated, it is checked. If the check is
> + * successful, the update is committed. Part of the commit is a call
> + * 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.
> + *
> + * + When the commit is done, and when all references to our &struct
> + * drm_atomic_state are put, drm_atomic_state_clear() runs and will
> + * free all state_to_destroy (ie. old states).

I would also mention here that the drm_atomic_state itself is freed at
this point (unless I'm mistaken and the drm_atomic_state still lives on
for some time, in which case this misunderstanding is probably a sign
that the correct behaviour should be documented :-)).

With this,

Reviewed-by: Laurent Pinchart <laurent.pinchart+renesas@ideasonboard.com>

> + *
> + * + Now, we don't have any active &struct drm_atomic_state 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);
>

--
Regards,

Laurent Pinchart