1 .\"
   2 .\" This file and its contents are supplied under the terms of the
   3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   4 .\" You may only use this file in accordance with the terms of version
   5 .\" 1.0 of the CDDL.
   6 .\"
   7 .\" A full copy of the text of the CDDL should have accompanied this
   8 .\" source.  A copy of the CDDL is also available via the Internet at
   9 .\" http://www.illumos.org/license/CDDL.
  10 .\"
  11 .\"
  12 .\" Copyright 2017, Richard Lowe.
  13 .\"
  14 .Dd Jan 18, 2017
  15 .Dt VMEM_ALLOC 9F
  16 .Os
  17 .Sh NAME
  18 .Nm vmem_alloc ,
  19 .Nm vmem_xalloc ,
  20 .Nm vmem_free ,
  21 .Nm vmem_xfree
  22 .Nd allocate and free segments from a vmem arena
  23 .Sh SYNOPSIS
  24 .In sys/vmem.h
  25 .Ft void *
  26 .Fo vmem_alloc
  27 .Fa "vmem_t *vmp"
  28 .Fa "size_t size"
  29 .Fa "int vmflag"
  30 .Fc
  31 .Ft void *
  32 .Fo vmem_xalloc
  33 .Fa "vmem_t *vmp"
  34 .Fa "size_t size"
  35 .Fa "size_t align_arg"
  36 .Fa "size_t phase"
  37 .Fa "size_t nocross"
  38 .Fa "void *minaddr"
  39 .Fa "void *maxaddr"
  40 .Fa "int vmflag"
  41 .Fc
  42 .Ft void
  43 .Fo vmem_free
  44 .Fa "vmem_t *vmp"
  45 .Fa "void *vaddr"
  46 .Fa "size_t size"
  47 .Fc
  48 .Ft void
  49 .Fo vmem_xfree
  50 .Fa "vmem_t *vmp"
  51 .Fa "void *vaddr"
  52 .Fa "size_t size"
  53 .Fc
  54 .Sh INTERFACE LEVEL
  55 illumos DDI specific
  56 .Sh PARAMETERS
  57 .Bl -tag -width Ds
  58 .It Fa vmp
  59 The vmem arena from which to allocate or free.
  60 .It Fa size
  61 The size of the segment to allocate or free.
  62 .It Fa vmflag
  63 A bitmask of flags controlling the behaviour of the allocation.
  64 There are two meaningful groups of flags.
  65 .Dv VM_SLEEP
  66 or
  67 .Dv VM_NOSLEEP
  68 must be specified, and indicate whether the allocation may block.  A
  69 .Dv VM_SLEEP
  70 allocation can never fail but may block indefinitely.
  71 .Pp
  72 The allocation policy may be specified by one of the following flags:
  73 .Bl -tag -width Ds
  74 .It Dv VM_BESTFIT
  75 Take the segment from the smallest free segment that could satisfy this allocation.
  76 .It Dv VM_FIRSTFIT
  77 Take the segment from the first free segment found that could satisfy this
  78 allocation.
  79 .It Dv VM_NEXTFIT
  80 Take the segment from the segment after the one previously allocated.  This
  81 provides sequential behaviour useful when allocating identifiers from a
  82 .Dv VMC_IDENTIFIER
  83 arena.
  84 .It Dv VM_ENDALLOC
  85 May be specified in combination with
  86 .Dv VM_BESTFIT ,
  87 .Dv VM_FIRSTFIT
  88 or the default policy to indicate that the higher addresses should be
  89 preferred.
  90 .El
  91 .Pp
  92 The default (unnamed) allocation policy is
  93 .Dq "instant fit" ,
  94 an approximation of
  95 .Dv VM_BESTFIT
  96 in guaranteed constant time.
  97 .It Fa align_arg
  98 The minimum alignment of the allocation.  If 0,
  99 the allocated segment will be aligned as the arena's quantum.
 100 .It Fa phase
 101 The allocated segment must be
 102 .Fa phase
 103 bytes from the alignment boundary.
 104 .It Fa nocross
 105 The allocated segment may not straddle a
 106 .Fa nocross
 107 alignment boundary.
 108 .It Fa minaddr
 109 The minimum address at which the segment may be allocated.
 110 .It Fa maxaddr
 111 The maximum address which may be included in the segment.
 112 .It Fa vaddr
 113 The address of the segment which
 114 .Fn vmem_free
 115 or
 116 .Fn vmem_xfree
 117 should free.
 118 .El
 119 .Sh DESCRIPTION
 120 The
 121 .Fn vmem_alloc
 122 and
 123 .Fn vmem_xalloc
 124 functions allocate a segment of
 125 .Fa size
 126 length from the vmem arena
 127 .Fa vmp .
 128 .Pp
 129 The
 130 .Fa vmflag
 131 argument controls the behaviour of the allocation, as described in
 132 .Sx PARAMETERS .
 133 .Pp
 134 For allocations with complex requirements, such as those used for DMA
 135 .Fn vmem_xalloc
 136 takes additional arguments allowing those requirements to be expressed.
 137 .Pp
 138 Segments allocated with
 139 .Fn vmem_xalloc
 140 must always be freed with
 141 .Fn vmem_xfree ,
 142 since these allocations are uncached.
 143 .Sh CONTEXT
 144 This function can be called from either user or kernel context.
 145 If the
 146 .Dv VM_NOSLEEP
 147 flag is specified, it may also be called from interrupt context.
 148 .Sh RETURN VALUES
 149 Upon successful completion the
 150 .Fn vmem_alloc
 151 and
 152 .Fn vmem_xalloc
 153 functions return a pointer to the beginning of the allocated segment.  In the
 154 case of a
 155 .Dv VMC_IDENTIFIER
 156 arena, the address of this pointer is the meaningful component, not the value
 157 to which it points.
 158 .Pp
 159 On failure,
 160 .Dv NULL
 161 is returned.
 162 When the
 163 .Dv VM_SLEEP
 164 flag is specified, these functions can never fail (but may block forever).
 165 .Sh SEE ALSO
 166 .Xr vmem 9 ,
 167 .Xr vmem_contains 9F ,
 168 .Xr vmem_create 9F