PMAP_EXTRACT(9)

💖 PMAP_EXTRACT(9) 💖

okay bestie, welcome to the Kernel Developer's Manual section 9, and today's main character is pmap_extract — the little guy who takes a virtual address and tells you which physical page it's living at. no cap. 🦋

---

✨ NAME ✨

pmap_extract, pmap_extract_and_hold — map a virtual address to a physical page

like, literally the whole job. address in, physical page out. slay. 💅

---

🌸 SYNOPSIS 🌸

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

vm_paddr_t
pmap_extract(pmap_t pmap, vm_offset_t va);

vm_paddr_t
pmap_extract_and_hold(pmap_t pmap, vm_offset_t va, vm_prot_t prot);

so you gotta pull in all three of those headers first — sys/param.h, vm/vm.h, and vm/pmap.h — and then you've got two functions to play with, both handing back a vm_paddr_t. 🎀

---

🫶 DESCRIPTION 🫶

So the pmap_extract() function maps a virtual address to a physical page. that's it, that's the vibe. ✨

But in certain situations, callers may use pmap_extract_and_hold() instead — and the reason you'd do that is to make sure the returned page is held. 🔥

The pmap_extract_and_hold() function maps a virtual address to a physical page and atomically holds the returned page for use by the caller — but only if the mapping permits the given page protection. it's giving responsible. it's giving "i checked first". periodt. 💜

---

🙈 IMPLEMENTATION NOTES 🙈

ngl, currently the page protection requested by the caller is not verified. the prot argument is just... there. living its life. 💀

---

⭐ RETURN VALUES ⭐

okay so here's the tea on what you actually get back:

• pmap_extract() will return the physical page address associated with the virtual address va inside the physical map pmap. 🫧 and if the mapping does not exist, or if the pmap parameter is NULL, then NULL will be returned. no mapping, no address, that simple.
• pmap_extract_and_hold() will return the physical page address associated with the virtual address va inside the physical map pmap. and if the mapping does not exist, the result is a no-op, and NULL will be returned. 😭

so like, NULL is the answer in both failure modes. iconic consistency honestly. 🌈

---

👑 SEE ALSO 👑

• mutex(9)
• pmap(9)

go read those next bestie, i'm serious, pmap(9) is required reading. 📚

---

💖 AUTHORS 💖

The pmap_extract_and_hold() function was implemented by Alan L. Cox <alc@imimic.com>. 🧚

This manual page was written by Bruce M Simpson <bms@spc.org>. 🎀

---

and that's the whole page, bestie!! this one's from the Debian crew, dated July 21, 2003 — ancient but still serving looks. go map some addresses, stay safe, and remember: if it returns NULL, that's not a personality flaw, that's just a missing mapping. 💅✨🦋