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 July 19, 2007 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 "unsigned long 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.Sh RETURN VALUES 104The 105.Fn contigmalloc 106function returns a kernel virtual address if allocation succeeds, 107or 108.Dv NULL 109otherwise. 110.Sh EXAMPLES 111.Bd -literal 112void *p; 113p = contigmalloc(8192, M_DEVBUF, M_ZERO, 0, (1L << 22), 114 32 * 1024, 1024 * 1024); 115.Ed 116.Pp 117Ask for 8192 bytes of zero-filled memory residing between physical 118address 0 and 4194303 inclusive, aligned to a 32K boundary and not 119crossing a 1M address boundary. 120.Sh DIAGNOSTICS 121The 122.Fn contigmalloc 123function will panic if 124.Fa size 125is zero, or if 126.Fa alignment 127or 128.Fa boundary 129is not a power of two. 130.Sh SEE ALSO 131.Xr malloc 9 , 132.Xr memguard 9 133