PMAP_ENTER(9)

💖 PMAP_ENTER 💖

okay bestie, gather round, because we're about to talk about pmap_enter — it's a kernel developer's manual page (section 9, iykyk) and it's literally the function that slides a virtual page into a physical map. main character energy fr. 🦋

---

✨ NAME ✨

pmap_enter — insert a virtual page into a physical map

---

🌸 SYNOPSIS 🌸

#include <sys/param.h>
#include <vm/vm.h>
#include <vm/pmap.h>

int
pmap_enter(pmap_t pmap, vm_offset_t va, vm_page_t m, vm_prot_t prot,
    u_int flags, int8_t psind);

---

🎀 DESCRIPTION 🎀

so what does pmap_enter() actually do, you ask? it creates a mapping in the physical map pmap, going from the virtual address va to the physical page m, with the protection prot. and bestie, listen — any previous mapping sitting at that virtual address va? destroyed. gone. not even a little bit sorry about it. 💅

the flags argument can have the following values:

• VM_PROT_READ — a read access to the given virtual address is what triggered this call.
• VM_PROT_WRITE — a write access to the given virtual address is what triggered this call.
• VM_PROT_EXECUTE — an execute access to the given virtual address is what triggered this call.
• PMAP_ENTER_WIRED — the mapping should be marked as wired.
• PMAP_ENTER_NOSLEEP — this function may not sleep while it's creating the mapping. if the mapping can't be created without sleeping, an appropriate Mach VM error gets returned. 😴🚫

now here's the tea: if the PMAP_ENTER_NOSLEEP flag is not specified, this function must create the requested mapping before it returns. it may not fail. periodt. and to make that mapping happen, it's allowed to destroy any non-wired mapping in any pmap. yes, any pmap. it's giving unhinged but that's the job. 🔥

the psind parameter says which page size the mapping should use. the supported page sizes are described by the global array pagesizes[]. you specify the page size you want by passing the index of the array element that equals the desired page size. simple as. ⭐

when pmap_enter() destroys or updates a managed mapping — including an existing mapping at virtual address va — it updates the vm_page structure corresponding to the previously mapped physical page. so if that physical page was accessed through the managed mapping, the vm_page structure's PGA_REFERENCED aflag gets set. and if the physical page was modified through the managed mapping, then the vm_page_dirty() function is called on the vm_page structure. keeping receipts, always. 📝

the PGA_WRITEABLE aflag must be set for the page m if the new mapping is managed and writeable. and it is advised to clear PGA_WRITEABLE for destroyed mappings, if the implementation can ensure that no other writeable managed mappings for the previously mapped pages exist. ok so that's a soft recommendation, not a hard rule — but bestie, do it if you can. 🙏

if the request modifies an existing mapping to use a different physical page, an implementation of pmap_enter must invalidate the previous mapping before installing the new one. why? because this ensures that all threads sharing the pmap keep a consistent view of the mapping, which is necessary for the correct handling of CoW (copy on write) faults. no vibes-based mapping over here. consistency is the moment. ✨

if the page m is managed, the page must be busied by the caller, or the owning object must be locked. and in that later case, the PMAP_ENTER_NOSLEEP must be specified by the caller. don't forget it, bestie, that one's on you. 🙈

also, the pmap_enter() function must handle the multiprocessor TLB consistency for the given address. it's a whole thing. TLB stays coherent, no cap. 🧚

---

💜 NOTES 💜

on arm and i386 architectures, the existing implementation of the pmap_enter function is incomplete — only value 0 for psind is supported. 💀

other supported architectures, except amd64, have a pagesizes[] array of size 1. so like, one page size, one option, no choices. iconic in its own minimalist way.

---

🌈 RETURN VALUES 🌈

if it all goes well, pmap_enter() returns KERN_SUCCESS. slay. 🎉

but if the PMAP_ENTER_NOSLEEP flag was specified and the resources required for the mapping can't be acquired without sleeping, KERN_RESOURCE_SHORTAGE is returned. that's the "sorry bestie, I can't sleep on the job" error. 😭

---

🦋 SEE ALSO 🦋

• pmap(9)

---

👑 AUTHORS 👑

this manual page was first written by Bruce M Simpson <bms@spc.org> and then rewritten by Alan Cox <alc@FreeBSD.org> and Konstantin Belousov <kib@FreeBSD.org>. legends, all of them, honestly. 🫶

---

and that's the whole page, bestie! this one came to you courtesy of the Debian crew, dated December 16, 2018 — so go forth and map those virtual pages responsibly. PMAP_ENTER(9) out. 💖✨🎀