share/man/man9f/id_space.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 2016 Joyent, Inc.
  13 .\"
  14 .Dd Aug 02, 2016
  15 .Dt ID_SPACE 9F
  16 .Os
  17 .Sh NAME
  18 .Nm id_space ,
  19 .Nm id_space_create ,
  20 .Nm id_space_destroy ,
  21 .Nm id_space_extend ,
  22 .Nm id_alloc ,
  23 .Nm id_alloc_nosleep ,
  24 .Nm id_allocff ,
  25 .Nm id_allocff_nosleep ,
  26 .Nm id_alloc_specific_nosleep ,
  27 .Nm id_free
  28 .Nd create, destroy, and use identifier spaces
  29 .Sh SYNOPSIS
  30 .In sys/id_space.h
  31 .Ft "id_space_t *"
  32 .Fo id_space_create
  33 .Fa "const char *name"
  34 .Fa "id_t low"
  35 .Fa "id_t high"
  36 .Fc
  37 .Ft void
  38 .Fo id_space_destroy
  39 .Fa "id_space_t *idspace"
  40 .Fc
  41 .Ft void
  42 .Fo id_space_extend
  43 .Fa "id_t low"
  44 .Fa "id_t high"
  45 .Fc
  46 .Ft id_t
  47 .Fo id_alloc
  48 .Fa "id_space_t *idspace"
  49 .Fc
  50 .Ft id_t
  51 .Fo id_alloc_nosleep
  52 .Fa "id_space_t *idspace"
  53 .Fc
  54 .Ft id_t
  55 .Fo id_allocff
  56 .Fa "id_space_t *idspace"
  57 .Fc
  58 .Ft id_t
  59 .Fo id_allocff_nosleep
  60 .Fa "id_space_t *idspace"
  61 .Fc
  62 .Ft id_t
  63 .Fo id_allocff_specific_nosleep
  64 .Fa "id_space_t *idspace"
  65 .Fa "id_t id"
  66 .Fc
  67 .Ft void
  68 .Fo id_free
  69 .Fa "id_space_t *idspace"
  70 .Fa "id_t id"
  71 .Fc
  72 .Sh INTERFACE STABILITY
  73 illumos DDI specific
  74 .Sh PARAMETERS
  75 .Bl -tag -width Fa
  76 .It Fa idspace
  77 A pointer to an
  78 .Sy id_space_t
  79 structure allocated with the
  80 .Fn id_space_create
  81 function.
  82 .It Fa id
  83 An identifier, a signed 32-bit integer.
  84 .It Fa name
  85 An ASCII character string to call the identifier space.
  86 .It Fa low
  87 The lower end of an identifier space.
  88 This value is included in the range.
  89 .It Fa high
  90 The upper end of an identifier space.
  91 This value is excluded from the range.
  92 .El
  93 .Sh DESCRIPTION
  94 The
  95 .Sy id_space
  96 suite of functions is used to create and manage identifier spaces.
  97 An identifier space allows the system to manage a range of identifiers.
  98 It tracks what values have been used and which values have not been used
  99 and has different ways of allocating values from the identifier space.
 100 .Pp
 101 Identifier spaces are often used by device drivers to manage ranges of
 102 numeric identifiers that may be disjoint.
 103 A common use case for identifier spaces is to manage the set of allocated minor
 104 numbers for a device driver.
 105 .Ss Creating, Expanding and Destroying Identifier Spaces
 106 To create an identifier space, the
 107 .Fn id_space_create
 108 function should be used.
 109 A name for the id space must be passed in the
 110 .Fa name
 111 argument.
 112 It should be unique.
 113 For device drivers, often combining the name of the driver and the instance from
 114 the
 115 .Xr ddi_get_instance 9F
 116 function results in a unique name.
 117 .Pp
 118 The values of
 119 .Fa low
 120 and
 121 .Fa high
 122 describe the range of the identifier space.
 123 The range is inclusive on the low end and exclusive on the high end.
 124 Mathematically, this would be represented as
 125 .Pf [ Fa low ,
 126 .Fa high Ns ).
 127 .Pp
 128 Once the
 129 .Fn id_space_create
 130 function has been successfully called, the returned identifier space can
 131 be used to allocate and manage identifiers.
 132 .Pp
 133 Once an identifier space has been created, additional ranges of
 134 identifiers can be added.
 135 This process allows for disjoint ranges of values to be added to a single
 136 identifier space.
 137 The
 138 .Fn id_space_extend
 139 function is used to do this, and it adds the range
 140 .Fa low
 141 to
 142 .Fa high
 143 to the identifier space.
 144 The range follows the same rules as with the
 145 .Fn id_space_create
 146 function.
 147 It is inclusive of
 148 .Fa low
 149 and is exclusive of
 150 .Fa high .
 151 .Pp
 152 Finally, when an identifier space is no longer being used and all of its
 153 identifiers have been freed, the caller should call the
 154 .Fn id_space_destroy
 155 function to destroy the id space
 156 .Fa idspace .
 157 .Pp
 158 All three of these functions,
 159 .Fn id_space_create ,
 160 .Fn id_space_extend ,
 161 and
 162 .Fn id_space_destroy
 163 may block.
 164 They should only be called from a context where it's safe for it to block.
 165 This is equivalent to performing a blocking memory allocation.
 166 .Ss Allocating Identifiers
 167 Once an id space has been created with the
 168 .Fn id_space_create
 169 function, identifiers can be allocated from the space.
 170 There are three different strategies for allocating an identifier:
 171 .Bl -enum
 172 .It
 173 Allocating an identifier using the standard algorithm that attempts to
 174 use the next identifier first.
 175 .It
 176 Allocating an identifier using a first fit algorithm.
 177 These are functions with
 178 .Em ff
 179 in the name.
 180 Using this will tend to keep the allocated id space more compressed.
 181 .It
 182 Allocating a specific id.
 183 .El
 184 .Pp
 185 In addition, identifiers can be allocated in both a blocking and
 186 non-blocking fashion.
 187 When functions with the
 188 .Sy _nosleep
 189 prefix are used, they are non-blocking.
 190 If no identifier is available, they will return an error.
 191 .Pp
 192 The
 193 .Fn id_alloc
 194 function will allocate the next identifier.
 195 The
 196 .Fn id_alloc_nosleep
 197 function uses the same algorithm as
 198 .Fn id_alloc ,
 199 but will fail rather than block.
 200 .Pp
 201 The
 202 .Fn id_allocff
 203 function will allocate the first available identifier.
 204 The
 205 .Fn id_allocff_nosleep
 206 function uses the same algorithm as
 207 .Fn id_allocff ,
 208 but will fail rather than block.
 209 .Pp
 210 The
 211 .Fn id_alloc_specific_nosleep
 212 function attempts to allocate the specific identifier
 213 .Fa id
 214 from the specified identifier space.
 215 If
 216 .Fa id
 217 has already been allocated, then the function will fail.
 218 .Ss Freeing Identifiers
 219 Every allocated identifier must eventually be freed and returned to the
 220 identifier space.
 221 To free an identifier, use the
 222 .Fn id_free
 223 function, specifying the identifier in
 224 .Fa id
 225 and the identifier space it came from in
 226 .Fa id_space .
 227 It is a programmer error to call the
 228 .Fn id_free
 229 function on an identifier that has not been allocated.
 230 .Sh CONTEXT
 231 All of these functions may be called in
 232 .Sy user
 233 or
 234 .Sy kernel
 235 context.
 236 The
 237 .Fn id_alloc_nosleep ,
 238 .Fn id_allocff_nosleep ,
 239 and
 240 .Fn id_alloc_specific_nosleep
 241 functions may be called in
 242 .Sy interrupt
 243 context.
 244 .Sh RETURN VALUES
 245 Upon successful completion, the
 246 .Fn id_space_create
 247 function returns a pointer to an identifier space.
 248 Otherwise,
 249 .Dv NULL
 250 is returned to indicate that the identifier space could not be created.
 251 .Pp
 252 The
 253 .Fn id_alloc
 254 and
 255 .Fn id_allocff
 256 functions always return an identifier that's in the range of the
 257 specified identifier space.
 258 .Pp
 259 Upon successful completion, the
 260 .Fn id_alloc_nosleep ,
 261 .Fn id_allocff_nosleep ,
 262 and
 263 .Fn id_alloc_specific_nosleep
 264 functions will return an identifier that's in the range of the specified
 265 identifier space.
 266 Otherwise,
 267 .Sy -1
 268 is returned to indicate that no identifier was available, or in the case
 269 of the
 270 .Fn id_alloc_specific_nosleep
 271 function, that the specified identifier was not available.
 272 .Sh SEE ALSO
 273 .Xr kmem_alloc 9F ,
 274 .Xr rmallocmap 9F