From: Thomas Zimmermann <tzimmermann@suse•de>
To: "Maxime Ripard" <mripard@kernel•org>,
"Maarten Lankhorst" <maarten.lankhorst@linux•intel.com>,
"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,
Laurent Pinchart <laurent.pinchart+renesas@ideasonboard•com>
Subject: Re: [PATCH v6 01/19] drm/atomic: Document atomic commit lifetime
Date: Wed, 27 May 2026 10:53:00 +0200 [thread overview]
Message-ID: <ec0fcc2e-b767-4509-b9ae-174c9941796e@suse.de> (raw)
In-Reply-To: <20260526-drm-mode-config-init-v6-1-852346394200@kernel.org>
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);
>
>
--
--
Thomas Zimmermann
Graphics Driver Developer
SUSE Software Solutions Germany GmbH
Frankenstr. 146, 90461 Nürnberg, Germany, www.suse.com
GF: Jochen Jaser, Andrew McDonald, Werner Knoblich, (HRB 36809, AG Nürnberg)
next prev parent reply other threads:[~2026-05-27 8:53 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 ` [PATCH v6 01/19] drm/atomic: Document atomic commit lifetime Maxime Ripard
2026-05-27 8:53 ` Thomas Zimmermann [this message]
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=ec0fcc2e-b767-4509-b9ae-174c9941796e@suse.de \
--to=tzimmermann@suse$(echo .)de \
--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=mripard@kernel$(echo .)org \
--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=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