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_state_readout.c describing the various SRO phases and how drivers wire up the callbacks. Reviewed-by: Maarten Lankhorst <[email protected]> Signed-off-by: Maxime Ripard <[email protected]> --- Documentation/gpu/drm-kms-helpers.rst | 17 ++++++++++++++ drivers/gpu/drm/drm_atomic_state_readout.c | 36 ++++++++++++++++++++++++++++++ 2 files changed, 53 insertions(+) diff --git a/Documentation/gpu/drm-kms-helpers.rst b/Documentation/gpu/drm-kms-helpers.rst index d64f941d34f5..b75bde712faf 100644 --- a/Documentation/gpu/drm-kms-helpers.rst +++ b/Documentation/gpu/drm-kms-helpers.rst @@ -83,4 +83,21 @@ Atomic State Helper Reference :export: +.. _drm_atomic_sro: + +Atomic State Read-Out +--------------------- + +.. kernel-doc:: drivers/gpu/drm/drm_atomic_state_readout.c + :doc: overview + +Atomic State Read-Out Reference +-------------------------------- + +.. kernel-doc:: include/drm/drm_atomic_state_readout.h + :internal: + +.. kernel-doc:: drivers/gpu/drm/drm_atomic_state_readout.c + :export: + GEM Atomic Helper Reference --------------------------- diff --git a/drivers/gpu/drm/drm_atomic_state_readout.c b/drivers/gpu/drm/drm_atomic_state_readout.c index a5bc77b3e492..413823579ed5 100644 --- a/drivers/gpu/drm/drm_atomic_state_readout.c +++ b/drivers/gpu/drm/drm_atomic_state_readout.c @@ -16,4 +16,40 @@ #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 hardware may have been programmed with a configuration that + * the driver doesn't support. The readout hooks are then expected + * to return a negative error code, and the state initialization + * will fall back to the regular path. + * + * 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 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. + */ + enum drm_atomic_readout_status { DRM_ATOMIC_READOUT_DISABLED = 0, -- 2.55.0
