The "atomic state reset and initialization" DOC section describes the problem of needing correct atomic state at driver load and after suspend, but only mentions the reset approach and a vague reference to i915's read-out as an alternative.
Now that the State Read-Out (SRO) infrastructure provides a generic solution, update the documentation to describe both approaches and cross-reference the SRO section. Also mention drm_mode_config_create_initial_state() which combines both. Signed-off-by: Maxime Ripard <[email protected]> --- drivers/gpu/drm/drm_atomic_state_helper.c | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/drivers/gpu/drm/drm_atomic_state_helper.c b/drivers/gpu/drm/drm_atomic_state_helper.c index 354fa9c6aca8..bd61c56ceca6 100644 --- a/drivers/gpu/drm/drm_atomic_state_helper.c +++ b/drivers/gpu/drm/drm_atomic_state_helper.c @@ -45,17 +45,25 @@ * DOC: atomic state reset and initialization * * Both the drm core and the atomic helpers assume that there is always the full * and correct atomic software state for all connectors, CRTCs and planes * available. Which is a bit a problem on driver load and also after system - * suspend. One way to solve this is to have a hardware state read-out - * infrastructure which reconstructs the full software state (e.g. the i915 - * driver). + * suspend. There are two ways to solve this: * - * The simpler solution is to just reset the software state to everything off, - * which is easiest to do by calling drm_mode_config_reset(). To facilitate this - * the atomic helpers provide default reset implementations for all hooks. + * The first is to use the :ref:`State Read-Out (SRO) <drm_atomic_sro>` + * infrastructure to reconstruct the full software state from hardware + * registers. This enables flicker-free boot when the firmware already + * configured the display. + * + * The simpler alternative is to just reset the software state to everything + * off, which is easiest to do by calling drm_mode_config_reset(). To + * facilitate this the atomic helpers provide default reset implementations for + * all hooks. + * + * drm_mode_config_create_initial_state() combines both approaches: it tries + * SRO first, and falls back to a hardware reset followed by + * drm_mode_config_create_state(). * * On the upside the precise state tracking of atomic simplifies system suspend * and resume a lot. For drivers using drm_mode_config_reset() a complete recipe * is implemented in drm_atomic_helper_suspend() and drm_atomic_helper_resume(). * For other drivers the building blocks are split out, see the documentation -- 2.55.0
