Print this page
code review from Josh and Robert


  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


  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