1.\" $NetBSD: percpu.9,v 1.12 2017/05/31 23:54:17 chs 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 May 31, 2017 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 a handle for the per-CPU storage. 88.It Fn percpu_free "pc" "size" 89Call this in thread context to 90return to the system the per-CPU storage held by 91.Fa pc . 92.Fa size 93should match the 94.Fa size 95passed to 96.Fn percpu_alloc . 97When 98.Fn percpu_free 99returns, 100.Fa pc 101is undefined. 102Treat this as an expensive operation. 103.It Fn percpu_getref "pc" 104Disable preemption and return a pointer to the storage held by 105.Fa pc 106on the local CPU. 107Use 108.Fn percpu_getref 109in either thread or interrupt context. 110Follow each 111.Fn percpu_getref 112call with a matching call to 113.Fn percpu_putref . 114.It Fn percpu_putref "pc" 115Indicate that the thread is finished 116with the pointer returned by the matching 117call to 118.Fn percpu_getref . 119Re-enables preemption. 120.It Fn percpu_foreach "pc" "cb" "arg" 121On each CPU, for 122.Fa ci 123the corresponding 124.Vt "struct cpu_info *" 125and 126.Fa "p" 127the CPU-local storage held by 128.Fa pc , 129run 130.Fo "(*cb)" 131.Fa "p" 132.Fa "arg" 133.Fa "ci" 134.Fc . 135Call this in thread context. 136.Fa cb 137should be non-blocking and fast. 138Do not rely on 139.Fa cb 140to be run on the CPUs in any particular order. 141.El 142.Sh CODE REFERENCES 143The 144.Nm 145interface is implemented within the file 146.Pa sys/kern/subr_percpu.c . 147.\" .Sh EXAMPLES 148.Sh SEE ALSO 149.Xr atomic_ops 3 , 150.Xr kmem 9 , 151.Xr pcq 9 , 152.Xr pool_cache 9 , 153.Xr xcall 9 154.Sh HISTORY 155The 156.Nm 157interface first appeared in 158.Nx 6.0 . 159.Sh AUTHORS 160.An YAMAMOTO Takashi Aq Mt yamt@NetBSD.org 161.\" .Sh CAVEATS 162.\" .Sh BUGS 163.\" .Sh SECURITY CONSIDERATIONS 164