From 96bce568b227b19fc6a42f587f030df8a05c8212 Mon Sep 17 00:00:00 2001 From: Hiten Pandya Date: Mon, 17 May 2004 21:46:40 +0000 Subject: [PATCH] Document the ``resource management'' (rman) abstraction in rman(9). The rman(9) manual page has sufficient information on the rman_* functions and some background on the concept of regions and resources and how rman(9) abstracts them. Install the necessary MLINKs. Note: Some of the functions have been commented out in the mdoc(7) until I or Joerg get around to updating the DragonFly rman(9) abstraction. After that is done, other parts of the maual page can be expanded. Obtained-from: FreeBSD (HEAD) Adapted-by: Hiten Pandya --- share/man/man9/Makefile | 29 +++- share/man/man9/rman.9 | 323 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 350 insertions(+), 2 deletions(-) create mode 100644 share/man/man9/rman.9 diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index 26e471bc97..82f43a9c7b 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -1,5 +1,5 @@ # $FreeBSD: src/share/man/man9/Makefile,v 1.60.2.26 2003/06/13 01:04:17 hmp Exp $ -# $DragonFly: src/share/man/man9/Makefile,v 1.9 2004/05/15 19:44:17 hmp Exp $ +# $DragonFly: src/share/man/man9/Makefile,v 1.10 2004/05/17 21:46:40 hmp Exp $ MAN= DECLARE_MODULE.9 DELAY.9 DEV_MODULE.9 KASSERT.9 MD5.9 \ MODULE_DEPEND.9 MODULE_VERSION.9 SPLASSERT.9 SYSCALL_MODULE.9 \ @@ -22,7 +22,9 @@ MAN= DECLARE_MODULE.9 DELAY.9 DEV_MODULE.9 KASSERT.9 MD5.9 \ ifnet.9 inittodr.9 intro.9 kernacc.9 lock.9 \ malloc.9 make_dev.9 mbuf.9 microseq.9 mi_switch.9 module.9 namei.9 \ pci.9 panic.9 physio.9 posix4.9 psignal.9 \ - resettodr.9 rtalloc.9 rtentry.9 sleep.9 spl.9 \ + resettodr.9 \ + rman.9 \ + rtalloc.9 rtentry.9 sleep.9 spl.9 \ store.9 style.9 suser.9 time.9 timeout.9 uio.9 \ vget.9 vnode.9 vput.9 vref.9 vrele.9 vslock.9 \ microtime.9 microuptime.9 tvtohz.9 @@ -101,6 +103,29 @@ MLINKS+=pci.9 pci_get_powerstate.9 pci.9 pci_set_powerstate.9 MLINKS+=pci.9 pci_find_bsf.9 pci.9 pci_find_device.9 MLINKS+=posix4.9 p1003_1b.9 MLINKS+=psignal.9 gsignal.9 psignal.9 pgsignal.9 +MLINKS+=rman.9 rman_activate_resource.9 +MLINKS+=rman.9 rman_await_resource.9 +MLINKS+=rman.9 rman_deactivate_resource.9 +MLINKS+=rman.9 rman_fini.9 +MLINKS+=rman.9 rman_fini.9 +MLINKS+=rman.9 rman_get_bushandle.9 +MLINKS+=rman.9 rman_get_bustag.9 +MLINKS+=rman.9 rman_get_end.9 +MLINKS+=rman_get_flags.9 +#MLINKS+=rman.9 rman_get_rid.9 +MLINKS+=rman.9 rman_get_size.9 +MLINKS+=rman.9 rman_get_start.9 +MLINKS+=rman.9 rman_get_virtual.9 +MLINKS+=rman.9 rman_init.9 +MLINKS+=rman.9 rman_make_alignment_flags.9 +MLINKS+=rman.9 rman_manage_region.9 +MLINKS+=rman.9 rman_release_resource.9 +MLINKS+=rman.9 rman_reserve_resource.9 +#MLINKS+=rman.9 rman_reserve_resource_bound.9 +MLINKS+=rman.9 rman_set_bushandle.9 +MLINKS+=rman.9 rman_set_bustag.9 +#MLINKS+=rman.9 rman_set_rid.9 +MLINKS+=rman.9 rman_set_virtual.9 MLINKS+=rtalloc.9 rtalloc1.9 rtalloc.9 rtalloc_ign.9 MLINKS+=sleep.9 tsleep.9 sleep.9 wakeup.9 sleep.9 wakeup_one.9 MLINKS+=sleep.9 asleep.9 sleep.9 await.9 diff --git a/share/man/man9/rman.9 b/share/man/man9/rman.9 new file mode 100644 index 0000000000..bfdfc4d7cd --- /dev/null +++ b/share/man/man9/rman.9 @@ -0,0 +1,323 @@ +.\" +.\" Copyright (c) 2004 Hiten Pandya +.\" Copyright (c) 2003 Bruce M Simpson +.\" 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: src/share/man/man9/rman.9,v 1.2 2003/05/30 21:13:32 ru Exp $ +.\" $DragonFly: src/share/man/man9/rman.9,v 1.1 2004/05/17 21:46:40 hmp Exp $ +.\" +.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_device , +.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/param.h +.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 *" +.Fo rman_reserve_resource +.Fa "struct rman *rm" "u_long start" "u_long end" "u_long count" +.Fa "u_int flags" "struct device *dev" +.Fc +.\".Ft "struct resource *" +.\".Fo rman_reserve_resource_bound +.\".Fa "struct rman *rm" "u_long start" "u_long end" "u_long count" +.\".Fa "u_long bound" "u_int flags" "struct device *dev" +.\".Fc +.Ft uint32_t +.Fn rman_make_alignment_flags "uint32_t size" +.Pp +.Ft u_long +.Fn rman_get_start "struct resource *r" +.Ft u_long +.Fn rman_get_end "struct resource *r" +.Ft "struct device *" +.Fn rman_get_device "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, +they are 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 +.Fa start +and +.Fa 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 +.\".Fa start +.\"and +.\".Fa 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 +.Vt 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 +.Vt 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 +.\".Fn 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 , +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Bruce M Simpson Aq bms@spc.org , +later revised by +.An Hiten Pandya Aq hmp@backplane.com . -- 2.41.0