efi_capsule_update(9)

📦 version 7.3.1, in nixpkgs unstable

💅 efi_capsule_update(9)

okay so real talk, this is a page from the Kernel API Manual, and it's about efi_capsule_update — the lil function that hands a capsule over to your firmware. yes bestie, that kind of capsule. no, not the medicine one 😭 it's the firmware update kind. buckle up 🎀

✨ NAME ✨

efi_capsule_update — send a capsule to the firmware 🚀

🌸 SYNOPSIS 🌸

int efi_capsule_update (efi_capsule_header_t *capsule , phys_addr_t *pages );

like, that's the whole signature. short king. 👑

🦋 ARGUMENTS 🦋

  • capsule — the capsule you're sending to the firmware, literally the whole point of the function 💖
  • pages — an array of capsule data pages, i.e. where the actual payload lives 🌈

🔥 DESCRIPTION 🔥

So what does it do? It builds a scatter gather list with EFI capsule block descriptors — yes, that's a lot of words, it ate — and uses them to map the capsule described by capsule together with its data in pages, then sends the whole thing to the firmware via the UpdateCapsule runtime service. periodt. ✨

Big important thing: capsule must be a virtual mapping of the complete capsule update in the kernel address space, because the capsule can be consumed immediately — like, not "in a sec", not "after you finish your iced coffee", immediately 😭. And a capsule_header_t that describes the entire contents of the capsule must be at the start of the first data page. no exceptions bestie 💅

Now, this function will validate that the firmware supports the capsule guid, but honestly? users will likely want to check that efi_capsule_supported returns true before calling this function, because it makes it way easier to print helpful error messages. you know, the ones that actually tell you what went wrong instead of just vibing mysteriously 💀

If the capsule is successfully submitted to the firmware, any subsequent calls to efi_capsule_pending will return true. So pages must not be released or modified if this function returns successfully. like, do NOT touch them. leave them alone. they're busy 🫶

⚠️ Callers must be prepared for this function to fail, which can happen if we raced with system reboot, or if there is already a pending capsule that has a reset type that conflicts with the one required by capsule. scary? a little. real? very. 🙈

And this next part is the big one, so listen up: do NOT use efi_capsule_pending to detect this conflict, because that would be racy. Instead, submit the capsule to efi_capsule_update and check the return value. that's the move. that's the whole strategy. iykyk 💜

Return 0 on success, and a converted EFI status code on failure. that's it, that's the deal ⭐

👑 SEE ALSO 👑

Kernel file ./drivers/firmware/efi/capsule.c, plus the whole friend group:

go read them, they're iconic too 🧚

aaaand that's the page!! 💖 brought to you from ./drivers/firmware/efi, dated October 2026, and yes the manual page is literally named efi_capsule_update(9) because we keep it consistent in this house 🎀 slay, go update some firmware responsibly, mwah 🫶✨

📦 where this page comes from