1.\" $NetBSD: percpu.9,v 1.9 2010/12/02 12:54:13 wiz Exp $ 2.\" 3.\" Copyright (c) 2010 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by David Young. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd January 23, 2010 31.Dt PERCPU 9 32.Os 33.Sh NAME 34.Nm percpu , 35.Nm percpu_alloc , 36.Nm percpu_free , 37.Nm percpu_getref , 38.Nm percpu_putref , 39.Nm percpu_foreach 40.Nd per-CPU storage allocator 41.Sh SYNOPSIS 42.In sys/percpu.h 43.Vt typedef void (*percpu_callback_t)(void *, void *, struct cpu_info *); 44.Ft percpu_t * 45.Fn percpu_alloc "size_t size" 46.Ft void 47.Fn percpu_free "percpu_t *pc" "size_t size" 48.Ft void * 49.Fn percpu_getref "percpu_t *pc" 50.Ft void 51.Fn percpu_putref "percpu_t *pc" 52.Ft void 53.Fn percpu_foreach "percpu_t *pc" "percpu_callback_t cb" "void *arg" 54.Sh DESCRIPTION 55The machine-independent 56.Nm 57interface provides per-CPU, CPU-local memory reservations to kernel 58subsystems. 59.Fo percpu_alloc 60.Fa size 61.Fc 62reserves on each CPU an independent memory region of 63.Fa size 64bytes that is local to that CPU, returning a handle 65.Po 66.Vt percpu_t 67.Pc 68to those regions. 69A thread may subsequently ask for a pointer, 70.Fa p , 71to the region held by the 72.Vt percpu_t 73on the thread's current CPU. 74Until the thread relinquishes the pointer, or voluntarily sleeps, 75the thread may read or write the region at 76.Fa p 77without causing interprocessor memory synchronization. 78.Sh FUNCTIONS 79.Bl -tag -width compact 80.It Fn percpu_alloc "size" 81Call this in thread context to allocate 82.Fa size 83bytes of local storage on each CPU. 84The storage is initialized with zeroes. 85Treat this as an expensive operation. 86.Fn percpu_alloc 87returns 88.Dv NULL 89on failure, and a handle for the per-CPU storage on success. 90.It Fn percpu_free "pc" "size" 91Call this in thread context to 92return to the system the per-CPU storage held by 93.Fa pc . 94.Fa size 95should match the 96.Fa size 97passed to 98.Fn percpu_alloc . 99When 100.Fn percpu_free 101returns, 102.Fa pc 103is undefined. 104Treat this as an expensive operation. 105.It Fn percpu_getref "pc" 106Disable preemption and return a pointer to the storage held by 107.Fa pc 108on the local CPU. 109Use 110.Fn percpu_getref 111in either thread or interrupt context. 112Follow each 113.Fn percpu_getref 114call with a matching call to 115.Fn percpu_putref . 116.It Fn percpu_putref "pc" 117Indicate that the thread is finished 118with the pointer returned by the matching 119call to 120.Fn percpu_getref . 121Re-enables preemption. 122.It Fn percpu_foreach "pc" "cb" "arg" 123On each CPU, for 124.Fa ci 125the corresponding 126.Vt "struct cpu_info *" 127and 128.Fa "p" 129the CPU-local storage held by 130.Fa pc , 131run 132.Fo "(*cb)" 133.Fa "p" 134.Fa "arg" 135.Fa "ci" 136.Fc . 137Call this in thread context. 138.Fa cb 139should be non-blocking and fast. 140Do not rely on 141.Fa cb 142to be run on the CPUs in any particular order. 143.El 144.Sh CODE REFERENCES 145The 146.Nm 147interface is implemented within the file 148.Pa sys/kern/subr_percpu.c . 149.\" .Sh EXAMPLES 150.Sh SEE ALSO 151.Xr atomic_ops 3 , 152.Xr kmem 9 , 153.Xr pcq 9 , 154.Xr pool_cache 9 , 155.Xr xcall 9 156.Sh HISTORY 157The 158.Nm 159interface first appeared in 160.Nx 6.0 . 161.Sh AUTHORS 162.An YAMAMOTO Takashi Aq yamt@NetBSD.org 163.\" .Sh CAVEATS 164.\" .Sh BUGS 165.\" .Sh SECURITY CONSIDERATIONS 166