[v6,01/19] drm/atomic: Document atomic commit lifetime

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@ideasonboard.com>
Signed-off-by: Maxime Ripard <mripard@kernel.org>
---
 Documentation/gpu/drm-kms.rst |  6 ++++
 drivers/gpu/drm/drm_atomic.c  | 72 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 78 insertions(+)
  

Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider:
- [Low] Typo in documentation: 'refererence' instead of 'reference'.
--

commit 68dc91b6affb075e72fa412fac45ff103b6f970a
Author: Maxime Ripard <mripard@kernel.org>

drm/atomic: Document atomic commit lifetime

This commit documents the lifetime and memory management of drm_atomic_commit
and its associated state structures.

> diff --git a/drivers/gpu/drm/drm_atomic.c b/drivers/gpu/drm/drm_atomic.c
> index 170de30c28ae4..3c5714481ad28 100644
> --- a/drivers/gpu/drm/drm_atomic.c
> +++ b/drivers/gpu/drm/drm_atomic.c
[ ... ]
> @@ -47,6 +47,78 @@
[ ... ]
> +   + Once done, and when the last refererence to our &struct
> +     drm_atomic_commit is given up through drm_atomic_commit_put(), it

[Severity: Low]
This isn't a bug, but there appears to be a typo here ("refererence" instead
of "reference").
  

Am 26.05.26 um 18:46 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@ideasonboard.com>
> Signed-off-by: Maxime Ripard <mripard@kernel.org>

Reviewed-by: Thomas Zimmermann <tzimmermann@suse.de>

> ---
>   Documentation/gpu/drm-kms.rst |  6 ++++
>   drivers/gpu/drm/drm_atomic.c  | 72 +++++++++++++++++++++++++++++++++++++++++++
>   2 files changed, 78 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..3c5714481ad2 100644
> --- a/drivers/gpu/drm/drm_atomic.c
> +++ b/drivers/gpu/drm/drm_atomic.c
> @@ -45,10 +45,82 @@
>   #include <drm/drm_colorop.h>
>   
>   #include "drm_crtc_internal.h"
>   #include "drm_internal.h"
>   
> +/**
> + * DOC: state lifetime
> + *
> + * &drm_atomic_commit represents an update to modeset pipeline 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 allocates a new
> + *   default state and stores it in the object state pointer.
> + *
> + * - whenever a new update is needed:
> + *
> + *   + drm_atomic_commit_alloc() allocates a new &drm_atomic_commit
> + *     instance.
> + *
> + *   + The code triggering the commit (ioctl, client modeset,
> + *     drm_atomic_helper_reset_crtc(), etc.) copies the current active
> + *     state of all entities affected by the update into this new
> + *     &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.
> + *
> + *     At that point, &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.
> + *
> + *   + After the calling code populated the commit with the entities
> + *     states, it updates the new states with the new values we need to
> + *     commit. The new commit instance is now ready.
> + *
> + *   + Then we have two branches depending on the calling code intent:
> + *
> + *     - If the calling code only wants to check that the commit would
> + *       work (for example because of the DRM_MODE_ATOMIC_TEST_ONLY
> + *       flag). It calls drm_atomic_check_only(), which in turn checks
> + *       all these states by invoking atomic_check on all affected
> + *       pipeline stages.
> + *
> + *     - If the calling code actually wants to trigger a commit, it
> + *       calls drm_atomic_commit(). The first stage is the check
> + *       mentioned above, and if the check is successful, it performs
> + *       the commit. Part of the commit is a call to
> + *       drm_atomic_helper_swap_state() which turns the new states into
> + *       the active states. After swapping states, each object's state
> + *       pointer now refers to the formerly new state. The
> + *       state_to_destroy now refers to the formerly old state.
> + *
> + *   + Once done, and when the last refererence to our &struct
> + *     drm_atomic_commit is given up through drm_atomic_commit_put(), it
> + *     calls __drm_atomic_commit_free(). In turn,
> + *     __drm_atomic_commit_free() calls drm_atomic_commit_clear() that
> + *     will free all state_to_destroy (ie. old states), and it finally
> + *     frees &drm_atomic_commit instance.
> + *
> + *   + Now, we don't have any active &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);
>   
>