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 AFA953E3D94 for ; Thu, 23 Apr 2026 10:19:11 +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=1776939551; cv=none; b=al5nZnpzijSC6rKWCePqZboRLon/DWkIVrueBRAR1+dRHezquTFKpstEj/z/ii6S2+Ng3BTcw5qJEmCQ67tlT2YH8bJf3XXzaaypTMGfTDW7AF5CrcT0l/+h+uzawUslktnWZ7+6NxO/7lee3rhmNl/p1M1BG6pc1kUOCfw6eqc= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1776939551; c=relaxed/simple; bh=ew/vbK19D1rti39ABVjAa+5wPwF9OUKTQzsxF5sO9ZM=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=KWVPV/LsaHcZ2VjtBt7hHmStK51dgVHk38W/Tmsyk4sV47idrm1vpM5eAvOHwggA8zX97OIgYNJIe9hJUQtPleZAbYTRCEwklYPPZvLsbnWNBWip550Rpr4WVp8P0mubVpxo1e20/9DcXs2VBW38LW0Qn+eAIhJhnZV4bqzywPI= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=qpd3TFht; 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="qpd3TFht" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 408D3C2BCB2; Thu, 23 Apr 2026 10:19:11 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1776939551; bh=ew/vbK19D1rti39ABVjAa+5wPwF9OUKTQzsxF5sO9ZM=; h=From:Date:Subject:References:In-Reply-To:To:Cc:From; b=qpd3TFhtilGPLvhS1G+2Kq0g+Rwjsuyw/bN/igQeun6ScqIgAS27gIBp3UJdZdFwR wVciLsEr4PnLQUpJuWiGE1057X7FaIgRS32/bGIeQ+puoXtzsMw7ICPriEi5G8IFUM RNPHtSdogcPp/fgSChPvg6/8/H2FQNi6VlXt6GDzOL1VmfyAJWMNGu4c28dqvi4y9j PVkktMF1HZ7Y3PP5O96dUgRm449DymPaSYkc9PX93apbl7pvOb+XMHpRgzeIWFiFhY YaEhy2BXZGKPzjod1KAGYKLmyd19VypRiEMLk6Bn0onaGVGrtKtwUWBHmz1HGUpLTP A96Z2DAKuX4Qw== From: Maxime Ripard Date: Thu, 23 Apr 2026 12:18:27 +0200 Subject: [PATCH v2 14/28] drm/atomic_sro: Create documentation Precedence: bulk X-Mailing-List: linux-kernel@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: <20260423-drm-state-readout-v2-14-8549f87cb978@kernel.org> References: <20260423-drm-state-readout-v2-0-8549f87cb978@kernel.org> In-Reply-To: <20260423-drm-state-readout-v2-0-8549f87cb978@kernel.org> To: Maarten Lankhorst , Thomas Zimmermann , David Airlie , Simona Vetter , Andrzej Hajda , Neil Armstrong , Robert Foss , Laurent Pinchart , Jonas Karlman , Jernej Skrabec , Jyri Sarha , Tomi Valkeinen Cc: Devarsh Thakkar , dri-devel@lists.freedesktop.org, linux-kernel@vger.kernel.org, Maxime Ripard X-Mailer: b4 0.14.3 X-Developer-Signature: v=1; a=openpgp-sha256; l=2670; i=mripard@kernel.org; h=from:subject:message-id; bh=ew/vbK19D1rti39ABVjAa+5wPwF9OUKTQzsxF5sO9ZM=; b=owGbwMvMwCmsHn9OcpHtvjLG02pJDJkvP75lTNfWvJxVuqZjpvIXed0q5Rq/1v4SLekZz3ad7 JeccF27YyoLgzAng6yYIssTmbDTy9sXVznYr/wBM4eVCWQIAxenAEzkxx3GOvXNcXM/xVbNZHP/ 9Oc02+szs9fzRRw7c8SJZ+00c1+LJ9s/MK211zJ8UntE33/t7B0h1xjrc62PREx9xmnaKGzyN3J e0nlN/v9rKia0fV/xsXSJV6hn2h9ftTNCydw5wi0zigxqHLcDAA== X-Developer-Key: i=mripard@kernel.org; a=openpgp; fpr=BE5675C37E818C8B5764241C254BCFC56BF6CE8D The SRO infrastructure has grown to span multiple files and hooks but lacks an overview section explaining the overall design and how drivers should integrate with it. Add a DOC: overview section to drm_atomic_sro.c describing the various SRO phases and how drivers wire up the callbacks. Signed-off-by: Maxime Ripard --- drivers/gpu/drm/drm_atomic_sro.c | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/drivers/gpu/drm/drm_atomic_sro.c b/drivers/gpu/drm/drm_atomic_sro.c index 7ff67c140ff2..0e62e9d22ecc 100644 --- a/drivers/gpu/drm/drm_atomic_sro.c +++ b/drivers/gpu/drm/drm_atomic_sro.c @@ -12,10 +12,44 @@ #include #include "drm_internal.h" #include "drm_crtc_internal.h" +/** + * DOC: overview + * + * The atomic State Read-Out (SRO) infrastructure allows drivers to + * initialize the KMS atomic state from the hardware state left by the + * firmware at boot, rather than programming a new state. This enables + * flicker-free boot (also called "fastboot" by i915): if the + * firmware already configured the display, the first userspace + * modeset can be skipped when the requested mode matches. + * + * The SRO lifecycle has two phases. The first phase is the readout + * itself: at driver registration time, each KMS object (CRTCs, planes, + * connectors, bridges, private objects) has its + * atomic_sro_readout_state hook called to populate a + * &struct drm_atomic_sro_state from hardware registers. + * + * The second phase is the installation. Once all states have been read + * out, drm_atomic_sro_install_state() walks through the + * &struct drm_atomic_sro_state and assigns each readout state as the + * object's current state. Before doing so, it calls the optional + * atomic_sro_install_state hook on each object. This gives drivers a + * chance to acquire the resources needed to keep the hardware state + * active, such as power domains, clocks, or interrupts. This hook + * cannot fail. + * + * Drivers integrate with SRO by implementing the readout and compare + * hooks in their object funcs vtables and setting the + * &drm_mode_config_funcs.atomic_sro_readout_state and + * &drm_mode_config_helper_funcs.atomic_sro_build_state callbacks. The + * default helpers drm_atomic_helper_sro_readout_state() and + * drm_atomic_helper_sro_build_state() handle the standard readout + * sequence. + */ + enum drm_atomic_readout_status { DRM_ATOMIC_READOUT_DISABLED = 0, DRM_ATOMIC_READOUT_ENABLED, DRM_ATOMIC_READOUT_SKIP_MISSING_COMPARE, DRM_ATOMIC_READOUT_SKIP_MISSING_READOUT, -- 2.53.0