From: Maxime Ripard <mripard@kernel•org>
To: "Maarten Lankhorst" <maarten.lankhorst@linux•intel.com>,
"Thomas Zimmermann" <tzimmermann@suse•de>,
"David Airlie" <airlied@gmail•com>,
"Simona Vetter" <simona@ffwll•ch>,
"Jonathan Corbet" <corbet@lwn•net>,
"Shuah Khan" <skhan@linuxfoundation•org>,
"Dmitry Baryshkov" <dmitry.baryshkov@oss•qualcomm.com>,
"Jyri Sarha" <jyri.sarha@iki•fi>,
"Tomi Valkeinen" <tomi.valkeinen@ideasonboard•com>,
"Andrzej Hajda" <andrzej.hajda@intel•com>,
"Neil Armstrong" <neil.armstrong@linaro•org>,
"Robert Foss" <rfoss@kernel•org>,
"Laurent Pinchart" <Laurent.pinchart@ideasonboard•com>,
"Jonas Karlman" <jonas@kwiboo•se>,
"Jernej Skrabec" <jernej.skrabec@gmail•com>,
"Simon Ser" <contact@emersion•fr>,
"Harry Wentland" <harry.wentland@amd•com>,
"Melissa Wen" <mwen@igalia•com>,
"Sebastian Wick" <sebastian.wick@redhat•com>,
"Alex Hung" <alex.hung@amd•com>,
"Jani Nikula" <jani.nikula@linux•intel.com>,
"Rodrigo Vivi" <rodrigo.vivi@intel•com>,
"Joonas Lahtinen" <joonas.lahtinen@linux•intel.com>,
"Tvrtko Ursulin" <tursulin@ursulin•net>,
"Chen-Yu Tsai" <wens@kernel•org>,
"Samuel Holland" <samuel@sholland•org>,
"Dave Stevenson" <dave.stevenson@raspberrypi•com>,
"Maíra Canal" <mcanal@igalia•com>,
"Raspberry Pi Kernel Maintenance" <kernel-list@raspberrypi•com>
Cc: dri-devel@lists•freedesktop.org, linux-doc@vger•kernel.org,
linux-kernel@vger•kernel.org,
Daniel Stone <daniels@collabora•com>,
intel-gfx@lists•freedesktop.org, intel-xe@lists•freedesktop.org,
linux-arm-kernel@lists•infradead.org,
linux-sunxi@lists•linux.dev, Maxime Ripard <mripard@kernel•org>,
Laurent Pinchart <laurent.pinchart+renesas@ideasonboard•com>
Subject: [PATCH v6 01/19] drm/atomic: Document atomic commit lifetime
Date: Tue, 26 May 2026 18:46:13 +0200 [thread overview]
Message-ID: <20260526-drm-mode-config-init-v6-1-852346394200@kernel.org> (raw)
In-Reply-To: <20260526-drm-mode-config-init-v6-0-852346394200@kernel.org>
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(+)
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);
--
2.54.0
next prev parent reply other threads:[~2026-05-26 16:46 UTC|newest]
Thread overview: 22+ messages / expand[flat|nested] mbox.gz Atom feed top
2026-05-26 16:46 [PATCH v6 00/19] drm/atomic: Rework initial state allocation Maxime Ripard
2026-05-26 16:46 ` Maxime Ripard [this message]
2026-05-27 8:53 ` [PATCH v6 01/19] drm/atomic: Document atomic commit lifetime Thomas Zimmermann
2026-05-26 16:46 ` [PATCH v6 02/19] drm/colorop: Fix typos in the doc Maxime Ripard
2026-05-26 16:46 ` [PATCH v6 03/19] drm/atomic: Drop drm_private_obj.state assignment from create_state Maxime Ripard
2026-05-26 16:46 ` [PATCH v6 04/19] drm/atomic: Expand atomic_create_state expectations for drm_private_obj Maxime Ripard
2026-05-26 16:46 ` [PATCH v6 05/19] drm/mode-config: Document drm_private_obj exclusion from drm_mode_config_reset() Maxime Ripard
2026-05-26 16:46 ` [PATCH v6 06/19] drm/colorop: Rename __drm_colorop_state_reset() Maxime Ripard
2026-05-26 16:46 ` [PATCH v6 07/19] drm/colorop: Create drm_atomic_helper_colorop_create_state() Maxime Ripard
2026-05-26 16:46 ` [PATCH v6 08/19] drm/atomic-state-helper: Fix __drm_atomic_helper_plane_reset() doc typo Maxime Ripard
2026-05-26 16:46 ` [PATCH v6 09/19] drm/atomic-state-helper: Rename __drm_atomic_helper_plane_state_reset() Maxime Ripard
2026-05-26 16:46 ` [PATCH v6 10/19] drm/plane: Add new atomic_create_state callback Maxime Ripard
2026-05-26 16:46 ` [PATCH v6 11/19] drm/atomic-state-helper: Rename __drm_atomic_helper_crtc_state_reset() Maxime Ripard
2026-05-26 16:46 ` [PATCH v6 12/19] drm/crtc: Add new atomic_create_state callback Maxime Ripard
2026-05-26 16:46 ` [PATCH v6 13/19] drm/atomic-state-helper: Rename __drm_atomic_helper_connector_state_reset() Maxime Ripard
2026-05-26 16:46 ` [PATCH v6 14/19] drm/hdmi: Rename __drm_atomic_helper_connector_hdmi_reset() Maxime Ripard
2026-05-26 16:46 ` [PATCH v6 15/19] drm/connector: Add new atomic_create_state callback Maxime Ripard
2026-05-26 16:46 ` [PATCH v6 16/19] drm/mode-config: Create drm_mode_config_create_initial_state() Maxime Ripard
2026-05-26 16:46 ` [PATCH v6 17/19] drm/drv: Switch skeleton to drm_mode_config_create_initial_state() Maxime Ripard
2026-05-26 16:46 ` [PATCH v6 18/19] drm/tidss: Convert to atomic_create_state Maxime Ripard
2026-05-26 16:46 ` [PATCH v6 19/19] drm/bridge_connector: " Maxime Ripard
2026-05-29 9:44 ` [PATCH v6 00/19] drm/atomic: Rework initial state allocation Maxime Ripard
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20260526-drm-mode-config-init-v6-1-852346394200@kernel.org \
--to=mripard@kernel$(echo .)org \
--cc=Laurent.pinchart@ideasonboard$(echo .)com \
--cc=airlied@gmail$(echo .)com \
--cc=alex.hung@amd$(echo .)com \
--cc=andrzej.hajda@intel$(echo .)com \
--cc=contact@emersion$(echo .)fr \
--cc=corbet@lwn$(echo .)net \
--cc=daniels@collabora$(echo .)com \
--cc=dave.stevenson@raspberrypi$(echo .)com \
--cc=dmitry.baryshkov@oss$(echo .)qualcomm.com \
--cc=dri-devel@lists$(echo .)freedesktop.org \
--cc=harry.wentland@amd$(echo .)com \
--cc=intel-gfx@lists$(echo .)freedesktop.org \
--cc=intel-xe@lists$(echo .)freedesktop.org \
--cc=jani.nikula@linux$(echo .)intel.com \
--cc=jernej.skrabec@gmail$(echo .)com \
--cc=jonas@kwiboo$(echo .)se \
--cc=joonas.lahtinen@linux$(echo .)intel.com \
--cc=jyri.sarha@iki$(echo .)fi \
--cc=kernel-list@raspberrypi$(echo .)com \
--cc=laurent.pinchart+renesas@ideasonboard$(echo .)com \
--cc=linux-arm-kernel@lists$(echo .)infradead.org \
--cc=linux-doc@vger$(echo .)kernel.org \
--cc=linux-kernel@vger$(echo .)kernel.org \
--cc=linux-sunxi@lists$(echo .)linux.dev \
--cc=maarten.lankhorst@linux$(echo .)intel.com \
--cc=mcanal@igalia$(echo .)com \
--cc=mwen@igalia$(echo .)com \
--cc=neil.armstrong@linaro$(echo .)org \
--cc=rfoss@kernel$(echo .)org \
--cc=rodrigo.vivi@intel$(echo .)com \
--cc=samuel@sholland$(echo .)org \
--cc=sebastian.wick@redhat$(echo .)com \
--cc=simona@ffwll$(echo .)ch \
--cc=skhan@linuxfoundation$(echo .)org \
--cc=tomi.valkeinen@ideasonboard$(echo .)com \
--cc=tursulin@ursulin$(echo .)net \
--cc=tzimmermann@suse$(echo .)de \
--cc=wens@kernel$(echo .)org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox