7051 want id_space(9F) docs

Reviewed by: Jerry Jelinek <jerry.jelinek@joyent.com>
Reviewed by: Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
Approved by: Richard Lowe <richlowe@richlowe.net>

3 files changed, 296 insertions, 0 deletions

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