101aaaf32SRobert Mustacchi.\" 201aaaf32SRobert Mustacchi.\" This file and its contents are supplied under the terms of the 301aaaf32SRobert Mustacchi.\" Common Development and Distribution License ("CDDL"), version 1.0. 401aaaf32SRobert Mustacchi.\" You may only use this file in accordance with the terms of version 501aaaf32SRobert Mustacchi.\" 1.0 of the CDDL. 601aaaf32SRobert Mustacchi.\" 701aaaf32SRobert Mustacchi.\" A full copy of the text of the CDDL should have accompanied this 801aaaf32SRobert Mustacchi.\" source. A copy of the CDDL is also available via the Internet at 901aaaf32SRobert Mustacchi.\" http://www.illumos.org/license/CDDL. 1001aaaf32SRobert Mustacchi.\" 1101aaaf32SRobert Mustacchi.\" 1201aaaf32SRobert Mustacchi.\" Copyright 2016 Joyent, Inc. 1301aaaf32SRobert Mustacchi.\" 141dcf899fSRobert Mustacchi.Dd Aug 02, 2016 1501aaaf32SRobert Mustacchi.Dt ID_SPACE 9F 1601aaaf32SRobert Mustacchi.Os 1701aaaf32SRobert Mustacchi.Sh NAME 1801aaaf32SRobert Mustacchi.Nm id_space , 1901aaaf32SRobert Mustacchi.Nm id_space_create , 2001aaaf32SRobert Mustacchi.Nm id_space_destroy , 2101aaaf32SRobert Mustacchi.Nm id_space_extend , 2201aaaf32SRobert Mustacchi.Nm id_alloc , 2301aaaf32SRobert Mustacchi.Nm id_alloc_nosleep , 2401aaaf32SRobert Mustacchi.Nm id_allocff , 2501aaaf32SRobert Mustacchi.Nm id_allocff_nosleep , 2601aaaf32SRobert Mustacchi.Nm id_alloc_specific_nosleep , 2701aaaf32SRobert Mustacchi.Nm id_free 2801aaaf32SRobert Mustacchi.Nd create, destroy, and use identifier spaces 2901aaaf32SRobert Mustacchi.Sh SYNOPSIS 3001aaaf32SRobert Mustacchi.In sys/id_space.h 3101aaaf32SRobert Mustacchi.Ft "id_space_t *" 3201aaaf32SRobert Mustacchi.Fo id_space_create 3301aaaf32SRobert Mustacchi.Fa "const char *name" 3401aaaf32SRobert Mustacchi.Fa "id_t low" 3501aaaf32SRobert Mustacchi.Fa "id_t high" 3601aaaf32SRobert Mustacchi.Fc 3701aaaf32SRobert Mustacchi.Ft void 3801aaaf32SRobert Mustacchi.Fo id_space_destroy 3901aaaf32SRobert Mustacchi.Fa "id_space_t *idspace" 4001aaaf32SRobert Mustacchi.Fc 4101aaaf32SRobert Mustacchi.Ft void 4201aaaf32SRobert Mustacchi.Fo id_space_extend 4301aaaf32SRobert Mustacchi.Fa "id_t low" 4401aaaf32SRobert Mustacchi.Fa "id_t high" 4501aaaf32SRobert Mustacchi.Fc 4601aaaf32SRobert Mustacchi.Ft id_t 4701aaaf32SRobert Mustacchi.Fo id_alloc 4801aaaf32SRobert Mustacchi.Fa "id_space_t *idspace" 4901aaaf32SRobert Mustacchi.Fc 5001aaaf32SRobert Mustacchi.Ft id_t 5101aaaf32SRobert Mustacchi.Fo id_alloc_nosleep 5201aaaf32SRobert Mustacchi.Fa "id_space_t *idspace" 5301aaaf32SRobert Mustacchi.Fc 5401aaaf32SRobert Mustacchi.Ft id_t 5501aaaf32SRobert Mustacchi.Fo id_allocff 5601aaaf32SRobert Mustacchi.Fa "id_space_t *idspace" 5701aaaf32SRobert Mustacchi.Fc 5801aaaf32SRobert Mustacchi.Ft id_t 5901aaaf32SRobert Mustacchi.Fo id_allocff_nosleep 6001aaaf32SRobert Mustacchi.Fa "id_space_t *idspace" 6101aaaf32SRobert Mustacchi.Fc 6201aaaf32SRobert Mustacchi.Ft id_t 6301aaaf32SRobert Mustacchi.Fo id_allocff_specific_nosleep 6401aaaf32SRobert Mustacchi.Fa "id_space_t *idspace" 6501aaaf32SRobert Mustacchi.Fa "id_t id" 6601aaaf32SRobert Mustacchi.Fc 6701aaaf32SRobert Mustacchi.Ft void 6801aaaf32SRobert Mustacchi.Fo id_free 6901aaaf32SRobert Mustacchi.Fa "id_space_t *idspace" 7001aaaf32SRobert Mustacchi.Fa "id_t id" 7101aaaf32SRobert Mustacchi.Fc 7201aaaf32SRobert Mustacchi.Sh INTERFACE STABILITY 7301aaaf32SRobert Mustacchiillumos DDI specific 7401aaaf32SRobert Mustacchi.Sh PARAMETERS 7501aaaf32SRobert Mustacchi.Bl -tag -width Fa 7601aaaf32SRobert Mustacchi.It Fa idspace 7701aaaf32SRobert MustacchiA pointer to an 7801aaaf32SRobert Mustacchi.Sy id_space_t 7901aaaf32SRobert Mustacchistructure allocated with the 8001aaaf32SRobert Mustacchi.Fn id_space_create 8101aaaf32SRobert Mustacchifunction. 8201aaaf32SRobert Mustacchi.It Fa id 8301aaaf32SRobert MustacchiAn identifier, a signed 32-bit integer. 8401aaaf32SRobert Mustacchi.It Fa name 851dcf899fSRobert MustacchiAn ASCII character string to call the identifier space. 8601aaaf32SRobert Mustacchi.It Fa low 87*72d3dbb9SYuri PankovThe lower end of an identifier space. 88*72d3dbb9SYuri PankovThis value is included in the range. 8901aaaf32SRobert Mustacchi.It Fa high 90*72d3dbb9SYuri PankovThe upper end of an identifier space. 91*72d3dbb9SYuri PankovThis value is excluded from the range. 9201aaaf32SRobert Mustacchi.El 9301aaaf32SRobert Mustacchi.Sh DESCRIPTION 9401aaaf32SRobert MustacchiThe 9501aaaf32SRobert Mustacchi.Sy id_space 96*72d3dbb9SYuri Pankovsuite of functions is used to create and manage identifier spaces. 97*72d3dbb9SYuri PankovAn identifier space allows the system to manage a range of identifiers. 98*72d3dbb9SYuri PankovIt tracks what values have been used and which values have not been used 9901aaaf32SRobert Mustacchiand has different ways of allocating values from the identifier space. 10001aaaf32SRobert Mustacchi.Pp 10101aaaf32SRobert MustacchiIdentifier spaces are often used by device drivers to manage ranges of 102*72d3dbb9SYuri Pankovnumeric identifiers that may be disjoint. 103*72d3dbb9SYuri PankovA common use case for identifier spaces is to manage the set of allocated minor 104*72d3dbb9SYuri Pankovnumbers for a device driver. 10501aaaf32SRobert Mustacchi.Ss Creating, Expanding and Destroying Identifier Spaces 10601aaaf32SRobert MustacchiTo create an identifier space, the 10701aaaf32SRobert Mustacchi.Fn id_space_create 108*72d3dbb9SYuri Pankovfunction should be used. 109*72d3dbb9SYuri PankovA name for the id space must be passed in the 11001aaaf32SRobert Mustacchi.Fa name 111*72d3dbb9SYuri Pankovargument. 112*72d3dbb9SYuri PankovIt should be unique. 113*72d3dbb9SYuri PankovFor device drivers, often combining the name of the driver and the instance from 114*72d3dbb9SYuri Pankovthe 11501aaaf32SRobert Mustacchi.Xr ddi_get_instance 9F 11601aaaf32SRobert Mustacchifunction results in a unique name. 11701aaaf32SRobert Mustacchi.Pp 11801aaaf32SRobert MustacchiThe values of 11901aaaf32SRobert Mustacchi.Fa low 12001aaaf32SRobert Mustacchiand 12101aaaf32SRobert Mustacchi.Fa high 122*72d3dbb9SYuri Pankovdescribe the range of the identifier space. 123*72d3dbb9SYuri PankovThe range is inclusive on the low end and exclusive on the high end. 124*72d3dbb9SYuri PankovMathematically, this would be represented as 12501aaaf32SRobert Mustacchi.Pf [ Fa low , 12601aaaf32SRobert Mustacchi.Fa high Ns ). 12701aaaf32SRobert Mustacchi.Pp 12801aaaf32SRobert MustacchiOnce the 12901aaaf32SRobert Mustacchi.Fn id_space_create 13001aaaf32SRobert Mustacchifunction has been successfully called, the returned identifier space can 13101aaaf32SRobert Mustacchibe used to allocate and manage identifiers. 13201aaaf32SRobert Mustacchi.Pp 13301aaaf32SRobert MustacchiOnce an identifier space has been created, additional ranges of 134*72d3dbb9SYuri Pankovidentifiers can be added. 135*72d3dbb9SYuri PankovThis process allows for disjoint ranges of values to be added to a single 136*72d3dbb9SYuri Pankovidentifier space. 137*72d3dbb9SYuri PankovThe 13801aaaf32SRobert Mustacchi.Fn id_space_extend 13901aaaf32SRobert Mustacchifunction is used to do this, and it adds the range 14001aaaf32SRobert Mustacchi.Fa low 14101aaaf32SRobert Mustacchito 14201aaaf32SRobert Mustacchi.Fa high 143*72d3dbb9SYuri Pankovto the identifier space. 144*72d3dbb9SYuri PankovThe range follows the same rules as with the 14501aaaf32SRobert Mustacchi.Fn id_space_create 14601aaaf32SRobert Mustacchifunction. 14701aaaf32SRobert MustacchiIt is inclusive of 14801aaaf32SRobert Mustacchi.Fa low 14901aaaf32SRobert Mustacchiand is exclusive of 15001aaaf32SRobert Mustacchi.Fa high . 15101aaaf32SRobert Mustacchi.Pp 15201aaaf32SRobert MustacchiFinally, when an identifier space is no longer being used and all of its 15301aaaf32SRobert Mustacchiidentifiers have been freed, the caller should call the 15401aaaf32SRobert Mustacchi.Fn id_space_destroy 15501aaaf32SRobert Mustacchifunction to destroy the id space 15601aaaf32SRobert Mustacchi.Fa idspace . 15701aaaf32SRobert Mustacchi.Pp 15801aaaf32SRobert MustacchiAll three of these functions, 15901aaaf32SRobert Mustacchi.Fn id_space_create , 16001aaaf32SRobert Mustacchi.Fn id_space_extend , 16101aaaf32SRobert Mustacchiand 1621dcf899fSRobert Mustacchi.Fn id_space_destroy 163*72d3dbb9SYuri Pankovmay block. 164*72d3dbb9SYuri PankovThey should only be called from a context where it's safe for it to block. 165*72d3dbb9SYuri PankovThis is equivalent to performing a blocking memory allocation. 16601aaaf32SRobert Mustacchi.Ss Allocating Identifiers 16701aaaf32SRobert MustacchiOnce an id space has been created with the 16801aaaf32SRobert Mustacchi.Fn id_space_create 169*72d3dbb9SYuri Pankovfunction, identifiers can be allocated from the space. 170*72d3dbb9SYuri PankovThere are three different strategies for allocating an identifier: 17101aaaf32SRobert Mustacchi.Bl -enum 17201aaaf32SRobert Mustacchi.It 17301aaaf32SRobert MustacchiAllocating an identifier using the standard algorithm that attempts to 17401aaaf32SRobert Mustacchiuse the next identifier first. 17501aaaf32SRobert Mustacchi.It 176*72d3dbb9SYuri PankovAllocating an identifier using a first fit algorithm. 177*72d3dbb9SYuri PankovThese are functions with 17801aaaf32SRobert Mustacchi.Em ff 179*72d3dbb9SYuri Pankovin the name. 180*72d3dbb9SYuri PankovUsing this will tend to keep the allocated id space more compressed. 18101aaaf32SRobert Mustacchi.It 18201aaaf32SRobert MustacchiAllocating a specific id. 18301aaaf32SRobert Mustacchi.El 18401aaaf32SRobert Mustacchi.Pp 18501aaaf32SRobert MustacchiIn addition, identifiers can be allocated in both a blocking and 186*72d3dbb9SYuri Pankovnon-blocking fashion. 187*72d3dbb9SYuri PankovWhen functions with the 18801aaaf32SRobert Mustacchi.Sy _nosleep 189*72d3dbb9SYuri Pankovprefix are used, they are non-blocking. 190*72d3dbb9SYuri PankovIf no identifier is available, they will return an error. 19101aaaf32SRobert Mustacchi.Pp 19201aaaf32SRobert MustacchiThe 19301aaaf32SRobert Mustacchi.Fn id_alloc 194*72d3dbb9SYuri Pankovfunction will allocate the next identifier. 195*72d3dbb9SYuri PankovThe 19601aaaf32SRobert Mustacchi.Fn id_alloc_nosleep 19701aaaf32SRobert Mustacchifunction uses the same algorithm as 19801aaaf32SRobert Mustacchi.Fn id_alloc , 19901aaaf32SRobert Mustacchibut will fail rather than block. 20001aaaf32SRobert Mustacchi.Pp 20101aaaf32SRobert MustacchiThe 20201aaaf32SRobert Mustacchi.Fn id_allocff 203*72d3dbb9SYuri Pankovfunction will allocate the first available identifier. 204*72d3dbb9SYuri PankovThe 20501aaaf32SRobert Mustacchi.Fn id_allocff_nosleep 20601aaaf32SRobert Mustacchifunction uses the same algorithm as 20701aaaf32SRobert Mustacchi.Fn id_allocff , 20801aaaf32SRobert Mustacchibut will fail rather than block. 20901aaaf32SRobert Mustacchi.Pp 21001aaaf32SRobert MustacchiThe 21101aaaf32SRobert Mustacchi.Fn id_alloc_specific_nosleep 21201aaaf32SRobert Mustacchifunction attempts to allocate the specific identifier 21301aaaf32SRobert Mustacchi.Fa id 214*72d3dbb9SYuri Pankovfrom the specified identifier space. 215*72d3dbb9SYuri PankovIf 21601aaaf32SRobert Mustacchi.Fa id 21701aaaf32SRobert Mustacchihas already been allocated, then the function will fail. 21801aaaf32SRobert Mustacchi.Ss Freeing Identifiers 21901aaaf32SRobert MustacchiEvery allocated identifier must eventually be freed and returned to the 220*72d3dbb9SYuri Pankovidentifier space. 221*72d3dbb9SYuri PankovTo free an identifier, use the 22201aaaf32SRobert Mustacchi.Fn id_free 22301aaaf32SRobert Mustacchifunction, specifying the identifier in 22401aaaf32SRobert Mustacchi.Fa id 22501aaaf32SRobert Mustacchiand the identifier space it came from in 22601aaaf32SRobert Mustacchi.Fa id_space . 22701aaaf32SRobert MustacchiIt is a programmer error to call the 22801aaaf32SRobert Mustacchi.Fn id_free 22901aaaf32SRobert Mustacchifunction on an identifier that has not been allocated. 23001aaaf32SRobert Mustacchi.Sh CONTEXT 2311dcf899fSRobert MustacchiAll of these functions may be called in 2321dcf899fSRobert Mustacchi.Sy user 23301aaaf32SRobert Mustacchior 2341dcf899fSRobert Mustacchi.Sy kernel 235*72d3dbb9SYuri Pankovcontext. 236*72d3dbb9SYuri PankovThe 2371dcf899fSRobert Mustacchi.Fn id_alloc_nosleep , 2381dcf899fSRobert Mustacchi.Fn id_allocff_nosleep , 23901aaaf32SRobert Mustacchiand 2401dcf899fSRobert Mustacchi.Fn id_alloc_specific_nosleep 2411dcf899fSRobert Mustacchifunctions may be called in 2421dcf899fSRobert Mustacchi.Sy interrupt 2431dcf899fSRobert Mustacchicontext. 24401aaaf32SRobert Mustacchi.Sh RETURN VALUES 24501aaaf32SRobert MustacchiUpon successful completion, the 24601aaaf32SRobert Mustacchi.Fn id_space_create 247*72d3dbb9SYuri Pankovfunction returns a pointer to an identifier space. 248*72d3dbb9SYuri PankovOtherwise, 24901aaaf32SRobert Mustacchi.Dv NULL 25001aaaf32SRobert Mustacchiis returned to indicate that the identifier space could not be created. 25101aaaf32SRobert Mustacchi.Pp 25201aaaf32SRobert MustacchiThe 25301aaaf32SRobert Mustacchi.Fn id_alloc 25401aaaf32SRobert Mustacchiand 25501aaaf32SRobert Mustacchi.Fn id_allocff 25601aaaf32SRobert Mustacchifunctions always return an identifier that's in the range of the 25701aaaf32SRobert Mustacchispecified identifier space. 25801aaaf32SRobert Mustacchi.Pp 25901aaaf32SRobert MustacchiUpon successful completion, the 26001aaaf32SRobert Mustacchi.Fn id_alloc_nosleep , 26101aaaf32SRobert Mustacchi.Fn id_allocff_nosleep , 26201aaaf32SRobert Mustacchiand 26301aaaf32SRobert Mustacchi.Fn id_alloc_specific_nosleep 26401aaaf32SRobert Mustacchifunctions will return an identifier that's in the range of the specified 265*72d3dbb9SYuri Pankovidentifier space. 266*72d3dbb9SYuri PankovOtherwise, 26701aaaf32SRobert Mustacchi.Sy -1 26801aaaf32SRobert Mustacchiis returned to indicate that no identifier was available, or in the case 26901aaaf32SRobert Mustacchiof the 27001aaaf32SRobert Mustacchi.Fn id_alloc_specific_nosleep 27101aaaf32SRobert Mustacchifunction, that the specified identifier was not available. 27201aaaf32SRobert Mustacchi.Sh SEE ALSO 27301aaaf32SRobert Mustacchi.Xr kmem_alloc 9F , 27401aaaf32SRobert Mustacchi.Xr rmallocmap 9F 275