From: Maxime Ripard Date: Thu, 13 Feb 2025 14:43:20 +0000 (+0100) Subject: drm/atomic: Document history of drm_atomic_state X-Git-Tag: v6.15-rc1~120^2~19^2~29 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=56339ffaeaf87cce070c2437df71dc3340598be0;p=thirdparty%2Fkernel%2Flinux.git drm/atomic: Document history of drm_atomic_state 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 Link: https://lore.kernel.org/dri-devel/Z4jtKHY4qN3RNZNG@phenom.ffwll.local/ Reviewed-by: Simona Vetter Link: https://lore.kernel.org/r/20250213-bridge-connector-v3-1-e71598f49c8f@kernel.org Signed-off-by: Maxime Ripard --- diff --git a/include/drm/drm_atomic.h b/include/drm/drm_atomic.h index 1ded9a8d4e84d..4c673f0698fef 100644 --- a/include/drm/drm_atomic.h +++ b/include/drm/drm_atomic.h @@ -357,6 +357,37 @@ struct __drm_private_objs_state { * 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 { /**