PERCPU(9)

PERCPU(9) | Kernel Developer's Manual | PERCPU(9)

# NAME

`percpu`, `percpu_alloc`, `percpu_free`, `percpu_getref`, `percpu_putref`, `percpu_foreach` —
per-CPU storage allocator

# SYNOPSIS

`#include <sys/percpu.h>`

typedef void (*percpu_callback_t)(void *, void *, struct cpu_info *);

percpu_t *
`percpu_alloc`(size_t size);

void
`percpu_free`(percpu_t *pc, size_t size);

void *
`percpu_getref`(percpu_t *pc);

void
`percpu_putref`(percpu_t *pc);

void
`percpu_foreach`(percpu_t *pc, percpu_callback_t cb, void *arg);

# DESCRIPTION

The machine-independent `percpu` interface provides per-CPU, CPU-local memory reservations to kernel subsystems. `percpu_alloc`(size); reserves on each CPU an independent memory region of size bytes that is local to that CPU, returning a handle (percpu_t) to those regions. A thread may subsequently ask for a pointer, p, to the region held by the percpu_t on the thread's current CPU. Until the thread relinquishes the pointer, or voluntarily sleeps, the thread may read or write the region at p without causing interprocessor memory synchronization.

# FUNCTIONS

`percpu_alloc`(size)
  Call this in thread context to allocate size bytes of local storage on each CPU. The storage is initialized with zeroes. Treat this as an expensive operation. `percpu_alloc`() returns a handle for the per-CPU storage.
`percpu_free`(pc, size)
  Call this in thread context to return to the system the per-CPU storage held by pc. size should match the size passed to `percpu_alloc`(). When `percpu_free`() returns, pc is undefined. Treat this as an expensive operation.
`percpu_getref`(pc)
  Disable preemption and return a pointer to the storage held by pc on the local CPU. Use `percpu_getref`() in either thread or interrupt context. Follow each `percpu_getref`() call with a matching call to `percpu_putref`().
`percpu_putref`(pc)
  Indicate that the thread is finished with the pointer returned by the matching call to `percpu_getref`(). Re-enables preemption.
`percpu_foreach`(pc, cb, arg)
  On each CPU, for ci the corresponding struct cpu_info * and p the CPU-local storage held by pc, run `(*cb)`(p, arg, ci);. Call this in thread context. cb should be non-blocking and fast. Do not rely on cb to be run on the CPUs in any particular order.

# CODE REFERENCES

The `percpu` interface is implemented within the file sys/kern/subr_percpu.c.

# SEE ALSO

atomic_ops(3), kmem(9), pcq(9), pool_cache(9), xcall(9)

# HISTORY

The `percpu` interface first appeared in NetBSD 6.0.

# AUTHORS

YAMAMOTO Takashi <yamt@NetBSD.org>

May 31, 2017 | NetBSD 9.5