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 bombadil.infradead.org (bombadil.infradead.org [198.137.202.133]) (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 991D8CD4F3C for ; Tue, 12 May 2026 13:06:28 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=lists.infradead.org; s=bombadil.20210309; h=Sender:List-Subscribe:List-Help :List-Post:List-Archive:List-Unsubscribe:List-Id:Cc:To:In-Reply-To:References :Message-Id:Content-Transfer-Encoding:Content-Type:MIME-Version:Subject:Date: From:Reply-To:Content-ID:Content-Description:Resent-Date:Resent-From: Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Owner; bh=9AskrI+u9gyyOEfYZxxdvAr9+S3Axevjsi0Sx07dleg=; b=fIUYncAFiEl+JwA8p00sVRhNRX rfos/KMGPls/FXIyxbFKhu/8cAz8/iRdzK2gqe+qXOZ2x0CCCaga3OBMSggZDB+cNgZnteEL4y+m9 WGMZc6AsWxgulv20I+b8WrBarYxn5AZnFxX/EyjrtKETL21rbcgbUiWI9AfwXsS52T5Vj++FkQm0b WSUbqXiMeJp25qDMWR6JSBOTu01W7JFGtiMxMY0bZPwO5RQMt4yR/nIc0zHxAS3EH45DoCs//ZtrT j0+MaoZltP9GFP/hXSzAmRxxVzhuCG18GZ9NhpveuVnnE4137Me6St5rweRGsRaR3SpVVedFRV/mY S9vGO4gQ==; Received: from localhost ([::1] helo=bombadil.infradead.org) by bombadil.infradead.org with esmtp (Exim 4.99.1 #2 (Red Hat Linux)) id 1wMmoX-0000000GkWl-0NMy; Tue, 12 May 2026 13:06:21 +0000 Received: from sea.source.kernel.org ([172.234.252.31]) by bombadil.infradead.org with esmtps (Exim 4.99.1 #2 (Red Hat Linux)) id 1wMmoU-0000000GkVU-0Fd9 for linux-arm-kernel@lists.infradead.org; Tue, 12 May 2026 13:06:19 +0000 Received: from smtp.kernel.org (transwarp.subspace.kernel.org [100.75.92.58]) by sea.source.kernel.org (Postfix) with ESMTP id 6DCCE440F8; Tue, 12 May 2026 13:06:17 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id C464FC2BCF5; Tue, 12 May 2026 13:06:16 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1778591177; bh=jYT+8eKQtT56pqf/AoWAaezeyAaTlJPtELeA7v5tLcg=; h=From:Date:Subject:References:In-Reply-To:To:Cc:From; b=nZw+w0NHkTpEIdvVBpFpNUnzeCCKgqSSe8va8WoUXQMuGEINJy6M4f8lQT6xf5H72 vFVeDwNp6lpYI6Fe68AlkRfk0TUbq1ab9u2dY8F/v5Dtlldp56vfe/bdT7VDptST2N TVk/ob2A04+iR1UsUFn9ASCDqg+ZNC3pGe48lQdBApOUgORlmxEHHpxaadtzLoGNYr N3eCFd7YXfZpq+uxcQxc7x2C2GmDkUPBdYWnSD+sP69roLxFTb0u6uhDtKWPAkrLBL FG8LEv33Je1M/N4X+CKAf8twZA7WOs1NCybeqmHXd8RXA/84HlEI0mnHtcfnb++rbN l6L0R+LAEGlzQ== From: Maxime Ripard Date: Tue, 12 May 2026 15:05:59 +0200 Subject: [PATCH v4 01/20] drm/atomic: Document atomic commit lifetime MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: 7bit Message-Id: <20260512-drm-mode-config-init-v4-1-591dfdcc1bf9@kernel.org> References: <20260512-drm-mode-config-init-v4-0-591dfdcc1bf9@kernel.org> In-Reply-To: <20260512-drm-mode-config-init-v4-0-591dfdcc1bf9@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 , Laurent Pinchart X-Mailer: b4 0.14.3 X-Developer-Signature: v=1; a=openpgp-sha256; l=4424; i=mripard@kernel.org; h=from:subject:message-id; bh=jYT+8eKQtT56pqf/AoWAaezeyAaTlJPtELeA7v5tLcg=; b=owGbwMvMwCmsHn9OcpHtvjLG02pJDFnMqrtKJlrtcH3kNlsh4+MDleB/K26LfbrjUeZant/a8 kzlyqbJHVNZGIQ5GWTFFFmeyISdXt6+uMrBfuUPmDmsTCBDGLg4BWAiaZaMdcpS68z2nfh/Jtv7 yLo1ratWb619PvOsQWdxW1Q7B8uKxYF/FZ1V1h382qTm67dMYvrEVsb6mK+H46ekz2Ffwjlj/Sz TmdbOL4t3b9d6EiOkuHWT0fK7XeHqv82MjJ0nSFdeTZDMPzoHAA== X-Developer-Key: i=mripard@kernel.org; a=openpgp; fpr=BE5675C37E818C8B5764241C254BCFC56BF6CE8D X-CRM114-Version: 20100106-BlameMichelson ( TRE 0.9.0 (BSD) ) MR-646709E3 X-CRM114-CacheID: sfid-20260512_060618_147109_EDDA569A X-CRM114-Status: GOOD ( 21.98 ) X-BeenThere: linux-arm-kernel@lists.infradead.org X-Mailman-Version: 2.1.34 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: "linux-arm-kernel" Errors-To: linux-arm-kernel-bounces+linux-arm-kernel=archiver.kernel.org@lists.infradead.org How drm_atomic_commit and the various entity structures are allocated and freed isn't really trivial. Document it. Reviewed-by: Laurent Pinchart Signed-off-by: Maxime Ripard --- Documentation/gpu/drm-kms.rst | 6 +++++ drivers/gpu/drm/drm_atomic.c | 57 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 63 insertions(+) diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst index fbe0583eb84c..d50529482335 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 170de30c28ae..04bc3e736cbd 100644 --- a/drivers/gpu/drm/drm_atomic.c +++ b/drivers/gpu/drm/drm_atomic.c @@ -45,10 +45,67 @@ #include #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_clear() runs and + * will free all state_to_destroy (ie. old states), and the &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