CONTIGMALLOC(9)

💖 CONTIGMALLOC(9) 💖

okay so bestie, this is a page from the Kernel Developer's Manual, and it's literally all about smooshing kernel memory into one contiguous physical blob. no cap, it's giving "I need my bytes together" energy. let's get into it 🫶

---

✨ NAME ✨

contigmalloc, contigfree — manage contiguous kernel physical memory 🌸

---

✨ SYNOPSIS ✨

first, the includes (yes, plural, keep up 💅):

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

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);

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

and then the domainset flavor, which has its own includes 🔥:

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

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 the whole main character here is contigmalloc() — it allocates size bytes of contiguous physical memory, and that memory is aligned to alignment bytes, and it does not cross a boundary of boundary bytes. like, boundaries are sacred, periodt. 🎀

if it succeeds, the allocation lives between physical addresses low and high. the pointer it hands back points to a wired kernel virtual address range of size bytes, allocated out of the kernel virtual address (KVA) map. iconic behavior honestly.

the contigmalloc_domainset() variant is the same vibe but lets the caller also specify a numa(4) domain selection policy. see domainset(9) for some example policies. iykyk 🦋

the flags parameter changes how contigmalloc() behaves, and here's the tea:

• M_ZERO — makes the allocated physical memory get zero filled. squeaky clean ✨
• M_NOWAIT — makes contigmalloc() return NULL if the request can't be immediately fulfilled because of a resource shortage. no waiting around, we're booked and busy 💅

any other flags (if present) are just ignored. they're not on the guest list.

then we have contigfree(), which deallocates memory allocated by a previous call to contigmalloc() or contigmalloc_domainset(). but listen—its use is deprecated in favor of free(9), which no longer requires the caller to know the size and also accepts NULL as an address. so like… free(9) ate, honestly. 👑

---

🌟 IMPLEMENTATION NOTES 🌟

important lore: contigmalloc() does not sleep waiting for memory resources to be freed up. instead it actively reclaims pages before giving up. it's a go-getter, a hustler, main character energy fr fr.

but heads up bestie — unless M_NOWAIT is specified, it may select a page for reclamation that must first be written to backing storage, and that causes it to sleep. so it's not a "never sleeps" situation, it's a "doesn't sleep waiting for frees" situation. nuance matters 😭

also, contigfree() does not accept NULL as an address input, unlike free(9). so don't try that, it will not slay.

---

💜 RETURN VALUES 💜

contigmalloc() returns a kernel virtual address if the allocation succeeds, or NULL otherwise. that's it. that's the whole return value story. simple, clean, no drama.

---

🍓 EXAMPLES 🍓

here's a lil example, look at it go:

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

what this is asking for, in human words: 8192 bytes of zero-filled memory residing between physical address 0 and 4194303 inclusive, aligned to a 32K boundary and not crossing a 1M address boundary. she's specific and she knows what she wants 💅✨

---

💀 DIAGNOSTICS 💀

okay so, contigmalloc() will panic if size is zero, or if alignment or boundary is not a power of two. not a warning, not a gentle nudge — a full-on panic. so double-check those numbers before you ship it, bestie 🙈

---

🌈 SEE ALSO 🌈

• malloc(9)
• memguard(9)

---

alright that's the whole page, you ate that 🫶 this one came from the Debian crew and is dated July 22, 2024 — go forth and allocate contiguously, queen 👑💖