STRUCT DRM_ATOMIC_COMMIT(9)

📦 version 7.3.1, in nixpkgs unstable

🌸 struct drm_atomic_commit(9) 🌸

okay so this page lives in the Kernel API Manual, and it's all about struct drm_atomic_commit — the atomic commit structure that is literally the main character of a display-state transition. 💅

🎀 NAME 🎀

struct drm_atomic_commit — the atomic commit structure, periodt. It's the struct holding the whole commit's business.

✨ SYNOPSIS ✨

here's the exact struct, bestie — every field stays exactly as printed:

       struct drm_atomic_commit {
           struct kref ref;
           struct drm_device *dev;
           bool allow_modeset : 1;
           bool legacy_cursor_update : 1;
           bool async_update : 1;
           bool duplicated : 1;
           bool checked : 1;
           bool plane_color_pipeline : 1;
           struct __drm_colorops_state *colorops;
           struct __drm_planes_state *planes;
           struct __drm_crtcs_state *crtcs;
           int num_connector;
           struct __drm_connnectors_state *connectors;
           int num_private_objs;
           struct __drm_private_objs_state *private_objs;
           struct drm_modeset_acquire_ctx *acquire_ctx;
           struct drm_crtc_commit *fake_commit;
           struct work_struct commit_work;
        };

👑 Members 👑

okay bestie, here's the member-by-member tea. 🫖

  • ref — count of all references to this update; it will not be freed until this hits zero.
  • dev — the parent DRM device.
  • allow_modeset — allow full modeset. This is used by the ATOMIC IOCTL handler to implement the DRM_MODE_ATOMIC_ALLOW_MODESET flag. Drivers should generally not consult this flag, but instead look at the output of drm_atomic_crtc_needs_modeset. The detailed rules are:
    • Drivers must not consult allow_modeset in the atomic commit path. Use drm_atomic_crtc_needs_modeset instead.
    • Drivers must consult allow_modeset before adding an unrelated struct drm_crtc_state to this commit by calling drm_atomic_get_crtc_state. See also the warning in the documentation for that function.
    • Drivers must never change this flag; it is under the exclusive control of userspace.
    • Drivers may consult allow_modeset in the atomic check path, if they have the choice between an optimal hardware configuration which requires a modeset, and a less optimal configuration which can be committed without a modeset. An example would be suboptimal scanout FIFO allocation resulting in increased idle power consumption. This allows userspace to avoid flickering and delays for the normal composition loop at reasonable cost.
  • legacy_cursor_update — hint to enforce legacy cursor IOCTL semantics.
WARNING: This is thoroughly broken and pretty much impossible to implement correctly. Drivers must ignore this and should instead implement drm_plane_helper_funcs.atomic_async_check and drm_plane_helper_funcs.atomic_async_commit hooks. New users of this flag are not allowed.
  • async_update — hint for asynchronous plane update.
  • duplicated — indicates whether or not this atomic state was duplicated using drm_atomic_helper_duplicate_state. Drivers and atomic helpers should use this to fixup normal inconsistencies in duplicated states.
  • checked — indicates the state has been checked and thus must no longer be mutated. For internal use only; do not consult from drivers.
  • plane_color_pipeline — indicates whether this atomic state originated with a client that set the DRM_CLIENT_CAP_PLANE_COLOR_PIPELINE.

Drivers and helper functions should use this to ignore legacy properties that are incompatible with the drm_plane COLOR_PIPELINE behavior, such as:

  • COLOR_RANGE
  • COLOR_ENCODING

or any other driver-specific properties that might affect pixel values.

  • colorops — pointer to array of drm_colorop and drm_colorop_state part of this update.
  • planes — pointer to array of drm_plane and drm_plane_state part of this update.
  • crtcs — pointer to array of drm_crtc and drm_crtc_state part of this update.
  • num_connector — size of the connectors array.
  • connectors — pointer to array of drm_connector and drm_connector_state part of this update.
  • num_private_objs — size of the private_objs array.
  • private_objs — pointer to array of drm_private_obj and drm_private_obj_state part of this update.
  • acquire_ctx — acquire context for this atomic modeset state update.
  • fake_commit — used for signaling unbound planes/connectors. When a connector or plane is not bound to any CRTC, it's still important to preserve linearity to prevent the atomic states from being freed too early.

This commit (if set) is not bound to any CRTC, but will be completed when drm_atomic_helper_commit_hw_done is called.

  • commit_work — work item which can be used by the driver or helpers to execute the commit without blocking.

💖 Description 💖

This structure is the kernel counterpart of drm_mode_atomic and represents an atomic commit that transitions from an old to a new display state. It contains all the objects affected by the atomic commit and both the new state structures and pointers to the old state structures for 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 💀

okay storytime, because this struct has lore. struct drm_atomic_commit 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_commit, 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_commit structure the old state.

Over time, and in order to avoid confusion, drm_atomic_commit 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_commit parameter called names like "old_state". This doesn't necessarily mean that the previous drm_atomic_commit 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_commit as a parameter to those operations. Similarly, the transition isn't complete yet, and one might still find atomic operations taking a drm_atomic_commit pointer, or a component state pointer. The former is the preferred form.

🔗 SEE ALSO 🔗

Kernel file ./include/drm/drm_atomic.h — and here's the whole linked friend group, all references kept exactly:

💖 that's the tea, bestie — source: ./include/drm, October 2026, all about struct drm_atomic_commit(9) 🫶

📦 where this page comes from