.\"     $NetBSD: percpu.9,v 1.12 2017/05/31 23:54:17 chs Exp $
.\"
.\" Copyright (c) 2010 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by David Young.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd May 31, 2017
.Dt PERCPU 9
.Os
.Sh NAME
.Nm percpu ,
.Nm percpu_alloc ,
.Nm percpu_free ,
.Nm percpu_getref ,
.Nm percpu_putref ,
.Nm percpu_foreach
.Nd per-CPU storage allocator
.Sh SYNOPSIS
.In sys/percpu.h
.Vt typedef void (*percpu_callback_t)(void *, void *, struct cpu_info *);
.Ft percpu_t *
.Fn percpu_alloc "size_t size"
.Ft void
.Fn percpu_free "percpu_t *pc" "size_t size"
.Ft void *
.Fn percpu_getref "percpu_t *pc"
.Ft void
.Fn percpu_putref "percpu_t *pc"
.Ft void
.Fn percpu_foreach "percpu_t *pc" "percpu_callback_t cb" "void *arg"
.Sh DESCRIPTION
The machine-independent
.Nm
interface provides per-CPU, CPU-local memory reservations to kernel
subsystems.
.Fo percpu_alloc
.Fa size
.Fc
reserves on each CPU an independent memory region of
.Fa size
bytes that is local to that CPU, returning a handle
.Po
.Vt percpu_t
.Pc
to those regions.
A thread may subsequently ask for a pointer,
.Fa p ,
to the region held by the
.Vt 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
.Fa p
without causing interprocessor memory synchronization.
.Sh FUNCTIONS
.Bl -tag -width compact
.It Fn percpu_alloc "size"
Call this in thread context to allocate
.Fa size
bytes of local storage on each CPU.
The storage is initialized with zeroes.
Treat this as an expensive operation.
.Fn percpu_alloc
returns a handle for the per-CPU storage.
.It Fn percpu_free "pc" "size"
Call this in thread context to
return to the system the per-CPU storage held by
.Fa pc .
.Fa size
should match the
.Fa size
passed to
.Fn percpu_alloc .
When
.Fn percpu_free
returns,
.Fa pc
is undefined.
Treat this as an expensive operation.
.It Fn percpu_getref "pc"
Disable preemption and return a pointer to the storage held by
.Fa pc
on the local CPU.
Use
.Fn percpu_getref
in either thread or interrupt context.
Follow each
.Fn percpu_getref
call with a matching call to
.Fn percpu_putref .
.It Fn percpu_putref "pc"
Indicate that the thread is finished
with the pointer returned by the matching
call to
.Fn percpu_getref .
Re-enables preemption.
.It Fn percpu_foreach "pc" "cb" "arg"
On each CPU, for
.Fa ci
the corresponding
.Vt "struct cpu_info *"
and
.Fa "p"
the CPU-local storage held by
.Fa pc ,
run
.Fo "(*cb)"
.Fa "p"
.Fa "arg"
.Fa "ci"
.Fc .
Call this in thread context.
.Fa cb
should be non-blocking and fast.
Do not rely on
.Fa cb
to be run on the CPUs in any particular order.
.El
.Sh CODE REFERENCES
The
.Nm
interface is implemented within the file
.Pa sys/kern/subr_percpu.c .
.\" .Sh EXAMPLES
.Sh SEE ALSO
.Xr atomic_ops 3 ,
.Xr kmem 9 ,
.Xr pcq 9 ,
.Xr pool_cache 9 ,
.Xr xcall 9
.Sh HISTORY
The
.Nm
interface first appeared in
.Nx 6.0 .
.Sh AUTHORS
.An YAMAMOTO Takashi Aq Mt yamt@NetBSD.org
.\" .Sh CAVEATS
.\" .Sh BUGS
.\" .Sh SECURITY CONSIDERATIONS