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

Maxime Ripard
2026-04-24T10:19:08Z

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
+ * 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).
+ *
+ * + 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);

--
2.53.0