From 2b0fb8a0aa50cd36c94d414f3d4b02766cfdfec7 Mon Sep 17 00:00:00 2001 From: Maxime Ripard Date: Tue, 26 May 2026 18:46:13 +0200 Subject: [PATCH] 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 Reviewed-by: Thomas Zimmermann Link: https://patch.msgid.link/20260526-drm-mode-config-init-v6-1-852346394200@kernel.org Signed-off-by: Maxime Ripard --- 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 fa69a5450f96..e4f7153543b3 100644 --- a/Documentation/gpu/drm-kms.rst +++ b/Documentation/gpu/drm-kms.rst @@ -287,6 +287,12 @@ structure, ordering of committing state changes to hardware is sequenced using 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 ----------------------------- diff --git a/drivers/gpu/drm/drm_atomic.c b/drivers/gpu/drm/drm_atomic.c index 170de30c28ae..a1bcaaf71eea 100644 --- a/drivers/gpu/drm/drm_atomic.c +++ b/drivers/gpu/drm/drm_atomic.c @@ -47,6 +47,78 @@ #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. &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 reference to our &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 =