From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from gabe.freedesktop.org (gabe.freedesktop.org [131.252.210.177]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 99F64FD4F01 for ; Tue, 10 Mar 2026 16:07:14 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id F368610E2C4; Tue, 10 Mar 2026 16:07:13 +0000 (UTC) Authentication-Results: gabe.freedesktop.org; dkim=pass (2048-bit key; unprotected) header.d=kernel.org header.i=@kernel.org header.b="J2wliESs"; dkim-atps=neutral Received: from sea.source.kernel.org (sea.source.kernel.org [172.234.252.31]) by gabe.freedesktop.org (Postfix) with ESMTPS id 0F89210E2C4 for ; Tue, 10 Mar 2026 16:07:12 +0000 (UTC) Received: from smtp.kernel.org (transwarp.subspace.kernel.org [100.75.92.58]) by sea.source.kernel.org (Postfix) with ESMTP id E8DD744546; Tue, 10 Mar 2026 16:07:11 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id 72D01C19423; Tue, 10 Mar 2026 16:07:11 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1773158831; bh=HGXDwistC7j0r/Ij2K5MQr2pye6tFQ6S1DiX2HIRAQ4=; h=From:Date:Subject:References:In-Reply-To:To:Cc:From; b=J2wliESseXnAdKrr8Q8T0m43B4HC6mY333oQc1PsY12N5g8VJqbWUG/p/Mea5+paI K/DkECdpFxvDcrdug8gzGN/nQHE9IWycz+9PNcQeYK+q11J48dEpAHHCtOVzGTIDle A3elvYAuTvLT+Sh3Q86CEttCMv4zLlp0Haafw4oO+loRK53nJJOA9OLhhATONBYwTi QtuTAEDIeM+JgsYongBS3jiDc3hpsvKXTvJE7c2MxOXEsjM2TRXmUDjnGLyUxCaGlI 2XSfNkaElq/Og0PFwRvIOuw6932K+6Z808vq/T2pxVcKmRb8lRgLQShdEzE1om4Gfg ZhS5zGM0pnyyw== From: Maxime Ripard Date: Tue, 10 Mar 2026 17:06:53 +0100 Subject: [PATCH 01/14] drm/atomic: Document atomic state lifetime MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: 7bit Message-Id: <20260310-drm-mode-config-init-v1-1-de7397c8e1cf@kernel.org> References: <20260310-drm-mode-config-init-v1-0-de7397c8e1cf@kernel.org> In-Reply-To: <20260310-drm-mode-config-init-v1-0-de7397c8e1cf@kernel.org> To: Maarten Lankhorst , Thomas Zimmermann , David Airlie , Simona Vetter , Jonathan Corbet , Shuah Khan , Dmitry Baryshkov , Jyri Sarha , Tomi Valkeinen , Andrzej Hajda , Neil Armstrong , Robert Foss , Laurent Pinchart , Jonas Karlman , Jernej Skrabec Cc: dri-devel@lists.freedesktop.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, Maxime Ripard X-Mailer: b4 0.14.2 X-Developer-Signature: v=1; a=openpgp-sha256; l=4285; i=mripard@kernel.org; h=from:subject:message-id; bh=HGXDwistC7j0r/Ij2K5MQr2pye6tFQ6S1DiX2HIRAQ4=; b=owGbwMvMwCmsHn9OcpHtvjLG02pJDJkbHJd8nFqSsIT/1/Sdji+Pr8u+ybLZeDLn1O8/I4OyE 0WULzUldkxlYRDmZJAVU2R5IhN2enn74ioH+5U/YOawMoEMYeDiFICJBE1jrK/SsJhuPY89hmF1 3NRndw4tKVC9nvvfffKMXUvLi07wHhXcW1h6ff2elFdnZQ5n7Tu+ZQNjnYaI9Uy3eRLhv4R+Wko ZX7he+o+rUMnz8rnX7TvNptv6r3hQWmNQJTube2GTX+ma7VaeAA== X-Developer-Key: i=mripard@kernel.org; a=openpgp; fpr=BE5675C37E818C8B5764241C254BCFC56BF6CE8D X-BeenThere: dri-devel@lists.freedesktop.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Direct Rendering Infrastructure - Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dri-devel-bounces@lists.freedesktop.org Sender: "dri-devel" How drm_atomic_state structures and the various entity structures are allocated and freed isn't really trivial, so let's document it. Signed-off-by: Maxime Ripard --- Documentation/gpu/drm-kms.rst | 6 +++++ drivers/gpu/drm/drm_atomic.c | 52 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 58 insertions(+) diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst index 2292e65f044c3bdebafbb8f83dfe7ac12e831273..017c7b196ed7ead4cf5fa8572e1f977d9e00dda8 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 `. 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 4283ab4d06c581727cc98b1dc870bf69691ea654..92c6afc8f22c8307a59dc266aacdb8e03351409d 100644 --- a/drivers/gpu/drm/drm_atomic.c +++ b/drivers/gpu/drm/drm_atomic.c @@ -45,10 +45,62 @@ #include #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 pointer 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 doing the update, while object states are allocated while + * the state will be, or is active in the hardware. + * + * 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: + * + * + we allocate a new &struct drm_atomic_state using drm_atomic_state_alloc(). + * + * + we copy the state of each affected entity into our &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(). That state can then be + * modified. + * + * At that point, &struct drm_atomic_state stores three state + * pointers for that particular entity: the old, new, and existing + * (called "state") states. 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 existing state points to the state we'll + * eventually have to free when the drm_atomic_state will be + * destroyed, but points to the new state for now. + * + * + 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 objects + * state pointer (&drm_crtc.state or similar) to point to the new + * state, and the existing states will now point to the old states, + * that used to be active but isn'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 the 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