6/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 August 10, 2004
  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
  54 The
  55 .Fn contigmalloc
  56 function allocates
  57 .Fa size
  58 bytes of contiguous physical memory that is aligned to
  59 .Fa alignment
  60 bytes, and which does not cross a boundary of
  61 .Fa boundary
  62 bytes.
  63 If successful, the allocation will reside between physical addresses
  64 .Fa low
  65 and
  66 .Fa high .
  67 The returned pointer points to a wired kernel virtual
  68 address range of
  69 .Fa size
  70 bytes allocated from the kernel virtual address (KVA) map.
  71 .Pp
  72 The
  73 .Fa flags
  74 parameter modifies
  75 .Fn contigmalloc Ns 's
  76 behaviour as follows:
  77 .Bl -tag -width indent
  78 .It Dv M_ZERO
  79 Causes the allocated physical memory to be zero filled.
  80 .El
  81 Other flags (if present) are ignored.
  82 .Pp
  83 The
  84 .Fn contigfree
  85 function deallocates memory allocated by a previous call to
  86 .Fn contigmalloc .
  87 .Sh IMPLEMENTATION NOTES
  88 The
  89 .Fn contigmalloc
  90 function does not sleep waiting for memory resources to be freed up,
  91 but instead scans available physical memory a small number of times
  92 for a suitably sized free address range before giving up.
  93 Memory allocation is done on a first-fit basis, starting from the
  94 top of the provided address range.
  95 .Sh RETURN VALUES
  96 The
  97 .Fn contigmalloc
  98 function returns a kernel virtual address if allocation succeeds,
  99 or
 100 .Dv NULL
 101 otherwise.
 102 .Sh EXAMPLES
 103 .Bd -literal
 104 void *p;
 105 p = contigmalloc(8192, M_DEVBUF, M_ZERO, 0, (1L << 22),
 106     32 * 1024, 1024 * 1024);
 107 .Ed
 108 .Pp
 109 Ask for 8192 bytes of zero-filled memory residing between physical
 110 address 0 and 4194303 inclusive, aligned to a 32K boundary and not
 111 crossing a 1M address boundary.
 112 .Sh DIAGNOSTICS
 113 The
 114 .Fn contigmalloc
 115 function will panic if
 116 .Fa size
 117 is zero, or if
 118 .Fa alignment
 119 or
 120 .Fa boundary
 121 is not a power of two.
 122 .Sh SEE ALSO
 123 .Xr malloc 9 ,
 124 .Xr memguard 9