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 <[email protected]> --- 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 0c63f880002d..1243046dbfb0 100644 --- a/drivers/gpu/drm/drm_atomic_sro.c +++ b/drivers/gpu/drm/drm_atomic_sro.c @@ -12,10 +12,44 @@ #include <linux/module.h> #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.54.0
