From 01aaaf328842760a1002109b299908a027e94cf8 Mon Sep 17 00:00:00 2001 From: Robert Mustacchi Date: Sat, 4 Jun 2016 16:50:08 -0700 Subject: 7051 want id_space(9F) docs Reviewed by: Jerry Jelinek Reviewed by: Josef 'Jeff' Sipek Approved by: Richard Lowe --- usr/src/man/man9f/Makefile | 20 ++ usr/src/man/man9f/id_space.9f | 266 ++++++++++++++++++++++++++ usr/src/pkg/manifests/system-kernel.man9f.inc | 10 + 3 files changed, 296 insertions(+) create mode 100644 usr/src/man/man9f/id_space.9f diff --git a/usr/src/man/man9f/Makefile b/usr/src/man/man9f/Makefile index d02ddd76c5..ffd15b5778 100644 --- a/usr/src/man/man9f/Makefile +++ b/usr/src/man/man9f/Makefile @@ -279,6 +279,7 @@ MANFILES= ASSERT.9f \ gld.9f \ hook_alloc.9f \ hook_free.9f \ + id_space.9f \ id32_alloc.9f \ inb.9f \ insq.9f \ @@ -892,6 +893,15 @@ MANLINKS= SIZEOF_PTR.9f \ gld_register.9f \ gld_sched.9f \ gld_unregister.9f \ + id_space_create.9f \ + id_space_destroy.9f \ + id_space_extend.9f \ + id_alloc.9f \ + id_alloc_nosleep.9f \ + id_allocff.9f \ + id_allocff_nosleep.9f \ + id_alloc_specific_nosleep.9f \ + id_free.9f \ id32_free.9f \ id32_lookup.9f \ inl.9f \ @@ -1659,6 +1669,16 @@ gld_register.9f := LINKSRC = gld.9f gld_sched.9f := LINKSRC = gld.9f gld_unregister.9f := LINKSRC = gld.9f +id_space_create.9f := LINKSRC = id_space.9f +id_space_destroy.9f := LINKSRC = id_space.9f +id_space_extend.9f := LINKSRC = id_space.9f +id_alloc.9f := LINKSRC = id_space.9f +id_alloc_nosleep.9f := LINKSRC = id_space.9f +id_allocff.9f := LINKSRC = id_space.9f +id_allocff_nosleep.9f := LINKSRC = id_space.9f +id_alloc_specific_nosleep.9f := LINKSRC = id_space.9f +id_free.9f := LINKSRC = id_space.9f + id32_free.9f := LINKSRC = id32_alloc.9f id32_lookup.9f := LINKSRC = id32_alloc.9f diff --git a/usr/src/man/man9f/id_space.9f b/usr/src/man/man9f/id_space.9f new file mode 100644 index 0000000000..b9770cab1f --- /dev/null +++ b/usr/src/man/man9f/id_space.9f @@ -0,0 +1,266 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 2016 Joyent, Inc. +.\" +.Dd June 04, 2016 +.Dt ID_SPACE 9F +.Os +.Sh NAME +.Nm id_space , +.Nm id_space_create , +.Nm id_space_destroy , +.Nm id_space_extend , +.Nm id_alloc , +.Nm id_alloc_nosleep , +.Nm id_allocff , +.Nm id_allocff_nosleep , +.Nm id_alloc_specific_nosleep , +.Nm id_free +.Nd create, destroy, and use identifier spaces +.Sh SYNOPSIS +.In sys/id_space.h +.Ft "id_space_t *" +.Fo id_space_create +.Fa "const char *name" +.Fa "id_t low" +.Fa "id_t high" +.Fc +.Ft void +.Fo id_space_destroy +.Fa "id_space_t *idspace" +.Fc +.Ft void +.Fo id_space_extend +.Fa "id_t low" +.Fa "id_t high" +.Fc +.Ft id_t +.Fo id_alloc +.Fa "id_space_t *idspace" +.Fc +.Ft id_t +.Fo id_alloc_nosleep +.Fa "id_space_t *idspace" +.Fc +.Ft id_t +.Fo id_allocff +.Fa "id_space_t *idspace" +.Fc +.Ft id_t +.Fo id_allocff_nosleep +.Fa "id_space_t *idspace" +.Fc +.Ft id_t +.Fo id_allocff_specific_nosleep +.Fa "id_space_t *idspace" +.Fa "id_t id" +.Fc +.Ft void +.Fo id_free +.Fa "id_space_t *idspace" +.Fa "id_t id" +.Fc +.Sh INTERFACE STABILITY +illumos DDI specific +.Sh PARAMETERS +.Bl -tag -width Fa +.It Fa idspace +A pointer to an +.Sy id_space_t +structure allocated with the +.Fn id_space_create +function. +.It Fa id +An identifier, a signed 32-bit integer. +.It Fa name +A null-terminated ASCII character string to call the identifier space. +.It Fa low +The lower end of an identifier space. This value is included in the +range. +.It Fa high +The upper end of an identifier space. This value is excluded in the +range. +.El +.Sh DESCRIPTION +The +.Sy id_space +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. +.Pp +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. +.Ss Creating, Expanding and Destroying Identifier Spaces +To create an identifier space, the +.Fn id_space_create +function should be used. A name for the id space must be passed in the +.Fa name +argument. It should be unique. For device drivers, often combining the +name of the driver and the instance from the +.Xr ddi_get_instance 9F +function results in a unique name. +.Pp +The values of +.Fa low +and +.Fa 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 +.Pf [ Fa low , +.Fa high Ns ). +.Pp +Once the +.Fn id_space_create +function has been successfully called, the returned identifier space can +be used to allocate and manage identifiers. +.Pp +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 +.Fn id_space_extend +function is used to do this, and it adds the range +.Fa low +to +.Fa high +to the identifier space. The range follows the same rules as with the +.Fn id_space_create +function. +It is inclusive of +.Fa low +and is exclusive of +.Fa high . +.Pp +Finally, when an identifier space is no longer being used and all of its +identifiers have been freed, the caller should call the +.Fn id_space_destroy +function to destroy the id space +.Fa idspace . +.Pp +All three of these functions, +.Fn id_space_create , +.Fn id_space_extend , +and +.Fn id_space_destory +may block. They should only be called from a context where it's safe for +it to block. This is logically the equivalent of calling +.Xr kmem_alloc 9F +with the flag +.Dv KMEM_SLEEP . +.Ss Allocating Identifiers +Once an id space has been created with the +.Fn id_space_create +function, identifiers can be allocated from the space. There are three +different strategies for allocating an identifier: +.Bl -enum +.It +Allocating an identifier using the standard algorithm that attempts to +use the next identifier first. +.It +Allocating an identifier using a first fit algorithm. These are +functions with +.Em ff +in the name. Using this will tend to keep the allocated id space more +compressed. +.It +Allocating a specific id. +.El +.Pp +In addition, identifiers can be allocated in both a blocking and +non-blocking fashion. When functions with the +.Sy _nosleep +prefix are used, they are non-blocking. If no identifier is available, +they will return an error. +.Pp +The +.Fn id_alloc +function will allocate the next identifier. The +.Fn id_alloc_nosleep +function uses the same algorithm as +.Fn id_alloc , +but will fail rather than block. +.Pp +The +.Fn id_allocff +function will allocate the first available identifier. The +.Fn id_allocff_nosleep +function uses the same algorithm as +.Fn id_allocff , +but will fail rather than block. +.Pp +The +.Fn id_alloc_specific_nosleep +function attempts to allocate the specific identifier +.Fa id +from the specified identifier space. If +.Fa id +has already been allocated, then the function will fail. +.Ss Freeing Identifiers +Every allocated identifier must eventually be freed and returned to the +identifier space. To free an identifier, use the +.Fn id_free +function, specifying the identifier in +.Fa id +and the identifier space it came from in +.Fa id_space . +It is a programmer error to call the +.Fn id_free +function on an identifier that has not been allocated. +.Sh CONTEXT +In general, all the functions listed here may be executed in either +.Sy user , +.Sy kernel , +or +.Sy interrupt +context. However, the functions +.Fn id_space_create , +.Fn id_space_destroy , +.Fn id_space_extend , +.Fn id_alloc , +and +.Fn id_allocff +must be called from a context where it is safe to block and sleep. If +the caller is not in such a context, then it must only use the +.Sy '_nosleep' +functions. +.Sh RETURN VALUES +Upon successful completion, the +.Fn id_space_create +function returns a pointer to an identifier space. Otherwise, +.Dv NULL +is returned to indicate that the identifier space could not be created. +.Pp +The +.Fn id_alloc +and +.Fn id_allocff +functions always return an identifier that's in the range of the +specified identifier space. +.Pp +Upon successful completion, the +.Fn id_alloc_nosleep , +.Fn id_allocff_nosleep , +and +.Fn id_alloc_specific_nosleep +functions will return an identifier that's in the range of the specified +identifier space. Otherwise, +.Sy -1 +is returned to indicate that no identifier was available, or in the case +of the +.Fn id_alloc_specific_nosleep +function, that the specified identifier was not available. +.Sh SEE ALSO +.Xr kmem_alloc 9F , +.Xr rmallocmap 9F diff --git a/usr/src/pkg/manifests/system-kernel.man9f.inc b/usr/src/pkg/manifests/system-kernel.man9f.inc index 94e46f191c..a9046569c0 100644 --- a/usr/src/pkg/manifests/system-kernel.man9f.inc +++ b/usr/src/pkg/manifests/system-kernel.man9f.inc @@ -275,6 +275,7 @@ file path=usr/share/man/man9f/gld.9f file path=usr/share/man/man9f/hook_alloc.9f file path=usr/share/man/man9f/hook_free.9f file path=usr/share/man/man9f/id32_alloc.9f +file path=usr/share/man/man9f/id_space.9f file path=usr/share/man/man9f/inb.9f file path=usr/share/man/man9f/insq.9f file path=usr/share/man/man9f/kiconv.9f @@ -903,6 +904,15 @@ link path=usr/share/man/man9f/gld_sched.9f target=gld.9f link path=usr/share/man/man9f/gld_unregister.9f target=gld.9f link path=usr/share/man/man9f/id32_free.9f target=id32_alloc.9f link path=usr/share/man/man9f/id32_lookup.9f target=id32_alloc.9f +link path=usr/share/man/man9f/id_alloc.9f target=id_space.9f +link path=usr/share/man/man9f/id_alloc_nosleep.9f target=id_space.9f +link path=usr/share/man/man9f/id_alloc_specific_nosleep.9f target=id_space.9f +link path=usr/share/man/man9f/id_allocff.9f target=id_space.9f +link path=usr/share/man/man9f/id_allocff_nosleep.9f target=id_space.9f +link path=usr/share/man/man9f/id_free.9f target=id_space.9f +link path=usr/share/man/man9f/id_space_create.9f target=id_space.9f +link path=usr/share/man/man9f/id_space_destroy.9f target=id_space.9f +link path=usr/share/man/man9f/id_space_extend.9f target=id_space.9f link path=usr/share/man/man9f/inl.9f target=inb.9f link path=usr/share/man/man9f/intro.9f target=Intro.9f link path=usr/share/man/man9f/inw.9f target=inb.9f -- cgit v1.2.3