.\" $OpenBSD: cpumem_get.9,v 1.1 2016/10/21 07:57:29 dlg Exp $ .\" .\" * Copyright 2002 Niels Provos .\" * 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 .\" .\" 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 .