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