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 January 29, 2015 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.Sh DESCRIPTION 54The 55.Fn contigmalloc 56function allocates 57.Fa size 58bytes of contiguous physical memory that is aligned to 59.Fa alignment 60bytes, and which does not cross a boundary of 61.Fa boundary 62bytes. 63If successful, the allocation will reside between physical addresses 64.Fa low 65and 66.Fa high . 67The returned pointer points to a wired kernel virtual 68address range of 69.Fa size 70bytes allocated from the kernel virtual address (KVA) map. 71.Pp 72The 73.Fa flags 74parameter modifies 75.Fn contigmalloc Ns 's 76behaviour as follows: 77.Bl -tag -width indent 78.It Dv M_ZERO 79Causes the allocated physical memory to be zero filled. 80.It Dv M_NOWAIT 81Causes 82.Fn contigmalloc 83to return 84.Dv NULL 85if the request cannot be immediately fulfilled due to resource shortage. 86.El 87.Pp 88Other flags (if present) are ignored. 89.Pp 90The 91.Fn contigfree 92function deallocates memory allocated by a previous call to 93.Fn contigmalloc . 94.Sh IMPLEMENTATION NOTES 95The 96.Fn contigmalloc 97function does not sleep waiting for memory resources to be freed up, 98but instead actively reclaims pages before giving up. 99However, unless 100.Dv M_NOWAIT 101is specified, it may select a page for reclamation that must first be 102written to backing storage, causing it to sleep. 103.Pp 104The 105.Fn contigfree 106function does not accept 107.Dv NULL 108as an address input, unlike 109.Xr free 9 . 110.Sh RETURN VALUES 111The 112.Fn contigmalloc 113function returns a kernel virtual address if allocation succeeds, 114or 115.Dv NULL 116otherwise. 117.Sh EXAMPLES 118.Bd -literal 119void *p; 120p = contigmalloc(8192, M_DEVBUF, M_ZERO, 0, (1L << 22), 121 32 * 1024, 1024 * 1024); 122.Ed 123.Pp 124Ask for 8192 bytes of zero-filled memory residing between physical 125address 0 and 4194303 inclusive, aligned to a 32K boundary and not 126crossing a 1M address boundary. 127.Sh DIAGNOSTICS 128The 129.Fn contigmalloc 130function will panic if 131.Fa size 132is zero, or if 133.Fa alignment 134or 135.Fa boundary 136is not a power of two. 137.Sh SEE ALSO 138.Xr malloc 9 , 139.Xr memguard 9 140