drm_crtc_arm_vblank_event(9)

📦 version 7.3.1, in nixpkgs unstable

💅 drm_crtc_arm_vblank_event(9) — the Kernel API Manual, bestie edition ✨

okay so you found the page for drm_crtc_arm_vblank_event in the Kernel API Manual and honestly? iconic of you. this is the "arm a vblank event after pageflip" girlie, and she has ✨opinions✨. let's get into it 🎀

✨ NAME ✨

drm_crtc_arm_vblank_event — arm vblank event after pageflip 🦋

🌸 SYNOPSIS 🌸

void drm_crtc_arm_vblank_event (struct drm_crtc *crtc , struct
drm_pending_vblank_event *e );

💖 ARGUMENTS 💖

  • crtc — the source CRTC of the vblank event 👑 like, the CRTC that's sending this whole thing
  • e — the event to send 💌 the actual event that goes out

🌈 DESCRIPTION 🌈

so real talk: a lot of drivers need to generate vblank events for the very next vblank interrupt. why? say the page flip interrupt fires off when the page flip gets armed — not when it actually executes within the next vblank period. awkward, right? 😭

this helper function implements exactly the required vblank arming behaviour. no cap, that's literally its whole job 💅

⚠️ NOTE ⚠️

bestie. listen to me. this is the important part 🚨

drivers using this to send out the drm_crtc_state.event as part of an atomic commit must ensure that the next vblank happens at exactly the same time as the atomic commit is committed to the hardware. this function itself does not protect against the next vblank interrupt racing with either this function call or the atomic commit operation. 💀

a possible sequence could be:

  1. Driver commits new hardware state into vblank-synchronized registers.
  2. A vblank happens, committing the hardware state. Also the corresponding vblank interrupt is fired off and fully processed by the interrupt handler.
  3. The atomic commit operation proceeds to call drm_crtc_arm_vblank_event.
  4. The event is only send out for the next vblank, which is wrong.

and an equivalent race can happen when the driver calls drm_crtc_arm_vblank_event before writing out the new hardware state. yes, both directions. she bites either way 🐍

the only way to make this work safely is to prevent the vblank from firing (and the hardware from committing anything else) until the entire atomic commit sequence has run to completion. if the hardware does not have such a feature (e.g. using a "go" bit), then it is unsafe to use this functions. instead, drivers need to manually send out the event from their interrupt handler by calling drm_crtc_send_vblank_event and make sure that there's no possible race with the hardware committing the atomic update. 🙏

last thing, and it's a big one: caller must hold a vblank reference for the event e acquired by a drm_crtc_vblank_get, which will be dropped when the next vblank arrives. 🫶 don't skip the ref, don't lose the ref.

🦋 SEE ALSO 🦋

the whole vblank cinematic universe, fr fr:

anyway that's the page 💜 sourced from ./drivers/gpu/drm, dated October 2026, living in the Kernel API Manual — mwah, go hold your vblank ref, ily, bye 🧚‍♀️✨

📦 where this page comes from