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. This value is included in the 88range. 89.It Fa high 90The upper end of an identifier space. This value is excluded from 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_destroy 157may block. They should only be called from a context where it's safe for 158it to block. This is equivalent to performing a blocking memory allocation. 159.Ss Allocating Identifiers 160Once an id space has been created with the 161.Fn id_space_create 162function, identifiers can be allocated from the space. There are three 163different strategies for allocating an identifier: 164.Bl -enum 165.It 166Allocating an identifier using the standard algorithm that attempts to 167use the next identifier first. 168.It 169Allocating an identifier using a first fit algorithm. These are 170functions with 171.Em ff 172in the name. Using this will tend to keep the allocated id space more 173compressed. 174.It 175Allocating a specific id. 176.El 177.Pp 178In addition, identifiers can be allocated in both a blocking and 179non-blocking fashion. When functions with the 180.Sy _nosleep 181prefix are used, they are non-blocking. If no identifier is available, 182they will return an error. 183.Pp 184The 185.Fn id_alloc 186function will allocate the next identifier. The 187.Fn id_alloc_nosleep 188function uses the same algorithm as 189.Fn id_alloc , 190but will fail rather than block. 191.Pp 192The 193.Fn id_allocff 194function will allocate the first available identifier. The 195.Fn id_allocff_nosleep 196function uses the same algorithm as 197.Fn id_allocff , 198but will fail rather than block. 199.Pp 200The 201.Fn id_alloc_specific_nosleep 202function attempts to allocate the specific identifier 203.Fa id 204from the specified identifier space. If 205.Fa id 206has already been allocated, then the function will fail. 207.Ss Freeing Identifiers 208Every allocated identifier must eventually be freed and returned to the 209identifier space. To free an identifier, use the 210.Fn id_free 211function, specifying the identifier in 212.Fa id 213and the identifier space it came from in 214.Fa id_space . 215It is a programmer error to call the 216.Fn id_free 217function on an identifier that has not been allocated. 218.Sh CONTEXT 219All of these functions may be called in 220.Sy user 221or 222.Sy kernel 223context. The 224.Fn id_alloc_nosleep , 225.Fn id_allocff_nosleep , 226and 227.Fn id_alloc_specific_nosleep 228functions may be called in 229.Sy interrupt 230context. 231.Sh RETURN VALUES 232Upon successful completion, the 233.Fn id_space_create 234function returns a pointer to an identifier space. Otherwise, 235.Dv NULL 236is returned to indicate that the identifier space could not be created. 237.Pp 238The 239.Fn id_alloc 240and 241.Fn id_allocff 242functions always return an identifier that's in the range of the 243specified identifier space. 244.Pp 245Upon successful completion, the 246.Fn id_alloc_nosleep , 247.Fn id_allocff_nosleep , 248and 249.Fn id_alloc_specific_nosleep 250functions will return an identifier that's in the range of the specified 251identifier space. Otherwise, 252.Sy -1 253is returned to indicate that no identifier was available, or in the case 254of the 255.Fn id_alloc_specific_nosleep 256function, that the specified identifier was not available. 257.Sh SEE ALSO 258.Xr kmem_alloc 9F , 259.Xr rmallocmap 9F 260