usr/src/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. This value is included in the
  88 range.
  89 .It Fa high
  90 The upper end of an identifier space. This value is excluded from the
  91 range.
  92 .El
  93 .Sh DESCRIPTION
  94 The
  95 .Sy id_space
  96 suite of functions is used to create and manage identifier spaces. An
  97 identifier space allows the system to manage a range of identifiers. It
  98 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. A common use case for
 103 identifier spaces is to manage the set of allocated minor numbers for a
 104 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. A name for the id space must be passed in the
 109 .Fa name
 110 argument. It should be unique. For device drivers, often combining the
 111 name of the driver and the instance from the
 112 .Xr ddi_get_instance 9F
 113 function results in a unique name.
 114 .Pp
 115 The values of
 116 .Fa low
 117 and
 118 .Fa high
 119 describe the range of the identifier space. The range is inclusive on
 120 the low end and exclusive on the high end. Mathematically, this would be
 121 represented as
 122 .Pf [ Fa low ,
 123 .Fa high Ns ).
 124 .Pp
 125 Once the
 126 .Fn id_space_create
 127 function has been successfully called, the returned identifier space can
 128 be used to allocate and manage identifiers.
 129 .Pp
 130 Once an identifier space has been created, additional ranges of
 131 identifiers can be added. This process allows for disjoint ranges of
 132 values to be added to a single identifier space. The
 133 .Fn id_space_extend
 134 function is used to do this, and it adds the range
 135 .Fa low
 136 to
 137 .Fa high
 138 to the identifier space. The range follows the same rules as with the
 139 .Fn id_space_create
 140 function.
 141 It is inclusive of
 142 .Fa low
 143 and is exclusive of
 144 .Fa high .
 145 .Pp
 146 Finally, when an identifier space is no longer being used and all of its
 147 identifiers have been freed, the caller should call the
 148 .Fn id_space_destroy
 149 function to destroy the id space
 150 .Fa idspace .
 151 .Pp
 152 All three of these functions,
 153 .Fn id_space_create ,
 154 .Fn id_space_extend ,
 155 and
 156 .Fn id_space_destroy
 157 may block. They should only be called from a context where it's safe for
 158 it to block. This is equivalent to performing a blocking memory allocation.
 159 .Ss Allocating Identifiers
 160 Once an id space has been created with the
 161 .Fn id_space_create
 162 function, identifiers can be allocated from the space. There are three
 163 different strategies for allocating an identifier:
 164 .Bl -enum
 165 .It
 166 Allocating an identifier using the standard algorithm that attempts to
 167 use the next identifier first.
 168 .It
 169 Allocating an identifier using a first fit algorithm. These are
 170 functions with
 171 .Em ff
 172 in the name. Using this will tend to keep the allocated id space more
 173 compressed.
 174 .It
 175 Allocating a specific id.
 176 .El
 177 .Pp
 178 In addition, identifiers can be allocated in both a blocking and
 179 non-blocking fashion. When functions with the
 180 .Sy _nosleep
 181 prefix are used, they are non-blocking. If no identifier is available,
 182 they will return an error.
 183 .Pp
 184 The
 185 .Fn id_alloc
 186 function will allocate the next identifier. The
 187 .Fn id_alloc_nosleep
 188 function uses the same algorithm as
 189 .Fn id_alloc ,
 190 but will fail rather than block.
 191 .Pp
 192 The
 193 .Fn id_allocff
 194 function will allocate the first available identifier. The
 195 .Fn id_allocff_nosleep
 196 function uses the same algorithm as
 197 .Fn id_allocff ,
 198 but will fail rather than block.
 199 .Pp
 200 The
 201 .Fn id_alloc_specific_nosleep
 202 function attempts to allocate the specific identifier
 203 .Fa id
 204 from the specified identifier space. If
 205 .Fa id
 206 has already been allocated, then the function will fail.
 207 .Ss Freeing Identifiers
 208 Every allocated identifier must eventually be freed and returned to the
 209 identifier space. To free an identifier, use the
 210 .Fn id_free
 211 function, specifying the identifier in
 212 .Fa id
 213 and the identifier space it came from in
 214 .Fa id_space .
 215 It is a programmer error to call the
 216 .Fn id_free
 217 function on an identifier that has not been allocated.
 218 .Sh CONTEXT
 219 All of these functions may be called in
 220 .Sy user
 221 or
 222 .Sy kernel
 223 context. The
 224 .Fn id_alloc_nosleep ,
 225 .Fn id_allocff_nosleep ,
 226 and
 227 .Fn id_alloc_specific_nosleep
 228 functions may be called in
 229 .Sy interrupt
 230 context.
 231 .Sh RETURN VALUES
 232 Upon successful completion, the
 233 .Fn id_space_create
 234 function returns a pointer to an identifier space. Otherwise,
 235 .Dv NULL
 236 is returned to indicate that the identifier space could not be created.
 237 .Pp
 238 The
 239 .Fn id_alloc
 240 and
 241 .Fn id_allocff
 242 functions always return an identifier that's in the range of the
 243 specified identifier space.
 244 .Pp
 245 Upon successful completion, the
 246 .Fn id_alloc_nosleep ,
 247 .Fn id_allocff_nosleep ,
 248 and
 249 .Fn id_alloc_specific_nosleep
 250 functions will return an identifier that's in the range of the specified
 251 identifier space. Otherwise,
 252 .Sy -1
 253 is returned to indicate that no identifier was available, or in the case
 254 of the
 255 .Fn id_alloc_specific_nosleep
 256 function, that the specified identifier was not available.
 257 .Sh SEE ALSO
 258 .Xr kmem_alloc 9F ,
 259 .Xr rmallocmap 9F