CPUMEM_GET(9) FreeBSD Kernel Developer's Manual CPUMEM_GET(9)
NAME
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 - per CPU memory allocations
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
The per CPU memory API provides wrappers around the allocation of and
access to per CPU memory.
An alternate implementation of the API is provided on uni-processor (i.e.
when the kernel is not built with MULTIPROCESSOR defined) systems that
provides no overhead compared to direct access to a data structure. This
allows the API to be used without affecting the performance on uni-
processor systems.
Per CPU Memory Allocation and Deallocation
cpumem_get() allocates memory for each CPU from the pp pool. The memory
will be zeroed on allocation.
cpumem_put() returns each CPUs memory allocation referenced by cm to the
pp pool.
cpumem_malloc() allocates sz bytes of type memory for each CPU using
malloc(9). The memory will be zeroed on allocation.
cpumem_free() returns each CPU's memory allocation referenced by cm to
the system using free(9). The same object size and type originally
provided to cpumem_malloc() must be specified by sz and type
respectively.
cpumem_get() and cpumem_malloc() may only be used after all the CPUs in
the system have been attached. If per CPU memory needs to be available
during early boot, a cpumem pointer and memory for the boot CPU may be
statically allocated.
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 provides the number of bytes specified by the
sz argument. The memory will be initialised to zeros.
CPUMEM_BOOT_INITIALIZER() is used to initialise a cpumem pointer with the
memory that was previously allocated using CPUMEM_BOOT_MEMORY() and
identified by NAME.
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(). 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.
Per CPU memory that has 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.
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.
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.
The CPUMEM_FOREACH() macro iterates over each CPU's memory allocation
referenced by cm using the iterator ci, setting VARNAME to each CPU's
allocation in turn.
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. The per CPU memory API does not provide any
locking or serialisation of access to each CPU's memory allocation. It
is up to the caller to provide appropriate locking or serialisation
around calls to these functions to prevent concurrent access to the
relevant data structures.
RETURN VALUES
cpumem_get(), cpumem_malloc(), and cpumem_malloc_ncpus() will 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.
SEE ALSO
counters_alloc(9), malloc(9), pool_get(9)
HISTORY
The per CPU memory API first appeared in OpenBSD 6.1.
AUTHORS
The per CPU memory API was written by David Gwynne <
[email protected]>.
FreeBSD 14.1-RELEASE-p8 August 27, 2020 FreeBSD 14.1-RELEASE-p8