drm_atomic_h...r_swap_state(9)

📦 version 7.3.1, in nixpkgs unstable

💅 drm_atomic_helper_swap_state(9) — Kernel API Manual, but make it make sense

okay so bestie, welcome to the drm_atomic_helper_swap_state page from the Kernel API Manual. this is the glow-up moment for your atomic state, no cap. let's get into it 🎀

✨ NAME ✨

drm_atomic_helper_swap_state — store atomic state into current sw state

like literally, it takes your staged atomic state and shoves it into the current state. that's the whole vibe. 🦋

🌸 SYNOPSIS 🌸

int drm_atomic_helper_swap_state (struct drm_atomic_commit *state , bool
stall );

🫶 ARGUMENTS 🫶

  • state — atomic state. the state bestie. the one being swapped. 👑
  • stall — stall for preceding commits. you set this and the function will literally wait around for the earlier commits to finish. 💀

🔥 DESCRIPTION 🔥

This function stores the atomic state into the current state pointers in all driver objects. Read that again. all driver objects. it's giving main character energy, and honestly? it earned it. ✨

When do you call it? Timing is everything, bestie: it should be called after all the failing steps have been done and succeeded, but before the actual hardware state is committed. so like — past the danger zone, not yet at the finish line. 🎯

And for cleanup / error recovery? the current state for all changed objects will be swapped into state. so the old stuff lives on in state, which is genuinely so useful. 🙈

With that sequence it fits perfectly into the plane prepare/cleanup sequence, and here's the choreography:

  1. Call drm_atomic_helper_prepare_planes with the staged atomic state.
  2. Do any other steps that might fail.
  3. Put the staged state into the current state pointers with this function.
  4. Actually commit the hardware state.
  5. Call drm_atomic_helper_cleanup_planes with state, which since step 3 contains the old state. Also do any other cleanup required with that state.

see how clean that is? steps 1–5, no notes. ate. 💅

⚠️ okay important: stall must be set when nonblocking commits for this driver directly access the drm_plane.state, drm_crtc.state or drm_connector.state pointer. With the current atomic helpers this is almost always the case, since the helpers don't pass the right state structures to the callbacks. so yeah, set it. like, basically always. 😭

⭐ RETURN ⭐

Returns 0 on success, icon behaviour honestly. 🌈

Can return -ERESTARTSYS when stall is true and the waiting for the previous commits has been interrupted. rude of the interrupt, but okay. 💀

👑 SEE ALSO 👑

the whole friend group, fr fr — go read these next:

and that's the page!! 🧚 this little cutie lives in ./drivers/gpu/drm and the docs are dated October 2026 — screenshot it, cite it, live by it. mwah 💜

📦 where this page comes from