HANDLING DRIVER PRIVATE STATE(9)

💅 handling driver private state 💅

okay so welcome to the Kernel API Manual page handling dr...rivate state(9), bestie — this is the one about handling driver private state, and it's genuinely iconic for anyone doing atomic modeset stuff. ✨

Very often the DRM objects exposed to userspace in the atomic modeset api (drm_connector, drm_crtc and drm_plane) do not map neatly to the underlying hardware. Especially for any kind of shared resources (e.g. shared clocks, scaler units, bandwidth and fifo limits shared among a group of planes or CRTCs, and so on) it makes sense to model these as independent objects. Drivers then need to do similar state tracking and commit ordering for such private (since not exposed to userspace) objects as the atomic core and helpers already provide for connectors, planes and CRTCs.

To make this easier on drivers the atomic core provides some support to track driver private state objects using struct drm_private_obj, with the associated state struct drm_private_state. 🫶

Similar to userspace-exposed objects, private state structures can be acquired by calling drm_atomic_get_private_obj_state. This also takes care of locking, hence drivers should not have a need to call drm_modeset_lock directly. Sequence of the actual hardware state commit is not handled, drivers might need to keep track of struct drm_crtc_commit within subclassed structure of drm_private_state as necessary, e.g. similar to drm_plane_state.commit. See also drm_atomic_commit.fake_commit. 👑

All private state structures contained in a drm_atomic_commit update can be iterated using for_each_oldnew_private_obj_in_state, for_each_new_private_obj_in_state and for_each_old_private_obj_in_state. Drivers are recommended to wrap these for each type of driver private state object they have, filtering on drm_private_obj.funcs using for_each_if, at least if they want to iterate over all objects of a given type. 🌈

An earlier way to handle driver private state was by subclassing struct drm_atomic_commit. But since that encourages non-standard ways to implement the check/commit split atomic requires (by using e.g. "check and rollback or commit instead" of "duplicate state, check, then either commit or release duplicated state) it is deprecated in favour of using drm_private_state. 🚨 like, deprecated deprecated — don't build new stuff on the old subclassing vibe, fr fr.

🌸 SEE ALSO 🌸

• Kernel file ./drivers/gpu/drm/drm_atomic.c state lifetime(9)
• drm_crtc_commit_wait(9)
• drm_atomic_commit_default_release(9)
• drm_atomic_commit_init(9)
• drm_atomic_commit_alloc(9)
• drm_atomic_commit_default_clear(9)
• drm_atomic_commit_clear(9)
• __drm_atomic_commit_free(9)
• drm_atomic_get_crtc_state(9)
• drm_atomic_get_plane_state(9)
• drm_atomic_get_colorop_state(9)
• drm_atomic_get_old_colorop_state(9)
• drm_atomic_get_new_colorop_state(9)
• drm_atomic_plane_check(9)
• drm_atomic_private_obj_init(9)
• drm_atomic_private_obj_fini(9)
• drm_atomic_get_private_obj_state(9)
• drm_atomic_get_old_private_obj_state(9)
• drm_atomic_get_new_private_obj_state(9)
• drm_atomic_get_old_connector_for_encoder(9)
• drm_atomic_get_new_connector_for_encoder(9)
• drm_atomic_get_connector_for_encoder(9)
• drm_atomic_get_old_crtc_for_encoder(9)
• drm_atomic_get_new_crtc_for_encoder(9)
• drm_atomic_get_connector_state(9)
• drm_atomic_get_bridge_state(9)
• drm_atomic_get_old_bridge_state(9)
• drm_atomic_get_new_bridge_state(9)
• drm_atomic_add_encoder_bridges(9)
• drm_atomic_add_affected_connectors(9)
• drm_atomic_add_affected_planes(9)
• drm_atomic_add_affected_colorops(9)
• drm_atomic_check_only(9)
• drm_atomic_commit(9)
• drm_atomic_nonblocking_commit(9)
• drm_atomic_print_new_state(9)
• drm_state_dump(9)

mwah 💋 that's the whole page — source/version ./drivers/gpu/drm · date October 2026 · page handling dr...rivate state(9). slay 💅