From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 65247364935; Fri, 24 Apr 2026 10:19:04 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1777025944; cv=none; b=HgzAje230dQINjOFKiizhYvZAz6EyYH7qguurXcybiV8UveyXEHSnygZgHHWHJnV6lT+lKtyod0fq4JtPZe4Vpuhzfs/6wNJynvOAK1b6Y1FRA2Ec7DKcln4wHhqx5RQUisIQIgVgM9qXEhd5q9WkUELzjlS+xdw8X+s59W0rVs= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1777025944; c=relaxed/simple; bh=cINX/D5QpQR2W4U6rueBfqwioXlzpvH8HbHly8FuKYM=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=hsIPQXg0IrLTpcBxAnVljEc8r36Ha3oip60znNP5liFuGDXloO/No93dFIddqIId89lXETDEgobOu6kwKih8C48512JxDvKFu2fB5eBefPIdnbe/MEBTNizVyu71uTpva2Z57//nhdUrMCADMjwBydLqR1JnXaowt37TunKo8tc= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=aUXsoeSX; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="aUXsoeSX" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 90A56C19425; Fri, 24 Apr 2026 10:19:03 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1777025944; bh=cINX/D5QpQR2W4U6rueBfqwioXlzpvH8HbHly8FuKYM=; h=From:Date:Subject:References:In-Reply-To:To:Cc:From; b=aUXsoeSXpv8hlDL/1PaaUSueigcD2BEDlCUc0/Sd9XgisLUYeJ6kXfstGCrDgSX5D 4uhuRX+jmXrlLhq/hk9+65PXyc6/4OXOA+UkQD1CDnqtl0P0hO7QIjxNU21oz9kA14 CCh/CqPAhGcURZT2HFoBZ0JEUn1AiixJxWSq+0wNraxozo8zlQyREFGgz29QVoZy4A 1A8Z+7VoH6Usbida8JPBaeot8jstA5QMHybYVDT9AmRNWpDSWx/xZg9Yz/V/+efgkC jG2MQKtm8FXrmP7kOYjHapE43XdNmSmu6hueo9dFQkkSuV+piu/qOmd1QGADEtrbDs 7uaIZAGOabNPQ== From: Maxime Ripard Date: Fri, 24 Apr 2026 12:18:41 +0200 Subject: [PATCH v3 01/20] drm/atomic: Document atomic state lifetime Precedence: bulk X-Mailing-List: linux-doc@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: 7bit Message-Id: <20260424-drm-mode-config-init-v3-1-8b68d9db0d8b@kernel.org> References: <20260424-drm-mode-config-init-v3-0-8b68d9db0d8b@kernel.org> In-Reply-To: <20260424-drm-mode-config-init-v3-0-8b68d9db0d8b@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 , Simon Ser , Harry Wentland , Melissa Wen , Sebastian Wick , Alex Hung , Jani Nikula , Rodrigo Vivi , Joonas Lahtinen , Tvrtko Ursulin , Chen-Yu Tsai , Samuel Holland , Dave Stevenson , =?utf-8?q?Ma=C3=ADra_Canal?= , Raspberry Pi Kernel Maintenance Cc: dri-devel@lists.freedesktop.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, Daniel Stone , intel-gfx@lists.freedesktop.org, intel-xe@lists.freedesktop.org, linux-arm-kernel@lists.infradead.org, linux-sunxi@lists.linux.dev, Maxime Ripard X-Mailer: b4 0.14.3 X-Developer-Signature: v=1; a=openpgp-sha256; l=4304; i=mripard@kernel.org; h=from:subject:message-id; bh=cINX/D5QpQR2W4U6rueBfqwioXlzpvH8HbHly8FuKYM=; b=owGbwMvMwCmsHn9OcpHtvjLG02pJDJmvnTsDJmbUzD8gfvZZW8oL5vdPeXPvT5GUSLE79PyRp V/69IIDHVNZGIQ5GWTFFFmeyISdXt6+uMrBfuUPmDmsTCBDGLg4BWAilnqMDf9v1b+foea16+CH OsVFeWl2DaZn35dq8hzfHLqyZW7PRYlyu5snG3LOG1XVrWdrFzbay9iwZSlT/ImOE82Kb389fn9 64tcTHZrzOpI2B+UoC6aau1izvDJ3OLv9lY1Tf/fkjjMFffMA X-Developer-Key: i=mripard@kernel.org; a=openpgp; fpr=BE5675C37E818C8B5764241C254BCFC56BF6CE8D How drm_atomic_state structures and the various entity structures are allocated and freed isn't really trivial. Document it. Signed-off-by: Maxime Ripard --- Documentation/gpu/drm-kms.rst | 6 +++++ drivers/gpu/drm/drm_atomic.c | 55 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 61 insertions(+) diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst index 2292e65f044c..017c7b196ed7 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 41c57063f3b4..253a00f450b0 100644 --- a/drivers/gpu/drm/drm_atomic.c +++ b/drivers/gpu/drm/drm_atomic.c @@ -45,10 +45,65 @@ #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 pointers 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 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_state is allocated using + * drm_atomic_state_alloc(). + * + * + The current active state of affected entity is copied into this + * new &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(). This new state can then be + * modified. + * + * At that point, &struct drm_atomic_state 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_state 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_state are put, drm_atomic_state_clear() runs and will + * free all state_to_destroy (ie. 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