Document the ``resource management'' routines in rman(9).

Submitted by: Bruce M. Simpson <bms@spc.org>
Reviewed by: mdodd

Approved by: des (mentor), re (scottl)

2 files changed, 295 insertions, 0 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index c748bef..29a2241 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -60,6 +60,7 @@ MAN=	BUF_LOCK.9 BUF_LOCKFREE.9 BUF_LOCKINIT.9 BUF_REFCNT.9 \
 	physio.9 printf.9 pseudofs.9 psignal.9 \
 	random.9 resettodr.9 resource_int_value.9 resource_query_string.9 \
 	rtalloc.9 rtentry.9 runqueue.9  random_harvest.9 rijndael.9 \
+	rman.9 \
 	sbuf.9 scheduler.9 selrecord.9 sema.9 signal.9 sleep.9 sleepqueue.9 \
 	spl.9 store.9 style.9 suser.9 swi.9 sx.9 \
 	sysctl_add_oid.9 sysctl_ctx_init.9 \
diff --git a/share/man/man9/rman.9 b/share/man/man9/rman.9
new file mode 100644
index 0000000..31c9bcf
--- /dev/null
+++ b/share/man/man9/rman.9
@@ -0,0 +1,294 @@
+.\"
+.\" Copyright (c) 2003 Bruce M Simpson <bms@spc.org>
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd May 12, 2003
+.Dt RMAN 9
+.Os
+.Sh NAME
+.Nm rman ,
+.Nm rman_activate_resource , 
+.Nm rman_await_resource , 
+.Nm rman_deactivate_resource , 
+.Nm rman_fini , 
+.Nm rman_init , 
+.Nm rman_manage_region , 
+.Nm rman_release_resource , 
+.Nm rman_reserve_resource , 
+.Nm rman_reserve_resource_bound , 
+.Nm rman_make_alignment_flags , 
+.Nm rman_get_start , 
+.Nm rman_get_end , 
+.Nm rman_get_size , 
+.Nm rman_get_flags , 
+.Nm rman_set_virtual , 
+.Nm rman_get_virtual , 
+.Nm rman_set_bustag , 
+.Nm rman_get_bustag , 
+.Nm rman_set_bushandle , 
+.Nm rman_get_bushandle , 
+.Nm rman_set_rid , 
+.Nm rman_get_rid   
+.Nd resource management functions
+.Sh SYNOPSIS
+.In sys/rman.h
+.Ft int
+.Fn rman_activate_resource "struct resource *r"
+.Ft int
+.Fn rman_await_resource "struct resource *r" "int pri2" "int timo"
+.Ft int
+.Fn rman_deactivate_resource "struct resource *r"
+.Ft int
+.Fn rman_fini "struct rman *rm"
+.Ft int
+.Fn rman_init "struct rman *rm"
+.Ft int
+.Fn rman_manage_region "struct rman *rm" "u_long start" "u_long end"
+.Ft int
+.Fn rman_release_resource "struct resource *r"
+.Ft struct resource *
+.Fn rman_reserve_resource "struct rman *rm" "u_long start" "u_long end" "u_long count" "u_int flags" "struct device *dev"
+.Ft struct resource *
+.Fn rman_reserve_resource_bound "struct rman *rm" "u_long start" "u_long end" "u_long count" "u_long bound" "u_int flags" "struct device *dev"
+.Ft uint32_t
+.Fn rman_make_alignment_flags "uint32_t size"
+.Ft u_long 
+.Fn rman_get_start "struct resource *_r"
+.Ft u_long
+.Fn rman_get_end "struct resource *_r"
+.Ft u_long
+.Fn rman_get_size "struct resource *_r"
+.Ft u_int
+.Fn rman_get_flags "struct resource *_r"
+.Ft void
+.Fn rman_set_virtual "struct resource *_r" "void *_v"
+.Ft void *
+.Fn rman_get_virtual "struct resource *_r"
+.Ft void
+.Fn rman_set_bustag "struct resource *_r" "bus_space_tag_t _t"
+.Ft bus_space_tag_t
+.Fn rman_get_bustag "struct resource *_r"
+.Ft void
+.Fn rman_set_bushandle "struct resource *_r" "bus_space_handle_t _h"
+.Ft bus_space_handle_t
+.Fn rman_get_bushandle "struct resource *_r"
+.Ft void
+.Fn rman_set_rid "struct resource *_r" "int _rid"
+.Ft int 
+.Fn rman_get_rid "struct resource *_r"
+.Sh DESCRIPTION
+The
+.Nm
+set of functions provides a flexible resource management abstraction.
+It is used extensively by the bus management code.
+It implements the abstractions of region and resource.
+A region descriptor is used to manage a region; this could be memory or
+some other form of bus space.
+.Pp
+Each region has a set of bounds.
+Within these bounds, allocated segments may reside.
+Each segment, termed a resource, has several properties which are
+represented by a 16-bit flag register, as follows.
+.Bd -literal
+#define RF_ALLOCATED    0x0001 /* resource has been reserved */
+#define RF_ACTIVE       0x0002 /* resource allocation has been activated */
+#define RF_SHAREABLE    0x0004 /* resource permits contemporaneous sharing */
+#define RF_TIMESHARE    0x0008 /* resource permits time-division sharing */
+#define RF_WANTED       0x0010 /* somebody is waiting for this resource */
+#define RF_FIRSTSHARE   0x0020 /* first in sharing list */
+#define RF_PREFETCHABLE 0x0040 /* resource is prefetchable */
+.Ed
+.Pp
+The remainder of the flag bits are used to represent the desired alignment
+of the resource within the region.
+.Pp
+The
+.Fn rman_init
+function initializes the region descriptor, pointed to by the
+.Fa rm
+argument, for use with the resource management functions.
+It also initializes any mutexes associated with the structure.
+.Pp
+The
+.Fn rman_fini
+function frees any structures associated with the structure
+pointed to by the
+.Fa rm
+argument. If any of the resources within the managed
+region have the
+.Dv RF_ALLOCATED
+flag set, it will return
+.Er EBUSY ;
+otherwise, any mutexes associated with the structure will be released
+and destroyed, and the function will return 0.
+.Pp
+The
+.Fn rman_manage_region
+function establishes the concept of a region which is under
+.Nm
+control.
+The
+.Fa rman
+argument points to the region descriptor.
+The start and end arguments specify the bounds of the region.
+.Pp
+.Em NOTE :
+This interface is not robust against programming errors which
+add multiple copies of the same region.
+.Pp
+The
+.Fn rman_reserve_resource_bound
+function is where the bulk of the
+.Nm logic is located.
+It attempts to reserve a contiguous range in the specified region
+.Fa rm
+for the use of the device
+.Fa dev .
+The caller can specify the start and end of an acceptable range, as well as
+alignment, and the code will attempt to find a free segment which fits.
+The default behavior is to allocate an exclusive segment, unless the
+.Dv RF_SHAREABLE
+or
+.Dv RF_TIMESHARE
+flags are set, in which case a shared
+segment will be allocated.
+If this shared segment already exists, the caller has its device
+added to the list of consumers.
+.Pp
+The
+.Fn rman_reserve_resource
+function is used to reserve resources within a previously established region.
+It is a simplified interface to
+.Fn rman_reserve_resource_bound
+which passes 0 for the
+.Fa flags
+argument.
+.Pp
+The
+.Fn rman_make_alignment_flags
+function returns the flag mask corresponding to the desired alignment
+.Fa size .
+This should be used when calling
+.Fn rman_reserve_resource_bound .
+.Pp
+The
+.Fn rman_release_resource
+function releases the reserved resource
+.Fa r .
+It may attempt to merge adjacent free resources.
+.Pp
+The
+.Fn rman_activate_resource
+function marks a resource as active, by setting the
+.Dv RF_ACTIVE
+flag.
+If this is a time shared resource, and the caller has not yet acquired
+the resource, the function returns
+.Er EBUSY.
+.Pp
+The
+.Fn rman_deactivate_resource
+function marks a resource
+.Fa r
+as inactive, by clearing the
+.Dv RF_ACTIVE
+flag.
+If other consumers are waiting for this range, it will wakeup their threads.
+.Pp
+The
+.Fn rman_await_resource
+function performs an asynchronous wait for a resource
+.Fa r
+to become inactive, that is, for the
+.Dv RF_ACTIVE
+flag to be cleared.
+It is used to enable cooperative sharing of a resource
+which can only be safely used by one thread at a time.
+The arguments
+.Fa pri
+and
+.Fa timo
+are passed to the
+.Fn rman_await_resource
+function.
+.Pp
+The
+.Fn rman_get_start ,
+.Fn rman_get_end ,
+.Fn rman_get_size , and
+.Fn rman_get_flags
+functions return the bounds, size and flags of the previously reserved
+resource
+.Fa r .
+.Pp
+The
+.Fn rman_set_bustag
+function associates a bus_space_tag_t
+.Fa t
+with the resource
+.Fa r .
+The
+.Fn rman_get_bustag
+function is used to retrieve this tag once set.
+.Pp
+The
+.Fn rman_set_bushandle
+function associates a bus_space_handle_t
+.Fa h
+with the resource
+.Fa r .
+The
+.Fn rman_get_bushandle
+function is used to retrieve this handle once set.
+.Pp
+The
+.Fn rman_set_virtual
+function is used to associate a kernel virtual address with a resource
+.Fa r .
+The
+.Fn rman_get_virtual
+function can be used to retrieve the KVA once set.
+.Pp
+The
+.Fn rman_set_rid
+function associates a resource identifier with a resource
+.Fa r .
+The rman_get_rid function retrieves this RID.
+.Pp
+The
+.Fn rman_get_device
+function returns a pointer to the device which reserved the resource
+.Fa r .
+.Pp
+.Sh SEE ALSO
+.Xr bus_activate_resource 9 ,
+.Xr bus_alloc_resource 9 ,
+.Xr bus_release_resource 9 ,
+.Xr bus_set_resource 9 ,
+.Xr mutex 9
+.Sh AUTHORS
+This man page was written by
+.An Bruce M Simpson Aq bms@spc.org .