IMPLEMENTING NONBLOCKING COMMIT(9)

📦 version 7.3.1, in nixpkgs unstable

💅 implementing nonblocking commit — Kernel API Manual ✨

okay so bestie, welcome to the Kernel API Manual entry on implementing nonblocking commit 🎀 this is the one where we make atomic commits happen without blocking everything, and honestly it's giving main character energy 💜

🌸 NAME 🌸

implementing nonblocking commit — the whole vibe of doing atomic commits asynchronously, no cap ✨

🦋 DESCRIPTION 🦋

Nonblocking atomic commits should use struct drm_crtc_commit to sequence different operations against each another, fr fr. Locks — especially struct drm_modeset_lock — should not be held in worker threads or any other asynchronous context used to commit the hardware state. literally do not do it 🙈

drm_atomic_helper_commit implements the recommended sequence for nonblocking commits, using drm_atomic_helper_setup_commit internally. slay 💅

  1. Run drm_atomic_helper_prepare_planes. Since this can fail and we need to propagate out of memory/VRAM errors to userspace, it must be called synchronously. no skipping, bestie 😭
  2. Synchronize with any outstanding nonblocking commit worker threads which might be affected by the new state update. This is handled by drm_atomic_helper_setup_commit. 🫶

Asynchronous workers need to have sufficient parallelism to be able to run different atomic commits on different CRTCs in parallel. The simplest way to achieve this is by running them on the system_dfl_wq work queue. Note that drivers are not required to split up atomic commits and run an individual commit in parallel — userspace is supposed to do that if it cares. But it might be beneficial to do that for modesets, since those necessarily must be done as one global operation, and enabling or disabling a CRTC can take a long time. But even that is not required. ⭐

IMPORTANT: A drm_atomic_commit update for multiple CRTCs is sequenced against all CRTCs therein. Therefore for atomic state updates which only flip planes the driver must not get the struct drm_crtc_state of unrelated CRTCs in its atomic check code: This would prevent committing of atomic updates to multiple CRTCs in parallel. In general, adding additional state structures should be avoided as much as possible, because this reduces parallelism in (nonblocking) commits, both due to locking and due to commit sequencing requirements. 💀 like, don't do it, iykyk
  1. The software state is updated synchronously with drm_atomic_helper_swap_state. Doing this under the protection of all modeset locks means concurrent callers never see inconsistent state. Note that commit workers do not hold any locks; their access is only coordinated through ordering. If workers would access state only through the pointers in the free-standing state objects (currently not the case for any driver) then even multiple pending commits could be in-flight at the same time. 🧚
  2. Schedule a work item to do all subsequent steps, using the split-out commit helpers: a) pre-plane commit b) plane commit c) post-plane commit and then cleaning up the framebuffers after the old framebuffer is no longer being displayed. The scheduled work should synchronize against other workers using the drm_crtc_commit infrastructure as needed. See drm_atomic_helper_setup_commit for more details. ✨

🔥 SEE ALSO 🔥

the whole friend group, assembled 👑

okay that's the whole page, periodt 💖 this one lives in ./drivers/gpu/drm and it's dated October 2026 — so like, future girlie energy fr fr 🌈 go forth and commit nonblockingly, you absolute icon 👑🎀🦋

📦 where this page comes from