share/man/man9/contigmalloc.9

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