STATE LIFETIME(9)

✨ state lifetime(9) ✨

okay so bestie, this is the Kernel API Manual page for state lifetime, and it's literally all about who lives how long in the DRM atomic state world 💅.

drm_atomic_commit represents an update to modeset pipeline state. It's a transient object that holds a state update as a collection of pointers to individual objects' states. drm_atomic_commit has a much shorter lifetime than the objects' states, since it's only allocated while preparing, checking or committing the update, while object states are allocated when preparing the update and kept alive as long as they are active in the device.

Their respective lifetimes are:

• at driver initialization time, the driver calls drm_mode_config_create_initial_state to allocate an initial, pristine, state for each object and stores it in the objects state pointer. Historically, this was one of drm_mode_config_reset job, so one might still encounter it in a driver.
• When resuming from suspend, drm_mode_config_reset resets the software and hardware state to a known default and stores it in the object's state pointer. Not all objects are affected by drm_mode_config_reset though.
• whenever a new update is needed:
  • drm_atomic_commit_alloc allocates a new drm_atomic_commit instance.
  • The code triggering the commit (ioctl, client modeset, drm_atomic_helper_reset_crtc, etc.) copies the current active state of all entities affected by the update into this new drm_atomic_commit using drm_atomic_get_plane_state, drm_atomic_get_crtc_state, drm_atomic_get_connector_state, or drm_atomic_get_private_obj_state. This new state can then be modified.

At that point, drm_atomic_commit stores three state pointers for any affected entity: the "old" and "new" states, and state_to_destroy. The old state is the state currently active in the hardware, which is either the one initialized by reset or a newer one if a commit has been made. The new state is the state we just allocated and we might eventually commit to the hardware. The state_to_destroy points to the state we'll eventually have to free when the drm_atomic_commit will be destroyed, and points to the new state for now since the old state is still the active state.

• After the calling code populated the commit with the entities states, it updates the new states with the new values we need to commit. The new commit instance is now ready.
• Then we have two branches depending on the calling code intent:
  • If the calling code only wants to check that the commit would work (for example because of the DRM_MODE_ATOMIC_TEST_ONLY flag). It calls drm_atomic_check_only, which in turn checks all these states by invoking atomic_check on all affected pipeline stages.
  • If the calling code actually wants to trigger a commit, it calls drm_atomic_commit. The first stage is the check mentioned above, and if the check is successful, it performs the commit. Part of the commit is a call to drm_atomic_helper_swap_state which turns the new states into the active states. After swapping states, each object's state pointer now refers to the formerly new state. The state_to_destroy now refers to the formerly old state.
• Once done, and when the last reference to our drm_atomic_commit is given up through drm_atomic_commit_put, it calls __drm_atomic_commit_free. In turn, __drm_atomic_commit_free calls drm_atomic_commit_clear that will free all state_to_destroy (ie. old states), and it finally frees drm_atomic_commit instance.
• Now, we don't have any active drm_atomic_commit anymore, and only the entity active states remain allocated.

🌈 SEE ALSO 🌈

Kernel file ./drivers/gpu/drm/drm_atomic.c, plus the whole reference squad, bestie: 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), handling driver private state(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 💋 from the source at ./drivers/gpu/drm and the date October 2026, on the state lifetime(9) page. periodt 🫶