share/man/man9f/vmem_create.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_CREATE 9F
  16 .Os
  17 .Sh NAME
  18 .Nm vmem_create ,
  19 .Nm vmem_xcreate ,
  20 .Nm vmem_destroy
  21 .Nd create and destroy vmem arenas
  22 .Sh SYNOPSIS
  23 .In sys/vmem.h
  24 .Vt "typedef struct vmem vmem_t;"
  25 .Vt "typedef void *(vmem_alloc_t)(vmem_t *, size_t, int);"
  26 .Vt "typedef void (vmem_free_t)(vmem_t *, void *, size_t);"
  27 .Vt "typedef void *(vmem_ximport_t)(vmem_t *, size_t *, size_t, int);"
  28 .Ft vmem_t *
  29 .Fo vmem_create
  30 .Fa "const char *name"
  31 .Fa "void *base"
  32 .Fa "size_t size"
  33 .Fa "size_t quantum"
  34 .Fa "vmem_alloc_t *afunc"
  35 .Fa "vmem_free_t *ffunc"
  36 .Fa "vmem_t *source"
  37 .Fa "size_t qcache_max"
  38 .Fa "int vmflag"
  39 .Fc
  40 .Ft vmem_t *
  41 .Fo vmem_xcreate
  42 .Fa "const char *name"
  43 .Fa "void *base"
  44 .Fa "size_t size"
  45 .Fa "size_t quantum"
  46 .Fa "vmem_ximport_t *afunc"
  47 .Fa "vmem_free_t *ffunc"
  48 .Fa "vmem_t *source"
  49 .Fa "size_t qcache_max"
  50 .Fa "int vmflag"
  51 .Fc
  52 .Ft void
  53 .Fo vmem_destroy
  54 .Fa "vmem_t *vmp"
  55 .Fc
  56 .Sh INTERFACE LEVEL
  57 illumos DDI specific
  58 .Sh PARAMETERS
  59 .Bl -tag -width Ds
  60 .It Fa name
  61 A character string giving a name to the vmem
  62 arena to be created.
  63 .It Fa base
  64 An address indicating the lowest possible value in the arena.
  65 .It Fa size
  66 The size of the arena to create.
  67 .It Fa quantum
  68 The arena's
  69 .Dq quantum .
  70 The granularity of the arena.
  71 The amount allocated at minimum by each request.
  72 Must be a power of 2.
  73 .It Fa afunc
  74 A function which is called to import new spans from
  75 .Fa source ,
  76 which may be
  77 .Dv NULL
  78 if this arena does not import from another.
  79 When calling
  80 .Fn vmem_create ,
  81 .Fa afunc
  82 is a
  83 .Vt vmem_alloc_t ,
  84 a function taking three parameters and returning a pointer to
  85 .Vt void
  86 (the imported space):
  87 .Bl -tag -width Ds
  88 .It Fa "vmem_t *"
  89 The source arena from which we'll import.
  90 The
  91 .Fa source
  92 argument to
  93 .Fn vmem_create .
  94 .It Fa size_t
  95 The size to import.
  96 .It Fa int
  97 The
  98 .Fa vmflag
  99 argument used for the import.
 100 .El
 101 .Pp
 102 When calling
 103 .Fn vmem_xcreate ,
 104 .Fa afunc
 105 is a
 106 .Vt vmem_ximport_t ,
 107 a function taking four parameters and returning a pointer to
 108 .Vt void
 109 (the imported space):
 110 .Bl -tag -width Ds
 111 .It Fa "vmem_t *"
 112 The source arena from which we'll import.
 113 The
 114 .Fa source
 115 argument to
 116 .Fn vmem_xcreate .
 117 .It Fa "size_t *"
 118 The size of the import.
 119 .Fa afunc
 120 may
 121 .Em increase
 122 this size if that is desirable, but must never decrease it.
 123 .It Fa size_t
 124 The desired alignment of the imported space.
 125 .It Fa int
 126 The
 127 .Fa vmflag
 128 argument used for the import.
 129 .El
 130 .It Fa ffunc
 131 A function which is called to return spans to
 132 .Fa source ,
 133 which may be
 134 .Dv NULL
 135 if this arena does not import from another.
 136 This is a
 137 .Vt vmem_free_t ,
 138 a function taking three parameters and returning void:
 139 .Bl -tag -width Ds
 140 .It Fa "vmem_t"
 141 The arena to which space is being returned.
 142 The
 143 .Fa source
 144 argument to
 145 .Fn vmem_create
 146 or
 147 .Fn vmem_xcreate .
 148 .It Fa "void *"
 149 The span being returned to the source arena.
 150 .It Fa "size_t"
 151 The size of the span being returned to the source arena.
 152 .El
 153 .It Fa source
 154 An arena from which this arena will import,
 155 which may be
 156 .Dv NULL
 157 if this arena does not import from another.
 158 .It Fa qcache_max
 159 Each arena offers caching of integer multiples of
 160 .Fa quantum
 161 up to
 162 .Fa qcache_max ,
 163 which may be 0.
 164 .It Fa vmflag
 165 A bitmask of flags indicating the characteristics of this arena.
 166 .Bl -tag -width Ds
 167 .It Dv VMC_IDENTIFIER
 168 The arena represents arbitrary integer identifiers, rather than virtual
 169 memory.
 170 .El
 171 .It Fa vmp
 172 A pointer to the vmem arena to be destroyed.
 173 .El
 174 .Sh DESCRIPTION
 175 A
 176 .Em vmem arena
 177 is a section of an arbitrary address space (a range of integer addresses).
 178 This commonly represents virtual memory, but can in fact be an arbitrary set
 179 of integers.
 180 The
 181 .Dv VMC_IDENTIFIER
 182 flag set at arena creation time differentiates between these two cases.
 183 .Pp
 184 The
 185 .Fa afunc ,
 186 .Fa ffunc , and
 187 .Fa source
 188 arguments combine to support a hierarchical structure of arenas, each
 189 importing from a single parent (the
 190 .Fa source ) .
 191 The
 192 .Fn vmem_create
 193 and
 194 .Fn vmem_xcreate
 195 functions differ in that the latter provides an interface for
 196 .Fa afunc
 197 to alter the size of the span imported from
 198 .Fa source .
 199 It is only legal to
 200 .Em increase
 201 this size.
 202 .Sh CONTEXT
 203 These functions can be called from user or kernel context.
 204 .Sh RETURN VALUES
 205 Upon successful completion the
 206 .Fn vmem_create
 207 and
 208 .Fn vmem_xcreate
 209 functions return a pointer to a vmem arena.
 210 Otherwise,
 211 .Dv NULL
 212 is returned to indicate the arena could not be created.
 213 .Sh SEE ALSO
 214 .Xr vmem 9 ,
 215 .Xr vmem_add 9F ,
 216 .Xr vmem_alloc 9F