ID_SPACE(9F) Kernel Functions for Drivers ID_SPACE(9F)

id_space, id_space_create, id_space_destroy, id_space_extend, id_alloc, id_alloc_nosleep, id_allocff, id_allocff_nosleep, id_alloc_specific_nosleep, id_free — create, destroy, and use identifier spaces

#include <sys/id_space.h>

id_space_t *
id_space_create(const char *name, id_t low, id_t high);

void
id_space_destroy(id_space_t *idspace);

void
id_space_extend(id_t low, id_t high);

id_t
id_alloc(id_space_t *idspace);

id_t
id_alloc_nosleep(id_space_t *idspace);

id_t
id_allocff(id_space_t *idspace);

id_t
id_allocff_nosleep(id_space_t *idspace);

id_t
id_allocff_specific_nosleep(id_space_t *idspace, id_t id);

void
id_free(id_space_t *idspace, id_t id);

illumos DDI specific

idspace
A pointer to an structure allocated with the () function.
id
An identifier, a signed 32-bit integer.
name
An ASCII character string to call the identifier space.
low
The lower end of an identifier space. This value is included in the range.
high
The upper end of an identifier space. This value is excluded from the range.

The suite of functions is used to create and manage identifier spaces. An identifier space allows the system to manage a range of identifiers. It tracks what values have been used and which values have not been used and has different ways of allocating values from the identifier space.

Identifier spaces are often used by device drivers to manage ranges of numeric identifiers that may be disjoint. A common use case for identifier spaces is to manage the set of allocated minor numbers for a device driver.

To create an identifier space, the () function should be used. A name for the id space must be passed in the name argument. It should be unique. For device drivers, often combining the name of the driver and the instance from the ddi_get_instance(9F) function results in a unique name.

The values of low and high describe the range of the identifier space. The range is inclusive on the low end and exclusive on the high end. Mathematically, this would be represented as [low, high).

Once the () function has been successfully called, the returned identifier space can be used to allocate and manage identifiers.

Once an identifier space has been created, additional ranges of identifiers can be added. This process allows for disjoint ranges of values to be added to a single identifier space. The () function is used to do this, and it adds the range low to high to the identifier space. The range follows the same rules as with the id_space_create() function. It is inclusive of low and is exclusive of high.

Finally, when an identifier space is no longer being used and all of its identifiers have been freed, the caller should call the () function to destroy the id space idspace.

All three of these functions, (), id_space_extend(), and id_space_destroy() may block. They should only be called from a context where it's safe for it to block. This is equivalent to performing a blocking memory allocation.

Once an id space has been created with the id_space_create() function, identifiers can be allocated from the space. There are three different strategies for allocating an identifier:

  1. Allocating an identifier using the standard algorithm that attempts to use the next identifier first.
  2. Allocating an identifier using a first fit algorithm. These are functions with in the name. Using this will tend to keep the allocated id space more compressed.
  3. Allocating a specific id.

In addition, identifiers can be allocated in both a blocking and non-blocking fashion. When functions with the prefix are used, they are non-blocking. If no identifier is available, they will return an error.

The () function will allocate the next identifier. The () function uses the same algorithm as id_alloc(), but will fail rather than block.

The () function will allocate the first available identifier. The () function uses the same algorithm as id_allocff(), but will fail rather than block.

The () function attempts to allocate the specific identifier id from the specified identifier space. If id has already been allocated, then the function will fail.

Every allocated identifier must eventually be freed and returned to the identifier space. To free an identifier, use the () function, specifying the identifier in id and the identifier space it came from in id_space. It is a programmer error to call the id_free() function on an identifier that has not been allocated.

All of these functions may be called in or context. The id_alloc_nosleep(), id_allocff_nosleep(), and id_alloc_specific_nosleep() functions may be called in context.

Upon successful completion, the id_space_create() function returns a pointer to an identifier space. Otherwise, NULL is returned to indicate that the identifier space could not be created.

The id_alloc() and id_allocff() functions always return an identifier that's in the range of the specified identifier space.

Upon successful completion, the id_alloc_nosleep(), id_allocff_nosleep(), and id_alloc_specific_nosleep() functions will return an identifier that's in the range of the specified identifier space. Otherwise, is returned to indicate that no identifier was available, or in the case of the id_alloc_specific_nosleep() function, that the specified identifier was not available.

kmem_alloc(9F), rmallocmap(9F)

August 2, 2016 OmniOS