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.\" 14*1dcf899fSRobert 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 85*1dcf899fSRobert MustacchiAn ASCII character string to call the identifier space. 8601aaaf32SRobert Mustacchi.It Fa low 8701aaaf32SRobert MustacchiThe lower end of an identifier space. This value is included in the 8801aaaf32SRobert Mustacchirange. 8901aaaf32SRobert Mustacchi.It Fa high 90*1dcf899fSRobert MustacchiThe upper end of an identifier space. This value is excluded from the 9101aaaf32SRobert Mustacchirange. 9201aaaf32SRobert Mustacchi.El 9301aaaf32SRobert Mustacchi.Sh DESCRIPTION 9401aaaf32SRobert MustacchiThe 9501aaaf32SRobert Mustacchi.Sy id_space 9601aaaf32SRobert Mustacchisuite of functions is used to create and manage identifier spaces. An 9701aaaf32SRobert Mustacchiidentifier space allows the system to manage a range of identifiers. It 9801aaaf32SRobert Mustacchitracks 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 10201aaaf32SRobert Mustacchinumeric identifiers that may be disjoint. A common use case for 10301aaaf32SRobert Mustacchiidentifier spaces is to manage the set of allocated minor numbers for a 10401aaaf32SRobert Mustacchidevice driver. 10501aaaf32SRobert Mustacchi.Ss Creating, Expanding and Destroying Identifier Spaces 10601aaaf32SRobert MustacchiTo create an identifier space, the 10701aaaf32SRobert Mustacchi.Fn id_space_create 10801aaaf32SRobert Mustacchifunction should be used. A name for the id space must be passed in the 10901aaaf32SRobert Mustacchi.Fa name 11001aaaf32SRobert Mustacchiargument. It should be unique. For device drivers, often combining the 11101aaaf32SRobert Mustacchiname of the driver and the instance from the 11201aaaf32SRobert Mustacchi.Xr ddi_get_instance 9F 11301aaaf32SRobert Mustacchifunction results in a unique name. 11401aaaf32SRobert Mustacchi.Pp 11501aaaf32SRobert MustacchiThe values of 11601aaaf32SRobert Mustacchi.Fa low 11701aaaf32SRobert Mustacchiand 11801aaaf32SRobert Mustacchi.Fa high 11901aaaf32SRobert Mustacchidescribe the range of the identifier space. The range is inclusive on 12001aaaf32SRobert Mustacchithe low end and exclusive on the high end. Mathematically, this would be 12101aaaf32SRobert Mustacchirepresented as 12201aaaf32SRobert Mustacchi.Pf [ Fa low , 12301aaaf32SRobert Mustacchi.Fa high Ns ). 12401aaaf32SRobert Mustacchi.Pp 12501aaaf32SRobert MustacchiOnce the 12601aaaf32SRobert Mustacchi.Fn id_space_create 12701aaaf32SRobert Mustacchifunction has been successfully called, the returned identifier space can 12801aaaf32SRobert Mustacchibe used to allocate and manage identifiers. 12901aaaf32SRobert Mustacchi.Pp 13001aaaf32SRobert MustacchiOnce an identifier space has been created, additional ranges of 13101aaaf32SRobert Mustacchiidentifiers can be added. This process allows for disjoint ranges of 13201aaaf32SRobert Mustacchivalues to be added to a single identifier space. The 13301aaaf32SRobert Mustacchi.Fn id_space_extend 13401aaaf32SRobert Mustacchifunction is used to do this, and it adds the range 13501aaaf32SRobert Mustacchi.Fa low 13601aaaf32SRobert Mustacchito 13701aaaf32SRobert Mustacchi.Fa high 13801aaaf32SRobert Mustacchito the identifier space. The range follows the same rules as with the 13901aaaf32SRobert Mustacchi.Fn id_space_create 14001aaaf32SRobert Mustacchifunction. 14101aaaf32SRobert MustacchiIt is inclusive of 14201aaaf32SRobert Mustacchi.Fa low 14301aaaf32SRobert Mustacchiand is exclusive of 14401aaaf32SRobert Mustacchi.Fa high . 14501aaaf32SRobert Mustacchi.Pp 14601aaaf32SRobert MustacchiFinally, when an identifier space is no longer being used and all of its 14701aaaf32SRobert Mustacchiidentifiers have been freed, the caller should call the 14801aaaf32SRobert Mustacchi.Fn id_space_destroy 14901aaaf32SRobert Mustacchifunction to destroy the id space 15001aaaf32SRobert Mustacchi.Fa idspace . 15101aaaf32SRobert Mustacchi.Pp 15201aaaf32SRobert MustacchiAll three of these functions, 15301aaaf32SRobert Mustacchi.Fn id_space_create , 15401aaaf32SRobert Mustacchi.Fn id_space_extend , 15501aaaf32SRobert Mustacchiand 156*1dcf899fSRobert Mustacchi.Fn id_space_destroy 15701aaaf32SRobert Mustacchimay block. They should only be called from a context where it's safe for 158*1dcf899fSRobert Mustacchiit to block. This is equivalent to performing a blocking memory allocation. 15901aaaf32SRobert Mustacchi.Ss Allocating Identifiers 16001aaaf32SRobert MustacchiOnce an id space has been created with the 16101aaaf32SRobert Mustacchi.Fn id_space_create 16201aaaf32SRobert Mustacchifunction, identifiers can be allocated from the space. There are three 16301aaaf32SRobert Mustacchidifferent strategies for allocating an identifier: 16401aaaf32SRobert Mustacchi.Bl -enum 16501aaaf32SRobert Mustacchi.It 16601aaaf32SRobert MustacchiAllocating an identifier using the standard algorithm that attempts to 16701aaaf32SRobert Mustacchiuse the next identifier first. 16801aaaf32SRobert Mustacchi.It 16901aaaf32SRobert MustacchiAllocating an identifier using a first fit algorithm. These are 17001aaaf32SRobert Mustacchifunctions with 17101aaaf32SRobert Mustacchi.Em ff 17201aaaf32SRobert Mustacchiin the name. Using this will tend to keep the allocated id space more 17301aaaf32SRobert Mustacchicompressed. 17401aaaf32SRobert Mustacchi.It 17501aaaf32SRobert MustacchiAllocating a specific id. 17601aaaf32SRobert Mustacchi.El 17701aaaf32SRobert Mustacchi.Pp 17801aaaf32SRobert MustacchiIn addition, identifiers can be allocated in both a blocking and 17901aaaf32SRobert Mustacchinon-blocking fashion. When functions with the 18001aaaf32SRobert Mustacchi.Sy _nosleep 18101aaaf32SRobert Mustacchiprefix are used, they are non-blocking. If no identifier is available, 18201aaaf32SRobert Mustacchithey will return an error. 18301aaaf32SRobert Mustacchi.Pp 18401aaaf32SRobert MustacchiThe 18501aaaf32SRobert Mustacchi.Fn id_alloc 18601aaaf32SRobert Mustacchifunction will allocate the next identifier. The 18701aaaf32SRobert Mustacchi.Fn id_alloc_nosleep 18801aaaf32SRobert Mustacchifunction uses the same algorithm as 18901aaaf32SRobert Mustacchi.Fn id_alloc , 19001aaaf32SRobert Mustacchibut will fail rather than block. 19101aaaf32SRobert Mustacchi.Pp 19201aaaf32SRobert MustacchiThe 19301aaaf32SRobert Mustacchi.Fn id_allocff 19401aaaf32SRobert Mustacchifunction will allocate the first available identifier. The 19501aaaf32SRobert Mustacchi.Fn id_allocff_nosleep 19601aaaf32SRobert Mustacchifunction uses the same algorithm as 19701aaaf32SRobert Mustacchi.Fn id_allocff , 19801aaaf32SRobert Mustacchibut will fail rather than block. 19901aaaf32SRobert Mustacchi.Pp 20001aaaf32SRobert MustacchiThe 20101aaaf32SRobert Mustacchi.Fn id_alloc_specific_nosleep 20201aaaf32SRobert Mustacchifunction attempts to allocate the specific identifier 20301aaaf32SRobert Mustacchi.Fa id 20401aaaf32SRobert Mustacchifrom the specified identifier space. If 20501aaaf32SRobert Mustacchi.Fa id 20601aaaf32SRobert Mustacchihas already been allocated, then the function will fail. 20701aaaf32SRobert Mustacchi.Ss Freeing Identifiers 20801aaaf32SRobert MustacchiEvery allocated identifier must eventually be freed and returned to the 20901aaaf32SRobert Mustacchiidentifier space. To free an identifier, use the 21001aaaf32SRobert Mustacchi.Fn id_free 21101aaaf32SRobert Mustacchifunction, specifying the identifier in 21201aaaf32SRobert Mustacchi.Fa id 21301aaaf32SRobert Mustacchiand the identifier space it came from in 21401aaaf32SRobert Mustacchi.Fa id_space . 21501aaaf32SRobert MustacchiIt is a programmer error to call the 21601aaaf32SRobert Mustacchi.Fn id_free 21701aaaf32SRobert Mustacchifunction on an identifier that has not been allocated. 21801aaaf32SRobert Mustacchi.Sh CONTEXT 219*1dcf899fSRobert MustacchiAll of these functions may be called in 220*1dcf899fSRobert Mustacchi.Sy user 22101aaaf32SRobert Mustacchior 222*1dcf899fSRobert Mustacchi.Sy kernel 223*1dcf899fSRobert Mustacchicontext. The 224*1dcf899fSRobert Mustacchi.Fn id_alloc_nosleep , 225*1dcf899fSRobert Mustacchi.Fn id_allocff_nosleep , 22601aaaf32SRobert Mustacchiand 227*1dcf899fSRobert Mustacchi.Fn id_alloc_specific_nosleep 228*1dcf899fSRobert Mustacchifunctions may be called in 229*1dcf899fSRobert Mustacchi.Sy interrupt 230*1dcf899fSRobert Mustacchicontext. 23101aaaf32SRobert Mustacchi.Sh RETURN VALUES 23201aaaf32SRobert MustacchiUpon successful completion, the 23301aaaf32SRobert Mustacchi.Fn id_space_create 23401aaaf32SRobert Mustacchifunction returns a pointer to an identifier space. Otherwise, 23501aaaf32SRobert Mustacchi.Dv NULL 23601aaaf32SRobert Mustacchiis returned to indicate that the identifier space could not be created. 23701aaaf32SRobert Mustacchi.Pp 23801aaaf32SRobert MustacchiThe 23901aaaf32SRobert Mustacchi.Fn id_alloc 24001aaaf32SRobert Mustacchiand 24101aaaf32SRobert Mustacchi.Fn id_allocff 24201aaaf32SRobert Mustacchifunctions always return an identifier that's in the range of the 24301aaaf32SRobert Mustacchispecified identifier space. 24401aaaf32SRobert Mustacchi.Pp 24501aaaf32SRobert MustacchiUpon successful completion, the 24601aaaf32SRobert Mustacchi.Fn id_alloc_nosleep , 24701aaaf32SRobert Mustacchi.Fn id_allocff_nosleep , 24801aaaf32SRobert Mustacchiand 24901aaaf32SRobert Mustacchi.Fn id_alloc_specific_nosleep 25001aaaf32SRobert Mustacchifunctions will return an identifier that's in the range of the specified 25101aaaf32SRobert Mustacchiidentifier space. Otherwise, 25201aaaf32SRobert Mustacchi.Sy -1 25301aaaf32SRobert Mustacchiis returned to indicate that no identifier was available, or in the case 25401aaaf32SRobert Mustacchiof the 25501aaaf32SRobert Mustacchi.Fn id_alloc_specific_nosleep 25601aaaf32SRobert Mustacchifunction, that the specified identifier was not available. 25701aaaf32SRobert Mustacchi.Sh SEE ALSO 25801aaaf32SRobert Mustacchi.Xr kmem_alloc 9F , 25901aaaf32SRobert Mustacchi.Xr rmallocmap 9F 260