[src/trunk]: src/share/man/man9 Add a manual page for per-CPU storage. Someb...

[dyoung <dyoung%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/2c07cb9d1570
branches:  trunk
changeset: 751032:2c07cb9d1570
user:      dyoung <dyoung%NetBSD.org@localhost>
date:      Fri Jan 22 20:11:16 2010 +0000

description:
Add a manual page for per-CPU storage.  Somebody should read this to
make sure I've described it correctly and intelligibly.

TBD: hook this up in the Makefile and in the set lists.

diffstat:

 share/man/man9/percpu.9 |  180 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 180 insertions(+), 0 deletions(-)

diffs (184 lines):

diff -r 54a35e23323c -r 2c07cb9d1570 share/man/man9/percpu.9
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/percpu.9   Fri Jan 22 20:11:16 2010 +0000
@@ -0,0 +1,180 @@
+.\"     $NetBSD: percpu.9,v 1.1 2010/01/22 20:11:16 dyoung 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 January 22, 2010
+.Dt PERCPU 9
+.Os
+.Sh NAME
+.Nm percpu
+.Nd Per-CPU storage
+.Sh SYNOPSIS
+.In sys/percpu.h
+.Vt typedef void (*percpu_callback_t)(void *, void *, struct cpu_info *);
+.Ft void
+.Fn percpu_init "void"
+.Ft void
+.Fn percpu_init_cpu "struct cpu_info *ci"
+.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_init "void"
+Initialize the per-CPU storage subsystem.  This is
+called just once, in
+.Fn main .
+.It Fn percpu_init_cpu "ci"
+Initialize per-CPU storage on the CPU given by
+.Fa ci .
+The kernel must call this before the CPU appears on the
+global CPUs list for
+.Dv CPU_INFO_FOREACH .
+.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
+.Dv NULL
+on failure, and a handle for the per-CPU storage on success.
+.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.
+.Sh CODE REFERENCES
+This section describes places within the
+.Nx
+source tree where actual code implementing the
+.Nm
+interface
+can be found.
+All pathnames are relative to
+.Pa /usr/src .
+.Pp
+The
+.Nm
+interface is implemented within the file
+.Pa sys/kern/subr_percpu.c .
+.\" .Sh EXAMPLES
+.Sh SEE ALSO
+.Xr atomic_ops 3 ,
+.Xr pcq 9 ,
+.Xr queue 9
+.Sh HISTORY
+The
+.Nm
+interface first appeared in
+.Nx 6.0 .
+.Sh AUTHORS
+.An YAMAMOTO Takashi Aq yamt%NetBSD.org@localhost
+.\" .Sh CAVEATS
+.\" .Sh BUGS
+.\" .Sh SECURITY CONSIDERATIONS