Re: [PATCH v3 01/37] drm/atomic: Document history of drm_atomic_state

[Simona Vetter]

On Thu, Feb 13, 2025 at 03:43:20PM +0100, Maxime Ripard wrote:
> After some discussions on the mailing-list for an earlier revision of
> the series, it was suggested to document the evolution of
> drm_atomic_state and its use by drivers to explain some of the confusion
> one might still encounter when reading the framework code.
> 
> Suggested-by: Simona Vetter <simona.vetter@xxxxxxxx>
> Link: https://lore.kernel.org/dri-devel/Z4jtKHY4qN3RNZNG@phenom.ffwll.local/
> Signed-off-by: Maxime Ripard <mripard@xxxxxxxxxx>

Thanks for documenting that little bit of lore!

Reviewed-by: Simona Vetter <simona.vetter@xxxxxxxx>

Cheers, Sima

> ---
>  include/drm/drm_atomic.h | 31 +++++++++++++++++++++++++++++++
>  1 file changed, 31 insertions(+)
> 
> diff --git a/include/drm/drm_atomic.h b/include/drm/drm_atomic.h
> index 1ded9a8d4e84d7d9879d7f60a876ba9d69785766..4c673f0698fef6b60f77db980378d5e88e0e250e 100644
> --- a/include/drm/drm_atomic.h
> +++ b/include/drm/drm_atomic.h
> @@ -355,10 +355,41 @@ struct __drm_private_objs_state {
>   * these.
>   *
>   * States are added to an atomic update by calling drm_atomic_get_crtc_state(),
>   * drm_atomic_get_plane_state(), drm_atomic_get_connector_state(), or for
>   * private state structures, drm_atomic_get_private_obj_state().
> + *
> + * NOTE: struct drm_atomic_state first started as a single collection of
> + * entities state pointers (drm_plane_state, drm_crtc_state, etc.).
> + *
> + * At atomic_check time, you could get the state about to be committed
> + * from drm_atomic_state, and the one currently running from the
> + * entities state pointer (drm_crtc.state, for example). After the call
> + * to drm_atomic_helper_swap_state(), the entities state pointer would
> + * contain the state previously checked, and the drm_atomic_state
> + * structure the old state.
> + *
> + * Over time, and in order to avoid confusion, drm_atomic_state has
> + * grown to have both the old state (ie, the state we replace) and the
> + * new state (ie, the state we want to apply). Those names are stable
> + * during the commit process, which makes it easier to reason about.
> + *
> + * You can still find some traces of that evolution through some hooks
> + * or callbacks taking a drm_atomic_state parameter called names like
> + * "old_state". This doesn't necessarily mean that the previous
> + * drm_atomic_state is passed, but rather that this used to be the state
> + * collection we were replacing after drm_atomic_helper_swap_state(),
> + * but the variable name was never updated.
> + *
> + * Some atomic operations implementations followed a similar process. We
> + * first started to pass the entity state only. However, it was pretty
> + * cumbersome for drivers, and especially CRTCs, to retrieve the states
> + * of other components. Thus, we switched to passing the whole
> + * drm_atomic_state as a parameter to those operations. Similarly, the
> + * transition isn't complete yet, and one might still find atomic
> + * operations taking a drm_atomic_state pointer, or a component state
> + * pointer. The former is the preferred form.
>   */
>  struct drm_atomic_state {
>  	/**
>  	 * @ref:
>  	 *
> 
> -- 
> 2.48.0
> 

-- 
Simona Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch