PERCPU(9)						   BSD 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 NULL on failure, and a handle for the per-CPU storage on success.

     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 inter-
	      rupt 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>

BSD
								 January 23, 2010							       BSD