mirror/linux
1
0
Fork 0
mirror of https://github.com/torvalds/linux.git synced 2025-04-12 16:47:42 +00:00
Code Issues Packages Projects Releases Wiki Activity

drm/atomic: Document history of drm_atomic_state

Browse Source 
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@ffwll.ch>
Link: https://lore.kernel.org/dri-devel/Z4jtKHY4qN3RNZNG@phenom.ffwll.local/
Reviewed-by: Simona Vetter <simona.vetter@ffwll.ch>
Link: https://lore.kernel.org/r/20250213-bridge-connector-v3-1-e71598f49c8f@kernel.org
Signed-off-by: Maxime Ripard <mripard@kernel.org>
This commit is contained in:
Maxime Ripard 2025-02-13 15:43:20 +01:00
parent fdee05235a
commit 56339ffaea
No known key found for this signature in database
GPG Key ID: 275FCE19A23DBE76
1 changed files with 31 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
include/drm/drm_atomic.h
View File

@ -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 {
/**