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: src/share/man/man9/contigmalloc.9,v 1.5 2005/01/21 08:36:40 ru Exp $
  27 .\" $DragonFly: src/share/man/man9/contigmalloc.9,v 1.1 2008/01/19 08:23:17 swildner Exp $
  28 .\"
  29 .Dd January 19, 2008
  30 .Dt CONTIGMALLOC 9
  31 .Os
  32 .Sh NAME
  33 .Nm contigmalloc ,
  34 .Nm contigfree
  35 .Nd manage contiguous kernel physical memory
  36 .Sh SYNOPSIS
  37 .In sys/types.h
  38 .In sys/malloc.h
  39 .Ft "void *"
  40 .Fo contigmalloc
  41 .Fa "unsigned long size"
  42 .Fa "struct malloc_type *type"
  43 .Fa "int flags"
  44 .Fa "vm_paddr_t low"
  45 .Fa "vm_paddr_t high"
  46 .Fa "unsigned long alignment"
  47 .Fa "unsigned long boundary"
  48 .Fc
  49 .Ft void
  50 .Fo contigfree
  51 .Fa "void *addr"
  52 .Fa "unsigned long size"
  53 .Fa "struct malloc_type *type"
  54 .Fc
  55 .Sh DESCRIPTION
  56 The
  57 .Fn contigmalloc
  58 function allocates
  59 .Fa size
  60 bytes of contiguous physical memory that is aligned to
  61 .Fa alignment
  62 bytes, and which does not cross a boundary of
  63 .Fa boundary
  64 bytes.
  65 If successful, the allocation will reside between physical addresses
  66 .Fa low
  67 and
  68 .Fa high .
  69 The returned pointer points to a wired kernel virtual
  70 address range of
  71 .Fa size
  72 bytes allocated from the kernel virtual address (KVA) map.
  73 The
  74 .Fa type
  75 argument is ignored.
  76 .Pp
  77 The
  78 .Fa flags
  79 parameter modifies
  80 .Fn contigmalloc Ns Ap s
  81 behavior as follows:
  82 .Bl -tag -width ".Dv M_WAITOK" -offset indent
  83 .It Dv M_WAITOK
  84 Causes
  85 .Fn contigmalloc
  86 to try flushing the active page queue in its second pass.
  87 Note that (unlike
  88 .Fn kmalloc M_WAITOK )
  89 .Fn contigmalloc M_WAITOK
  90 can still return NULL.
  91 .It Dv M_ZERO
  92 Causes the allocated physical memory to be zero filled.
  93 .El
  94 .Pp
  95 Other flags (if present) are ignored.
  96 .Pp
  97 The
  98 .Fn contigfree
  99 function deallocates memory allocated by a previous call to
 100 .Fn contigmalloc .
 101 .Sh IMPLEMENTATION NOTES
 102 The
 103 .Fn contigmalloc
 104 function does not sleep waiting for memory resources to be freed up,
 105 but instead scans available physical memory a small number of times
 106 for a suitably sized free address range before giving up.
 107 Memory allocation is done on a first-fit basis, starting from the
 108 top of the provided address range.
 109 .Sh RETURN VALUES
 110 The
 111 .Fn contigmalloc
 112 function returns a kernel virtual address if allocation succeeds,
 113 or
 114 .Dv NULL
 115 otherwise.
 116 .Sh EXAMPLES
 117 .Bd -literal
 118 void *p;
 119 p = contigmalloc(8192, M_DEVBUF, M_ZERO, 0, (1L << 22),
 120     32 * 1024, 1024 * 1024);
 121 .Ed
 122 .Pp
 123 Ask for 8192 bytes of zero-filled memory residing between physical
 124 address 0 and 4194303 inclusive, aligned to a 32K boundary and not
 125 crossing a 1M address boundary.
 126 .Sh DIAGNOSTICS
 127 The
 128 .Fn contigmalloc
 129 function will panic if
 130 .Fa size
 131 is zero, or if
 132 .Fa alignment
 133 or
 134 .Fa boundary
 135 is not a power of two.
 136 .Sh SEE ALSO
 137 .Xr kmalloc 9