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 v5 01/19] drm/atomic: Document atomic commit lifetime
Date: Tue, 19 May 2026 11:01:43 +0200 [thread overview]
Message-ID: <20260519-drm-mode-config-init-v5-1-388b03321e38@kernel.org> (raw)
In-Reply-To: <20260519-drm-mode-config-init-v5-0-388b03321e38@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 | 58 +++++++++++++++++++++++++++++++++++++++++++
2 files changed, 64 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..d98586d89bbe 100644
--- a/drivers/gpu/drm/drm_atomic.c
+++ b/drivers/gpu/drm/drm_atomic.c
@@ -45,10 +45,68 @@
#include <drm/drm_colorop.h>
#include "drm_crtc_internal.h"
#include "drm_internal.h"
+/**
+ * DOC: state lifetime
+ *
+ * &struct drm_atomic_commit represents an update to video 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 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_commit is allocated using
+ * drm_atomic_commit_alloc().
+ *
+ * + The current active state of all entities affected by the update
+ * is copied into this new &struct 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, &struct 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 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_commit are put, __drm_atomic_commit_free() is called.
+ * It will, in turn, call drm_atomic_commit_clear() that will free
+ * all state_to_destroy (ie. old states), and finally free &struct
+ * drm_atomic_commit instance.
+ *
+ * + Now, we don't have any active &struct 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-19 9:02 UTC|newest]
Thread overview: 30+ messages / expand[flat|nested] mbox.gz Atom feed top
2026-05-19 9:01 [PATCH v5 00/19] drm/atomic: Rework initial state allocation Maxime Ripard
2026-05-19 9:01 ` Maxime Ripard [this message]
2026-05-26 8:59 ` [PATCH v5 01/19] drm/atomic: Document atomic commit lifetime Thomas Zimmermann
2026-05-19 9:01 ` [PATCH v5 02/19] drm/colorop: Fix typos in the doc Maxime Ripard
2026-05-19 9:01 ` [PATCH v5 03/19] drm/atomic: Drop drm_private_obj.state assignment from create_state Maxime Ripard
2026-05-26 9:03 ` Thomas Zimmermann
2026-05-19 9:01 ` [PATCH v5 04/19] drm/atomic: Expand atomic_create_state expectations for drm_private_obj Maxime Ripard
2026-05-26 9:03 ` Thomas Zimmermann
2026-05-19 9:01 ` [PATCH v5 05/19] drm/mode-config: Document drm_private_obj exclusion from drm_mode_config_reset() Maxime Ripard
2026-05-26 9:05 ` Thomas Zimmermann
2026-05-19 9:01 ` [PATCH v5 06/19] drm/colorop: Rename __drm_colorop_state_reset() Maxime Ripard
2026-05-19 9:01 ` [PATCH v5 07/19] drm/colorop: Create drm_atomic_helper_colorop_create_state() Maxime Ripard
2026-05-19 9:01 ` [PATCH v5 08/19] drm/atomic-state-helper: Fix __drm_atomic_helper_plane_reset() doc typo Maxime Ripard
2026-05-19 9:01 ` [PATCH v5 09/19] drm/atomic-state-helper: Rename __drm_atomic_helper_plane_state_reset() Maxime Ripard
2026-05-19 9:01 ` [PATCH v5 10/19] drm/plane: Add new atomic_create_state callback Maxime Ripard
2026-05-26 9:08 ` Thomas Zimmermann
2026-05-19 9:01 ` [PATCH v5 11/19] drm/atomic-state-helper: Rename __drm_atomic_helper_crtc_state_reset() Maxime Ripard
2026-05-19 9:01 ` [PATCH v5 12/19] drm/crtc: Add new atomic_create_state callback Maxime Ripard
2026-05-26 9:22 ` Thomas Zimmermann
2026-05-19 9:01 ` [PATCH v5 13/19] drm/atomic-state-helper: Rename __drm_atomic_helper_connector_state_reset() Maxime Ripard
2026-05-19 9:01 ` [PATCH v5 14/19] drm/hdmi: Rename __drm_atomic_helper_connector_hdmi_reset() Maxime Ripard
2026-05-19 9:01 ` [PATCH v5 15/19] drm/connector: Add new atomic_create_state callback Maxime Ripard
2026-05-26 9:28 ` Thomas Zimmermann
2026-05-19 9:01 ` [PATCH v5 16/19] drm/mode-config: Create drm_mode_config_create_initial_state() Maxime Ripard
2026-05-26 9:33 ` Thomas Zimmermann
2026-05-19 9:01 ` [PATCH v5 17/19] drm/drv: Switch skeleton to drm_mode_config_create_initial_state() Maxime Ripard
2026-05-26 9:34 ` Thomas Zimmermann
2026-05-19 9:02 ` [PATCH v5 18/19] drm/tidss: Convert to atomic_create_state Maxime Ripard
2026-05-19 9:02 ` [PATCH v5 19/19] drm/bridge_connector: " Maxime Ripard
2026-05-26 9:36 ` [PATCH v5 00/19] drm/atomic: Rework initial state allocation Thomas Zimmermann
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=20260519-drm-mode-config-init-v5-1-388b03321e38@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