1.\" $OpenBSD: cpumem_get.9,v 1.5 2016/10/21 15:00:30 bluhm Exp $ 2.\" 3.\" Copyright (c) 2016 David Gwynne <dlg@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: October 21 2016 $ 18.Dt CPUMEM_GET 9 19.Os 20.Sh NAME 21.Nm cpumem_get , 22.Nm cpumem_put , 23.Nm cpumem_malloc , 24.Nm cpumem_free , 25.Nm cpumem_enter , 26.Nm cpumem_leave , 27.Nm cpumem_first , 28.Nm cpumem_next 29.Nd per CPU memory allocations 30.Sh SYNOPSIS 31.In sys/percpu.h 32.Ft struct cpumem * 33.Fn cpumem_get "struct pool *pp" 34.Ft void 35.Fn cpumem_put "struct pool *pp" "struct cpumem *cm" 36.Ft struct cpumem * 37.Fn cpumem_malloc "size_t sz" "int type" 38.Ft void 39.Fn cpumem_free "struct cpumem *cm" "int type" "size_t sz" 40.Ft void * 41.Fn cpumem_enter "struct cpumem *cm" 42.Ft void 43.Fn cpumem_leave "struct cpumem *cm" "void *m" 44.Ft void * 45.Fn cpumem_first "struct cpumem_iter *ci" "struct cpumem *cm" 46.Ft void * 47.Fn cpumem_next "struct cpumem_iter *ci" "struct cpumem *cm" 48.Fn CPUMEM_FOREACH "VARNAME" "struct cpumem_iter *ci" "struct cpumem *cm" 49.Sh DESCRIPTION 50The per CPU memory API provides wrappers around the allocation of 51and access to per CPU memory. 52.Pp 53An alternate implemention of the API is provided on uni-processor 54(i.e. when the kernel is not built with 55.Dv MULTIPROCESSOR 56defined) 57systems that provides no overhead compared to direct access to a 58data structure. 59This allows the API to be used without affecting the performance 60uni-processor systems. 61.Ss Per CPU Memory Allocation and Deallocation 62.Fn cpumem_get 63allocates memory for each CPU from the 64.Fa pp 65pool. 66The memory will be zeroed on allocation by passing 67.Dv PR_ZERO 68to 69.Xr pool_get 9 70internally. 71.Pp 72.Fn cpumem_put 73returns each CPUs memory allocation referenced by 74.Fa cm 75to the 76.Fa pp 77pool. 78.Pp 79.Fn cpumem_malloc 80allocates 81.Fa sz 82bytes of 83.Fa type 84memory for each CPU using 85.Xr malloc 9 . 86The memory will be zeroed on allocation by passing 87.Fn M_ZERO 88to 89.Xr malloc 9 . 90.Pp 91.Fn cpumem_free 92returns each CPU's memory allocation referenced by 93.Fa cm 94to the system using 95.Xr free 9 . 96The same object size and type originally provided to 97.Fn cpumem_malloc 98must be specified by 99.Fa sz 100and 101.Fa type 102respectively. 103.Ss Per CPU Memory Access 104.Fn cpumem_enter 105provides access to the current CPU's memory allocation referenced by 106.Fa cm . 107.Pp 108.Fn cpumem_leave 109indicates the end of access to the current CPU's memory allocation referenced by 110.Fa cm . 111.Ss Per CPU Memory Iterators 112.Fn cpumem_first 113provides access to the first CPU's memory allocation referenced by 114.Fa cm . 115The iterator 116.Fa ci 117may be used in subsequent calls to 118.Fn cpumem_next . 119.Pp 120.Fn cpumem_next 121provides access to the next CPU's memory allocation referenced by 122.Fa cm 123and 124.Fa ci . 125.Pp 126The 127.Fn CPUMEM_FOREACH 128macro iterates over each CPU's memory allocation referenced by 129.Fa cm 130using the iterator 131.Fa ci , 132setting 133.Fa VARNAME 134to each CPU's allocation in turn. 135.Sh CONTEXT 136.Fn cpumem_get , 137.Fn cpumem_put , 138.Fn cpumem_malloc , 139and 140.Fn cpumem_free 141may be called during autoconf, or from process context. 142.Pp 143.Fn cpumem_enter , 144.Fn cpumem_leave , 145.Fn cpumem_first , 146.Fn cpumem_next , 147and 148.Fn CPUMEM_FOREACH 149may be called during autoconf, from process context, or from interrupt 150context. 151The per CPU memory API does not provide any locking or serialisation 152of access to each CPU's memory allocation. 153It is up to the caller to provide appropriate locking or serialisation 154around calls to these functions to prevent concurrent access to the 155relevant data structures. 156.Sh RETURN VALUES 157.Fn cpumem_get 158and 159.Fn cpumem_malloc 160will return an opaque cpumem pointer that references each CPU's 161memory allocation. 162.Pp 163.Fn cpumem_enter 164returns a reference to the current CPU's memory allocation. 165.Pp 166.Fn cpumem_first 167returns a reference to the first CPU's memory allocation. 168.Pp 169.Fn cpumem_next 170returns a reference to the next CPU's memory allocation according to the 171iterator 172.Fa ci , 173or 174.Dv NULL 175if the iterator has run out of CPUs. 176.Sh SEE ALSO 177.Xr counters_alloc 9 , 178.Xr malloc 9 , 179.Xr pool_get 9 180.Sh HISTORY 181The per CPU memory API first appeared in 182.Ox 6.1 . 183.Sh AUTHORS 184The per CPU memory API was written by 185.An David Gwynne Aq Mt dlg@openbsd.org . 186