PMAP_QUICK_ENTER_PAGE(9)

💖 PMAP_QUICK_ENTER_PAGE 💖

okay bestie, so this is a page from the Kernel Developer's Manual — section 9, the deep lore section — and it's literally about yeeting a single page into kernel address space for like two seconds and then putting it back. so iconic of it.

✨ NAME ✨

pmap_quick_enter_page, pmap_quick_remove_page — manage fast, single-page kernel address space mappings 🦋

like, the speedrun version of mapping. no cap.

🌸 SYNOPSIS 🌸

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

vm_offset_t
pmap_quick_enter_page(vm_page_t m);

void
pmap_quick_remove_page(vm_offset_t kva);

💅 DESCRIPTION 💅

So pmap_quick_enter_page() takes one single page, m, and slots it into a preallocated address in kernel virtual address (KVA) space. that's it, that's the whole vibe. it's made for temporary mappings that you're only gonna use for a very short period — think a copy operation on the page contents. blink and it's gone, fr fr.

Then pmap_quick_remove_page() does the clean-up era: it removes a mapping that pmap_quick_enter_page() made earlier at kva, which frees up that KVA frame so pmap_quick_enter_page() can reuse it. recycle, reduce, reuse 🫶

okay now the part where you gotta pay attention. 👀 On many architectures, pmap_quick_enter_page() uses a per-CPU pageframe. When that's the case, it must disable preemption on the local CPU. and the corresponding pmap_quick_remove_page() call is what re-enables preemption. so, consequence time:

it is not safe for machine-independent code to sleep or perform locking operations while holding these mappings. like, don't do it. 💀

Also — current implementations only guarantee the availability of a single page for the calling thread, so calls to pmap_quick_enter_page() must not be nested. one at a time, bestie. one. at. a. time.

Good news tho: neither pmap_quick_enter_page() nor pmap_quick_remove_page() sleeps, and pmap_quick_enter_page() always returns a valid address. always. periodt. ✨ It's safe to use these functions under all types of locks — except spin mutexes. and it's also safe to use them in all thread contexts — except primary interrupt context. so like, everything except that one specific thing.

And one more rule, don't skip it: the page must not be swapped or otherwise reused while the mapping is active. it has to be either wired or held, or it has to belong to an unmanaged region such as I/O device memory. no exceptions, this is the vibe check. 🌈

🎀 RETURN VALUES 🎀

pmap_quick_enter_page() returns the kernel virtual address that is mapped to the page m. that's your prize. take it. 👑

🦋 SEE ALSO 🦋

• pmap(9)

👑 AUTHORS 👑

This manual page was written by Jason A Harmening <jah@FreeBSD.org>. absolute legend, we stan. 💜

and that's the whole page, bestie — Debian, dated August 6, 2015, PMAP_QUICK_ENTER_PAGE(9). slay, go map something (briefly) 💖✨