kvm_pgtable_stage2_map(9)

💖 NAME 💖

okay so bestie, this is kvm_pgtable_stage2_map(9) from the Kernel API Manual, and the name is literally the assignment: kvm_pgtable_stage2_map — install a mapping in a guest stage-2 page-table. main character page-table energy ✨

✨ SYNOPSIS ✨

int kvm_pgtable_stage2_map (struct kvm_pgtable *pgt , u64 addr , u64
size , u64 phys , enum kvm_pgtable_prot prot , void *mc , enum
kvm_pgtable_walk_flags flags );

🎀 ARGUMENTS 🎀

• pgt — page-table structure initialised by kvm_pgtable_stage2_init*(). gotta be initialised first, bestie.
• addr — intermediate physical address at which to place the mapping.
• size — size of the mapping.
• phys — physical address of the memory to map.
• prot — permissions and attributes for the mapping.
• mc — cache of pre-allocated and zeroed memory from which to allocate page-table pages.
• flags — flags to control the page-table walk (ex. a shared walk). shared walk? noted.

🦋 DESCRIPTION 🦋

The offset of addr within a page is ignored, size is rounded-up to the next page boundary, and phys is rounded-down to the previous page boundary. page math lowkey said what it said, periodt 💅

If device attributes are not explicitly requested in prot, then the mapping will be normal, cacheable. normal + cacheable, iykyk.

Note that the update of a valid leaf PTE in this function will be aborted, if it's trying to recreate the exact same mapping or only change the access permissions. Instead, the vCPU will exit one more time from guest if still needed and then go through the path of relaxing permissions. so that update gets aborted — fr fr, no cap.

Note that this function will both coalesce existing table entries and split existing block mappings, relying on page-faults to fault back areas outside of the new mapping lazily. coalesce + split, lazy fault-back, iconic behaviour 😭

🌸 RETURN 🌸

0 on success, negative error code on failure. slay when it's zero, sad little negative when it's not.

💅 SEE ALSO 💅

Kernel file ./arch/arm64/include/asm/kvm_pgtable.h — plus the whole friend group:

• struct kvm_pgtable_mm_ops(9)
• enum kvm_pgtable_stage2_flags(9)
• enum kvm_pgtable_prot(9)
• enum kvm_pgtable_walk_flags(9)
• struct kvm_pgtable_walker(9)
• struct kvm_pgtable(9)
• kvm_pgtable_hyp_init(9)
• kvm_pgtable_hyp_destroy(9)
• kvm_pgtable_hyp_map(9)
• kvm_pgtable_hyp_unmap(9)
• kvm_get_vtcr(9)
• kvm_pgtable_stage2_pgd_size(9)
• __kvm_pgtable_stage2_init(9)
• kvm_pgtable_stage2_destroy(9)
• kvm_pgtable_stage2_destroy_range(9)
• kvm_pgtable_stage2_destroy_pgd(9)
• kvm_pgtable_stage2_free_unlinked(9)
• kvm_pgtable_stage2_create_unlinked(9)
• kvm_pgtable_stage2_annotate(9)
• kvm_pgtable_stage2_unmap(9)
• kvm_pgtable_stage2_wrprotect(9)
• kvm_pgtable_stage2_mkyoung(9)
• kvm_pgtable_stage2_test_clear_young(9)
• kvm_pgtable_stage2_relax_perms(9)
• kvm_pgtable_stage2_split(9)
• kvm_pgtable_walk(9)
• kvm_pgtable_get_leaf(9)
• kvm_pgtable_stage2_pte_prot(9)
• kvm_pgtable_hyp_pte_prot(9)
• kvm_tlb_flush_vmid_range(9)

and that's the vibe check, bestie 🫶 source path on the footer is ./arch/arm64/include/asm, date is October 2026, and the manual is kvm_pgtable_stage2_map(9) — mwah 💋