CONTIGMALLOC(9)

💖 CONTIGMALLOC(9) — the kernel dev manual, but make it make sense 💖

okay so bestie, we're talking about contigmalloc and contigfree — the duo that manages contiguous kernel physical memory. yes it's a 9 page, yes it's kernel dev territory, and yes you're gonna slay it. 🫶

---

✨ SYNOPSIS ✨

first things first, the includes. you need these:

#include <sys/types.h>
#include <sys/malloc.h>

and here's your girl contigmalloc():

void *
contigmalloc(unsigned long size, struct malloc_type *type, int flags,
    vm_paddr_t low, vm_paddr_t high, unsigned long alignment,
    vm_paddr_t boundary);

and her bestie contigfree():

void
contigfree(void *addr, unsigned long size, struct malloc_type *type);

now, if you're doing the numa thing (we'll get there), swap those includes out for:

#include <sys/param.h>
#include <sys/domainset.h>

and here's the fancy variant:

void *
contigmalloc_domainset(unsigned long size, struct malloc_type *type,
    struct domainset *ds, int flags, vm_paddr_t low, vm_paddr_t high,
    unsigned long alignment, vm_paddr_t boundary);

---

🌸 DESCRIPTION 🌸

so contigmalloc() is the one that gets you size bytes of contiguous physical memory. and like, it's not just any memory — it's aligned to alignment bytes, and it does NOT cross a boundary of boundary bytes. the way that matters for hardware. 💅

if it works, the allocation is gonna live between physical addresses low and high. the pointer you get back points to a wired kernel virtual address range of size bytes, allocated from the kernel virtual address (KVA) map. wired means it's staying put, no cap. 🔥

contigmalloc_domainset() is literally the same thing but you also get to pick a numa(4) domain selection policy. that's what the ds is for. if you want to see what kinds of policies exist, go peek at domainset(9) — it's got examples and everything. 👑

now the flags parameter, which changes how contigmalloc() behaves:

• M_ZERO — makes the allocated physical memory get zero filled. clean slate energy. ✨
• M_NOWAIT — makes contigmalloc() return NULL if it can't fulfill the request immediately because of a resource shortage. like, no waiting, no patience, it's giving instant-answer-or-nothing. 💀

other flags? if there are any, they get ignored. not our problem. 🙈

and contigfree()? she's the one who deallocates memory from a previous call to contigmalloc() or contigmalloc_domainset(). you allocated it, you free it, that's the cycle. periodt.

---

🛠️ IMPLEMENTATION NOTES 🛠️

okay here's the tea. contigmalloc() does not sleep waiting for memory resources to get freed up. instead it actively reclaims pages before it gives up. main character behavior honestly.

but — and this is a big but — unless you specified M_NOWAIT, it might select a page for reclamation that has to be written to backing storage first. and that? that can make it sleep. so like, it's not sleeping for memory, but it can still end up sleeping. iykyk. 😭

also, important: contigfree() does not accept NULL as an address input. unlike free(9). so don't come at her with NULL, she's not that kind of function. 🚫

---

⭐ RETURN VALUES ⭐

contigmalloc() hands you a kernel virtual address if the allocation succeeds. if it doesn't? you get NULL. that's it, that's the whole thing. 💜

---

🌈 EXAMPLES 🌈

okay let's actually see it in action:

void *p;
p = contigmalloc(8192, M_DEVBUF, M_ZERO, 0, (1L << 22),
    32 * 1024, 1024 * 1024);

so what did we just ask for? 8192 bytes of zero-filled memory, sitting between physical address 0 and 4194303 inclusive, aligned to a 32K boundary, and not crossing a 1M address boundary. iconic request, honestly. 🎀

---

💀 DIAGNOSTICS 💀

bestie. listen. contigmalloc() will panic if size is zero. it will ALSO panic if alignment or boundary is not a power of two. no negotiating, no warnings, just panic. so double-check those before you ship it. 😭

---

👑 SEE ALSO 👑

• malloc(9)
• memguard(9)

---

and that's the whole page, bestie!! 💖 this was the Debian build of the kernel dev manual, dated October 30, 2018 — go forth and allocate contiguously, you absolute legend. 🦋✨🎀