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