usr/src/man/man9f/vmem_alloc.9f

   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.
  69 A
  70 .Dv VM_SLEEP
  71 allocation can never fail but may block indefinitely.
  72 .Pp
  73 The allocation policy may be specified by one of the following flags:
  74 .Bl -tag -width Ds
  75 .It Dv VM_BESTFIT
  76 Take the segment from the smallest free segment that could satisfy this
  77 allocation.
  78 .It Dv VM_FIRSTFIT
  79 Take the segment from the first free segment found that could satisfy this
  80 allocation.
  81 .It Dv VM_NEXTFIT
  82 Take the segment from the segment after the one previously allocated.
  83 This
  84 provides sequential behaviour useful when allocating identifiers from a
  85 .Dv VMC_IDENTIFIER
  86 arena.
  87 .It Dv VM_ENDALLOC
  88 May be specified in combination with
  89 .Dv VM_BESTFIT ,
  90 .Dv VM_FIRSTFIT
  91 or the default policy to indicate that the higher addresses should be
  92 preferred.
  93 .El
  94 .Pp
  95 The default (unnamed) allocation policy is
  96 .Dq "instant fit" ,
  97 an approximation of
  98 .Dv VM_BESTFIT
  99 in guaranteed constant time.
 100 .It Fa align_arg
 101 The minimum alignment of the allocation.
 102 If 0, the allocated segment will be aligned as the arena's quantum.
 103 .It Fa phase
 104 The allocated segment must be
 105 .Fa phase
 106 bytes from the alignment boundary.
 107 .It Fa nocross
 108 The allocated segment may not straddle a
 109 .Fa nocross
 110 alignment boundary.
 111 .It Fa minaddr
 112 The minimum address at which the segment may be allocated.
 113 .It Fa maxaddr
 114 The maximum address which may be included in the segment.
 115 .It Fa vaddr
 116 The address of the segment which
 117 .Fn vmem_free
 118 or
 119 .Fn vmem_xfree
 120 should free.
 121 .El
 122 .Sh DESCRIPTION
 123 The
 124 .Fn vmem_alloc
 125 and
 126 .Fn vmem_xalloc
 127 functions allocate a segment of
 128 .Fa size
 129 length from the vmem arena
 130 .Fa vmp .
 131 .Pp
 132 The
 133 .Fa vmflag
 134 argument controls the behaviour of the allocation, as described in
 135 .Sx PARAMETERS .
 136 .Pp
 137 For allocations with complex requirements, such as those used for DMA
 138 .Fn vmem_xalloc
 139 takes additional arguments allowing those requirements to be expressed.
 140 .Pp
 141 Segments allocated with
 142 .Fn vmem_xalloc
 143 must always be freed with
 144 .Fn vmem_xfree ,
 145 since these allocations are uncached.
 146 .Sh CONTEXT
 147 This function can be called from either user or kernel context.
 148 If the
 149 .Dv VM_NOSLEEP
 150 flag is specified, it may also be called from interrupt context.
 151 .Sh RETURN VALUES
 152 Upon successful completion the
 153 .Fn vmem_alloc
 154 and
 155 .Fn vmem_xalloc
 156 functions return a pointer to the beginning of the allocated segment.
 157 In the case of a
 158 .Dv VMC_IDENTIFIER
 159 arena, the address of this pointer is the meaningful component, not the value
 160 to which it points.
 161 .Pp
 162 On failure,
 163 .Dv NULL
 164 is returned.
 165 When the
 166 .Dv VM_SLEEP
 167 flag is specified, these functions can never fail (but may block forever).
 168 .Sh SEE ALSO
 169 .Xr vmem 9 ,
 170 .Xr vmem_contains 9F ,
 171 .Xr vmem_create 9F