kvm_pgtable_stage2_annotate(9)

📦 version 7.3.1, in nixpkgs unstable

💅 kvm_pgtable_stage2_annotate(9) 💅

okay so bestie, welcome to the Kernel API Manual, section 9 — this is the <pink>kvm_pgtable_stage2_annotate</pink> girlie and she's here to help you claim what's yours in the IPA space 🎀

✨ NAME ✨

kvm_pgtable_stage2_annotate — unmap and annotate pages in the IPA space so you can track ownership (and honestly, so much more). 👑

🦋 SYNOPSIS 🦋

int kvm_pgtable_stage2_annotate (struct kvm_pgtable *pgt , u64 addr ,
u64 size , void *mc , enum kvm_invalid_pte_type type , kvm_pte_t
annotation );

literally the whole signature, no cap. 📎

🌸 ARGUMENTS 🌸

  • pgt — the page-table struct, and it must have been initialised by kvm_pgtable_stage2_init*() first. no shortcuts babe, she needs her setup 💖
  • addr — base intermediate physical address you're annotating. where the magic starts. ✨
  • size — how big the annotated range is, i.e. how much of the IPA space is getting the treatment. 📏
  • mc — the cache of pre-allocated, already-zeroed memory that page-table pages get allocated from. it's giving prepared queen 🧚
  • type — the type of the annotation; this is the whole personality of it, since it determines its meaning and its format. 🎭
  • annotation — a 59-bit value that gets stored in the page tables. lowkey crucial details: annotation[0] and annotation[63:60] must be 0, and annotation[59:1] is what's actually stored in the page tables, along with type. 🫶
fr fr, annotation[0] and annotation[63:60] must be 0 — don't try to be cute and sneak bits in there. 🙈

💜 DESCRIPTION 💜

so by default, all page-tables are owned by identifier 0. like, everyone starts out as ID zero, that's just the vibe. 🌈

this function is how you branch out: you can use it to mark portions of the IPA space as owned by other entities. main character energy for everyone involved 💅

and here's the slay part — when a stage 2 is used with identity-mappings, these annotations let you use the page-table data structure as a simple rmap. iconic honestly. 🔥

⭐ RETURN ⭐

  • 0 on success 🎉
  • a negative error code on failure 😭

🌈 SEE ALSO 🌈

start with the kernel file itself: ./arch/arm64/include/asm/kvm_pgtable.h — go read the source bestie, it ate 🍓

then the whole friend group, all present and accounted for:

okay that's the whole page!! 🫶 this one ships out from ./arch/arm64/include/asm, dated October 2026, and it's kvm_pgtable_stage2_annotate(9) signing off from the Kernel API Manual. mwah 💋 go annotate something, you've got this ✨🎀🦋

📦 where this page comes from