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.\" $FreeBSD$ 27.\" 28.Dd October 30, 2018 29.Dt CONTIGMALLOC 9 30.Os 31.Sh NAME 32.Nm contigmalloc , contigfree 33.Nd manage contiguous kernel physical memory 34.Sh SYNOPSIS 35.In sys/types.h 36.In sys/malloc.h 37.Ft "void *" 38.Fo contigmalloc 39.Fa "unsigned long size" 40.Fa "struct malloc_type *type" 41.Fa "int flags" 42.Fa "vm_paddr_t low" 43.Fa "vm_paddr_t high" 44.Fa "unsigned long alignment" 45.Fa "vm_paddr_t boundary" 46.Fc 47.Ft void 48.Fo contigfree 49.Fa "void *addr" 50.Fa "unsigned long size" 51.Fa "struct malloc_type *type" 52.Fc 53.In sys/param.h 54.In sys/domainset.h 55.Ft "void *" 56.Fo contigmalloc_domainset 57.Fa "unsigned long size" 58.Fa "struct malloc_type *type" 59.Fa "struct domainset *ds" 60.Fa "int flags" 61.Fa "vm_paddr_t low" 62.Fa "vm_paddr_t high" 63.Fa "unsigned long alignment" 64.Fa "vm_paddr_t boundary" 65.Fc 66.Sh DESCRIPTION 67The 68.Fn contigmalloc 69function allocates 70.Fa size 71bytes of contiguous physical memory that is aligned to 72.Fa alignment 73bytes, and which does not cross a boundary of 74.Fa boundary 75bytes. 76If successful, the allocation will reside between physical addresses 77.Fa low 78and 79.Fa high . 80The returned pointer points to a wired kernel virtual 81address range of 82.Fa size 83bytes allocated from the kernel virtual address (KVA) map. 84.Pp 85The 86.Fn contigmalloc_domainset 87variant allows the caller to additionally specify a 88.Xr numa 4 89domain selection policy. 90See 91.Xr domainset 9 92for some example policies. 93.Pp 94The 95.Fa flags 96parameter modifies 97.Fn contigmalloc Ns 's 98behaviour as follows: 99.Bl -tag -width indent 100.It Dv M_ZERO 101Causes the allocated physical memory to be zero filled. 102.It Dv M_NOWAIT 103Causes 104.Fn contigmalloc 105to return 106.Dv NULL 107if the request cannot be immediately fulfilled due to resource shortage. 108.El 109.Pp 110Other flags (if present) are ignored. 111.Pp 112The 113.Fn contigfree 114function deallocates memory allocated by a previous call to 115.Fn contigmalloc 116or 117.Fn contigmalloc_domainset . 118.Sh IMPLEMENTATION NOTES 119The 120.Fn contigmalloc 121function does not sleep waiting for memory resources to be freed up, 122but instead actively reclaims pages before giving up. 123However, unless 124.Dv M_NOWAIT 125is specified, it may select a page for reclamation that must first be 126written to backing storage, causing it to sleep. 127.Pp 128The 129.Fn contigfree 130function does not accept 131.Dv NULL 132as an address input, unlike 133.Xr free 9 . 134.Sh RETURN VALUES 135The 136.Fn contigmalloc 137function returns a kernel virtual address if allocation succeeds, 138or 139.Dv NULL 140otherwise. 141.Sh EXAMPLES 142.Bd -literal 143void *p; 144p = contigmalloc(8192, M_DEVBUF, M_ZERO, 0, (1L << 22), 145 32 * 1024, 1024 * 1024); 146.Ed 147.Pp 148Ask for 8192 bytes of zero-filled memory residing between physical 149address 0 and 4194303 inclusive, aligned to a 32K boundary and not 150crossing a 1M address boundary. 151.Sh DIAGNOSTICS 152The 153.Fn contigmalloc 154function will panic if 155.Fa size 156is zero, or if 157.Fa alignment 158or 159.Fa boundary 160is not a power of two. 161.Sh SEE ALSO 162.Xr malloc 9 , 163.Xr memguard 9 164