CPUMEM_GET(9) | 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 <dlg@openbsd.org>.

August 27, 2020 | Debian