kvm_pgtable_hyp_map(9)

💅 kvm_pgtable_hyp_map(9) 💅

okay so real talk bestie, this is a page straight out of the Kernel API Manual and it's lowkey one of the most useful little functions in the arm64 KVM-adjacent universe, so grab a strawberry drink 🍓 and let's get into it.

---

✨ NAME ✨

kvm_pgtable_hyp_map — installs a mapping in a hypervisor stage-1 page-table. that's it, that's the whole vibe 🫶

---

🌸 SYNOPSIS 🌸

int kvm_pgtable_hyp_map (struct kvm_pgtable *pgt , u64 addr , u64 size ,
u64 phys , enum kvm_pgtable_prot prot );

it's giving very "five arguments, zero notes" energy and honestly? iconic.

---

🎀 ARGUMENTS 🎀

• pgt — the page-table structure, and it has to have been initialised by kvm_pgtable_hyp_init first. no shortcuts, no vibes-only setup, she needs to be properly initialised 💅
• addr — the virtual address where you want the mapping to live.
• size — how big the mapping is.
• phys — the physical address of the memory you're mapping. yes bestie, the actual real memory.
• prot — the permissions and attributes for the mapping. this is where you tell her how to behave.

---

🦋 DESCRIPTION 🦋

okay so here's the tea ☕ — the offset of addr within a page is ignored. like, entirely. not asked, not consulted, just skipped.

meanwhile size gets rounded-up to the next page boundary, and phys gets rounded-down to the previous page boundary. so she's snapping everything to page edges whether you like it or not ✨

if device attributes are not explicitly requested in prot, then the mapping will be normal and cacheable. no cap, that's just the default behavior.

and now the part where you need to pay attention 🙈 — attempts to install a new mapping for a virtual address that is already mapped will be rejected with an error and a WARN. so like, don't try to double-book the same address, she will notice and she will be dramatic about it.

⚠️ re-mapping an already-mapped virtual address = rejected + WARN. this is a "don't do it" situation, not a "try it and see" situation, bestie.

---

🔥 RETURN 🔥

0 on success, negative error code on failure. short, sweet, main character energy 👑

---

👑 SEE ALSO 👑

the whole friend group, and yes we're listing every single one because nobody gets left out:

Kernel file ./arch/arm64/include/asm/kvm_pgtable.h 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_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_map(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 whole page! go map something responsibly, bestie. 🧚

---

mwah 💋 this cutie came from ./arch/arm64/include/asm, dated October 2026, and it's part of the Kernel API Manual — read it, love it, cite it. 🎀✨