first cut at a man page for cpumem

2 files changed, 214 insertions, 2 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index de8cf732dde..05dd94b749b 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.281 2016/09/15 17:53:38 awolk Exp $
+#	$OpenBSD: Makefile,v 1.282 2016/10/21 07:57:29 dlg Exp $
 #	$NetBSD: Makefile,v 1.4 1996/01/09 03:23:01 thorpej Exp $
 
 #	Makefile for section 9 (kernel function and variable) manual pages.
@@ -9,7 +9,7 @@ MAN=	aml_evalnode.9 atomic_add_int.9 atomic_cas_uint.9 \
 	audio.9 autoconf.9 \
 	bemtoh32.9 bio_register.9 boot.9 bpf_mtap.9 buffercache.9 bufq_init.9 \
 	bus_dma.9 bus_space.9 \
-	copy.9 config_attach.9 config_defer.9 crypto.9 delay.9 \
+	copy.9 config_attach.9 config_defer.9 cpumem_get.9 crypto.9 delay.9 \
 	disk.9 disklabel.9 dma_alloc.9 dohooks.9 \
 	dostartuphooks.9 \
 	evcount.9 extent.9 fb_setup.9 file.9 fork1.9 \
diff --git a/share/man/man9/cpumem_get.9 b/share/man/man9/cpumem_get.9
new file mode 100644
index 00000000000..43c4aa89584
--- /dev/null
+++ b/share/man/man9/cpumem_get.9
@@ -0,0 +1,212 @@
+.\"	$OpenBSD: cpumem_get.9,v 1.1 2016/10/21 07:57:29 dlg Exp $
+.\"
+.\" * Copyright 2002 Niels Provos <provos@citi.umich.edu>
+.\" * All rights reserved.
+.\" *
+.\" * 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 AUTHOR ``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 AUTHOR 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.
+.\" */
+.\"
+.\" Copyright (c) 2016 David Gwynne <dlg@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: October 21 2016 $
+.Dt cpumem_get 9
+.Os
+.Sh NAME
+.Nm cpumem_get ,
+.Nm cpumem_put ,
+.Nm cpumem_malloc ,
+.Nm cpumem_free ,
+.Nm cpumem_enter ,
+.Nm cpumem_leave ,
+.Nm cpumem_first ,
+.Nm cpumem_next
+.Nd Per CPU memory allocations
+.Sh SYNOPSIS
+.In sys/percpu.h
+.Ft struct cpumem *
+.Fn cpumem_get "struct pool *pp"
+.Ft void
+.Fn cpumem_put "struct pool *pp" "struct cpumem *cm"
+.Ft struct cpumem *
+.Fn cpumem_malloc "size_t sz" "int type"
+.Ft void
+.Fn cpumem_free "struct cpumem *cm" "int type" "size_t sz"
+.Ft void *
+.Fn cpumem_enter "struct cpumem *cm"
+.Ft void
+.Fn cpumem_leave "struct cpumem *cm" "void *m"
+.Ft void *
+.Fn cpumem_first "struct cpumem_iter *ci" "struct cpumem *cm"
+.Ft void *
+.Fn cpumem_next "struct cpumem_iter *ci" "struct cpumem *cm"
+.Fn CPUMEM_FOREACH "VARNAME" "struct cpumem_iter *ci" "struct cpumem *cm"
+.Sh DESCRIPTION
+The per CPU memory API provides wrappers around the allocation of
+and access to per CPU memory.
+.Pp
+An alternate implemention of the API is provided on uni-processor
+(ie, when the kernel is not built with
+.Dv MULTIPROCESSOR
+defined)
+systems that provides no overhead compared to direct access to a
+data structure.
+This allows the API to be used without affecting the performance
+uni-processor systems.
+.Ss Per CPU Memory Allocation and Deallocation
+.Pp
+.Fn cpumem_get
+allocates memory for each CPU from the
+.Fa pp
+pool.
+The memory will be zeroed on allocation by passing
+.Dv PR_ZERO
+to
+.Xr pool_get 9
+internally.
+.Pp
+.Fn cpumem_put
+returns each CPUs memory allocation referenced by
+.Fa cm
+to the
+.Fa pp
+pool.
+.Pp
+.Fn cpumem_malloc
+allocates
+.Fa sz
+bytes of
+.Fa type
+memory for each CPU using
+.Xr malloc 9 .
+The memory will be zeroed on allocation by passing
+.Fn M_ZERO
+to
+.Xr malloc 9.
+.Pp
+.Fn cpumem_free
+returns each CPUs memory allocation referenced by
+.Fa cm
+to the system using
+.Xr free 9 .
+The same object size and type originally provided to
+.Fn cpumem_malloc
+must be specified by
+.Fa sz
+and
+.Fa type
+respectively.
+.Ss Per CPU Memory Access
+.Fn cpumem_enter
+provides access to the current CPUs memory allocation referenced by
+.Fa cm .
+.Pp
+.Fn cpumem_leave
+indicates the end of access to the current CPUs memory allocation referenced by
+.Fa cm .
+.Pp
+.Ss Per CPU Memory Iterators
+.Fn cpumem_first
+provides access to the first CPUs memory allocation referenced by
+.Fa cm .
+The iterator
+.Fa ci
+may be used in subsequent calls to
+.Fn cpumem_next .
+.Pp
+.Fn cpumem_next
+provides access to the next CPUs memory allocation referenced by
+.Fa cm
+and
+.Fa ci .
+.Pp
+The
+.Fn CPUMEM_FOREACH
+macro iterates over each CPUs memory allocation referenced by
+.Fa cm
+using the iterator
+.Fa ci ,
+setting
+Fa VARNAME
+to each CPUs allocation in turn.
+.Sh CONTEXT
+.Fn cpumem_get ,
+.Fn cpumem_put ,
+.Fn cpumem_malloc ,
+and
+.Fn cpumem_free
+may be called during autoconf, or from process context.
+.Pp
+.Fn cpumem_enter ,
+.Fn cpumem_leave ,
+.Fn cpumem_first ,
+.Fn cpumem_next ,
+and
+.Fn CPUMEM_FOREACH
+may be called during autoconf, from process context, or from interrupt
+context.
+The per CPU memory API does not provide any locking or serialisation
+of access to each CPUs memory allocation.
+It is up to the caller to provide appropriate locking or serialisation
+around calls to these functions to prevent concurrent access to the
+relevant data structures.
+.Sh RETURN VALUES
+.Fn cpumem_get
+and
+.Fn cpumem_malloc
+will return an opaque cpumem pointer that references each CPUs
+memory allocation.
+.Pp
+.Fn cpumem_enter
+returns a reference to the current CPUs memory allocation.
+.Pp
+.Fn cpumem_first
+returns a reference to the first CPUs memory allocation.
+.Pp
+.Fn cpumem_next
+returns a reference to the next CPUs memory allocation according to the
+iterator
+.Fa ci ,
+or
+.Dv NULL
+if the iterator has run out of CPUs.
+.Sh SEE ALSO
+.Xr pool_get 9 ,
+.Xr malloc 9
+.\" .Xr curcpu()
+.\" .Xr counters_get()
+.Sh HISTORY
+The per CPU memory API first appeared in
+.Ox 6.1 .
+.Sh AUTHORS
+The per CPU memory API was written by
+.An David Gwynne Aq Mt dlg@openbsd.org .