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 (un\-named) 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
  99 .Ql 0
 100 the allocated segment will be aligned as the arena's quantum.
 101 .It Fa phase
 102 The allocated segment must be
 103 .Fa phase
 104 bytes from the alignment boundary.
 105 .It Fa nocross
 106 The allocated segment may not straddle a
 107 .Fa nocross
 108 alignment boundary.
 109 .It Fa minaddr
 110 The minimum address at which the segment may be allocated.
 111 .It Fa maxaddr
 112 The maximum address which may be included in the segment.
 113 .It Fa vaddr
 114 The address of the segment which
 115 .Fn vmem_free
 116 or
 117 .Fn vmem_xfree
 118 should free.
 119 .El
 120 .Sh DESCRIPTION
 121 The
 122 .Fn vmem_alloc
 123 and
 124 .Fn vmem_xalloc
 125 functions allocate a segment of
 126 .Fa size
 127 length from the vmem arena
 128 .Fa vmp .
 129 .Pp
 130 The
 131 .Fa vmflag
 132 argument controls the behaviour of the allocation.  As described in
 133 .Sx PARAMETERS
 134 .Pp
 135 For allocations with complex requirements, such as those used for DMA
 136 .Fn vmem_xalloc
 137 takes additional arguments allowing those requirements to be expressed.
 138 .Pp
 139 Segments allocated with
 140 .Fn vmem_xalloc
 141 must always be freed with
 142 .Fn vmem_xfree ,
 143 since these allocations are uncached.
 144 .Sh CONTEXT
 145 This function can be called from either user or kernel context.
 146 If the
 147 .Dv VM_NOSLEEP
 148 flag is specified, it may also be called from interrupt context.
 149 .Sh RETURN VALUES
 150 Upon successful completion the
 151 .Fn vmem_alloc
 152 and
 153 .Fn vmem_xalloc
 154 functions return a pointer to the beginning of the allocated segment.  In the
 155 case of a
 156 .Dv VMC_IDENTIFIER
 157 arena, the address of this pointer is the meaningful component, not the value
 158 to which it points.
 159 .Pp
 160 On failure,
 161 .Dv NULL
 162 is returned.
 163 When the
 164 .Dv VM_SLEEP
 165 flag is specified, these functions can never fail (but may block forever).
 166 .Sh SEE ALSO
 167 .Xr vmem 9 ,
 168 .Xr vmem_create 9F