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