CPUMEM_GET(9)

🌸 CPUMEM_GET(9) 🌸

okay bestie, welcome to the Kernel Developer's Manual — this one's about per CPU memory allocations and it's honestly kind of iconic once you get the vibe. there's a whole fam of functions and macros here (cpumem_get, cpumem_put, cpumem_malloc, cpumem_malloc_ncpus, cpumem_free, CPUMEM_BOOT_MEMORY, CPUMEM_BOOT_INITIALIZER, cpumem_enter, cpumem_leave, cpumem_first, cpumem_next, CPUMEM_FOREACH) and we're gonna go through every single one, no skipping 💅

---

✨ SYNOPSIS ✨

#include <sys/percpu.h>

struct cpumem *
cpumem_get(struct pool *pp);

void
cpumem_put(struct pool *pp, struct cpumem *cm);

struct cpumem *
cpumem_malloc(size_t sz, int type);

struct cpumem *
cpumem_malloc_ncpus(struct cpumem *cm, size_t sz, int type);

void
cpumem_free(struct cpumem *cm, int type, size_t sz);

CPUMEM_BOOT_MEMORY(NAME, size_t sz);

CPUMEM_BOOT_INITIALIZER(NAME);

void *
cpumem_enter(struct cpumem *cm);

void
cpumem_leave(struct cpumem *cm, void *m);

void *
cpumem_first(struct cpumem_iter *ci, struct cpumem *cm);

void *
cpumem_next(struct cpumem_iter *ci, struct cpumem *cm);

CPUMEM_FOREACH(VARNAME, struct cpumem_iter *ci, struct cpumem *cm);

---

💖 DESCRIPTION 💖

so the per CPU memory API is basically a cute little wrapper layer around allocating and accessing per CPU memory. that's the whole job 🫶

plot twist: on uni-processor systems (like, when the kernel is not built with MULTIPROCESSOR defined) there's an alternate implementation of the API that adds literally zero overhead compared to just reaching straight into a data structure. so you can use the API everywhere and it won't tank performance on uni-processor systems. slay ✨

🎀 Per CPU Memory Allocation and Deallocation 🎀

• cpumem_get() allocates memory for each CPU from the pp pool. the memory gets zeroed on allocation, so it's giving clean slate energy.
• cpumem_put() returns each CPU's memory allocation referenced by cm back to the pp pool.
• cpumem_malloc() allocates sz bytes of type memory for each CPU using malloc(9). yep, zeroed on allocation too.
• cpumem_free() hands each CPU's memory allocation referenced by cm back to the system using free(9). ⚠️ you must pass the same object size and type that you originally gave to cpumem_malloc() — that means sz and type respectively. no swapsies.
• cpumem_get() and cpumem_malloc() may only be used after all the CPUs in the system have been attached. that's the rule, periodt. but if you need per CPU memory during early boot, you can statically allocate a cpumem pointer and memory for the boot CPU instead.
• CPUMEM_BOOT_MEMORY() statically allocates memory for use on the boot CPU before the other CPUs in the system have been attached. the allocation is identified by NAME, and gives you the number of bytes specified by the sz argument. the memory is initialised to zeros 🧚
• CPUMEM_BOOT_INITIALIZER() initialises a cpumem pointer with the memory that was previously allocated using CPUMEM_BOOT_MEMORY() and identified by NAME. it's the glow-up step, basically.
• cpumem_malloc_ncpus() allocates additional memory for the CPUs that were attached during boot. the cpumem structure cm must have been initialised with CPUMEM_BOOT_INITIALIZER() first — non-negotiable. the same number of bytes originally passed to COUNTERS_BOOT_MEMORY must be specified by sz. the type argument specifies the type of memory that the counters will be allocated as via malloc(9). the contents of the memory on the boot CPU will be preserved, while the allocations for the additional CPU's will be zeroed on allocation 💜

🚨 big warning, bestie: per CPU memory that's been allocated with CPUMEM_BOOT_MEMORY() and cpumem_malloc_ncpus() cannot be deallocated with cpumem_free. any attempt to do so will lead to undefined behaviour. that's not a vibe check you want to fail 😭

🌈 Per CPU Memory Access 🌈

• cpumem_enter() provides access to the current CPU's memory allocation referenced by cm.
• cpumem_leave() indicates the end of access to the current CPU's memory allocation referenced by cm. it's the little "we're done here" 🫡

🦋 Per CPU Memory Iterators 🦋

• cpumem_first() provides access to the first CPU's memory allocation referenced by cm. the iterator ci may be used in subsequent calls to cpumem_next().
• cpumem_next() provides access to the next CPU's memory allocation referenced by cm and ci.
• CPUMEM_FOREACH() is the macro that iterates over each CPU's memory allocation referenced by cm using the iterator ci, setting VARNAME to each CPU's allocation in turn. it's the main character of this section tbh 👑

---

⭐ CONTEXT ⭐

• cpumem_get(), cpumem_put(), cpumem_malloc(), cpumem_free(), and cpumem_malloc_ncpus() may be called during autoconf, or from process context.
• cpumem_enter(), cpumem_leave(), cpumem_first(), cpumem_next(), and CPUMEM_FOREACH() may be called during autoconf, from process context, or from interrupt context.

🫶 real talk though: the per CPU memory API does not provide any locking or serialisation of access to each CPU's memory allocation. it is up to you, the caller, to provide appropriate locking or serialisation around calls to these functions so you don't get concurrent access to the relevant data structures. no cap, that's on you 💀

---

🔥 RETURN VALUES 🔥

• cpumem_get(), cpumem_malloc(), and cpumem_malloc_ncpus() return an opaque cpumem pointer that references each CPU's memory allocation.
• cpumem_enter() returns a reference to the current CPU's memory allocation.
• cpumem_first() returns a reference to the first CPU's memory allocation.
• cpumem_next() returns a reference to the next CPU's memory allocation according to the iterator ci, or NULL if the iterator has run out of CPUs. that's your cue to stop looping, bestie 🎀

---

🌸 SEE ALSO 🌸

counters_alloc(9), malloc(9), pool_get(9) — go read these next, iykyk ✨

---

🧚 HISTORY 🧚

the per CPU memory API first appeared in OpenBSD 6.1. a genuine icon from day one 💅

---

👑 AUTHORS 👑

the per CPU memory API was written by David Gwynne <dlg@openbsd.org>. king behaviour, honestly 🫶

---

and that's the whole page, bestie — this one came from the Debian edition of the manual, dated August 27, 2020, from CPUMEM_GET(9) to the very last line. mwah 💋✨