1.\" 2.\" Copyright (c) 2004 Joseph Koshy 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' 15.\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 16.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 17.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE 18.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 19.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 20.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 21.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 22.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 23.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 24.\" POSSIBILITY OF SUCH DAMAGE. 25.\" 26.Dd October 30, 2018 27.Dt CONTIGMALLOC 9 28.Os 29.Sh NAME 30.Nm contigmalloc , contigfree 31.Nd manage contiguous kernel physical memory 32.Sh SYNOPSIS 33.In sys/types.h 34.In sys/malloc.h 35.Ft "void *" 36.Fo contigmalloc 37.Fa "unsigned long size" 38.Fa "struct malloc_type *type" 39.Fa "int flags" 40.Fa "vm_paddr_t low" 41.Fa "vm_paddr_t high" 42.Fa "unsigned long alignment" 43.Fa "vm_paddr_t boundary" 44.Fc 45.Ft void 46.Fo contigfree 47.Fa "void *addr" 48.Fa "unsigned long size" 49.Fa "struct malloc_type *type" 50.Fc 51.In sys/param.h 52.In sys/domainset.h 53.Ft "void *" 54.Fo contigmalloc_domainset 55.Fa "unsigned long size" 56.Fa "struct malloc_type *type" 57.Fa "struct domainset *ds" 58.Fa "int flags" 59.Fa "vm_paddr_t low" 60.Fa "vm_paddr_t high" 61.Fa "unsigned long alignment" 62.Fa "vm_paddr_t boundary" 63.Fc 64.Sh DESCRIPTION 65The 66.Fn contigmalloc 67function allocates 68.Fa size 69bytes of contiguous physical memory that is aligned to 70.Fa alignment 71bytes, and which does not cross a boundary of 72.Fa boundary 73bytes. 74If successful, the allocation will reside between physical addresses 75.Fa low 76and 77.Fa high . 78The returned pointer points to a wired kernel virtual 79address range of 80.Fa size 81bytes allocated from the kernel virtual address (KVA) map. 82.Pp 83The 84.Fn contigmalloc_domainset 85variant allows the caller to additionally specify a 86.Xr numa 4 87domain selection policy. 88See 89.Xr domainset 9 90for some example policies. 91.Pp 92The 93.Fa flags 94parameter modifies 95.Fn contigmalloc Ns 's 96behaviour as follows: 97.Bl -tag -width indent 98.It Dv M_ZERO 99Causes the allocated physical memory to be zero filled. 100.It Dv M_NOWAIT 101Causes 102.Fn contigmalloc 103to return 104.Dv NULL 105if the request cannot be immediately fulfilled due to resource shortage. 106.El 107.Pp 108Other flags (if present) are ignored. 109.Pp 110The 111.Fn contigfree 112function deallocates memory allocated by a previous call to 113.Fn contigmalloc 114or 115.Fn contigmalloc_domainset . 116.Sh IMPLEMENTATION NOTES 117The 118.Fn contigmalloc 119function does not sleep waiting for memory resources to be freed up, 120but instead actively reclaims pages before giving up. 121However, unless 122.Dv M_NOWAIT 123is specified, it may select a page for reclamation that must first be 124written to backing storage, causing it to sleep. 125.Pp 126The 127.Fn contigfree 128function does not accept 129.Dv NULL 130as an address input, unlike 131.Xr free 9 . 132.Sh RETURN VALUES 133The 134.Fn contigmalloc 135function returns a kernel virtual address if allocation succeeds, 136or 137.Dv NULL 138otherwise. 139.Sh EXAMPLES 140.Bd -literal 141void *p; 142p = contigmalloc(8192, M_DEVBUF, M_ZERO, 0, (1L << 22), 143 32 * 1024, 1024 * 1024); 144.Ed 145.Pp 146Ask for 8192 bytes of zero-filled memory residing between physical 147address 0 and 4194303 inclusive, aligned to a 32K boundary and not 148crossing a 1M address boundary. 149.Sh DIAGNOSTICS 150The 151.Fn contigmalloc 152function will panic if 153.Fa size 154is zero, or if 155.Fa alignment 156or 157.Fa boundary 158is not a power of two. 159.Sh SEE ALSO 160.Xr malloc 9 , 161.Xr memguard 9 162