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
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>.