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