percpu(9) - NetBSD Manual Pages

Command:
Section:
Arch:
Collection:
>>>
PERCPU(9)              NetBSD 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 mem-
     ory 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 subse-
     quently 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 vol-
     untarily 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 suc-
              cess.

     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>

NetBSD 6.0                     January 23, 2010                     NetBSD 6.0