1.\" 2.\" Copyright (c) 2004 Hiten Pandya <hmp@backplane.com> 3.\" Copyright (c) 2003 Bruce M Simpson <bms@spc.org> 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.\" $FreeBSD: src/share/man/man9/rman.9,v 1.2 2003/05/30 21:13:32 ru Exp $ 28.\" $DragonFly: src/share/man/man9/rman.9,v 1.1 2004/05/17 21:46:40 hmp Exp $ 29.\" 30.Dd May 12, 2003 31.Dt RMAN 9 32.Os 33.Sh NAME 34.Nm rman , 35.Nm rman_activate_resource , 36.Nm rman_await_resource , 37.Nm rman_deactivate_resource , 38.Nm rman_fini , 39.Nm rman_init , 40.Nm rman_manage_region , 41.Nm rman_release_resource , 42.Nm rman_reserve_resource , 43.\".Nm rman_reserve_resource_bound , 44.Nm rman_make_alignment_flags , 45.Nm rman_get_start , 46.Nm rman_get_end , 47.Nm rman_get_device , 48.Nm rman_get_size , 49.Nm rman_get_flags , 50.Nm rman_set_virtual , 51.Nm rman_get_virtual , 52.Nm rman_set_bustag , 53.Nm rman_get_bustag , 54.Nm rman_set_bushandle , 55.Nm rman_get_bushandle , 56.\".Nm rman_set_rid , 57.\".Nm rman_get_rid 58.Nd resource management functions 59.Sh SYNOPSIS 60.In sys/param.h 61.In sys/rman.h 62.Ft int 63.Fn rman_activate_resource "struct resource *r" 64.Ft int 65.Fn rman_await_resource "struct resource *r" "int pri2" "int timo" 66.Ft int 67.Fn rman_deactivate_resource "struct resource *r" 68.Ft int 69.Fn rman_fini "struct rman *rm" 70.Ft int 71.Fn rman_init "struct rman *rm" 72.Ft int 73.Fn rman_manage_region "struct rman *rm" "u_long start" "u_long end" 74.Ft int 75.Fn rman_release_resource "struct resource *r" 76.Ft "struct resource *" 77.Fo rman_reserve_resource 78.Fa "struct rman *rm" "u_long start" "u_long end" "u_long count" 79.Fa "u_int flags" "struct device *dev" 80.Fc 81.\".Ft "struct resource *" 82.\".Fo rman_reserve_resource_bound 83.\".Fa "struct rman *rm" "u_long start" "u_long end" "u_long count" 84.\".Fa "u_long bound" "u_int flags" "struct device *dev" 85.\".Fc 86.Ft uint32_t 87.Fn rman_make_alignment_flags "uint32_t size" 88.Pp 89.Ft u_long 90.Fn rman_get_start "struct resource *r" 91.Ft u_long 92.Fn rman_get_end "struct resource *r" 93.Ft "struct device *" 94.Fn rman_get_device "struct resource *r" 95.Ft u_long 96.Fn rman_get_size "struct resource *r" 97.Ft u_int 98.Fn rman_get_flags "struct resource *r" 99.Ft void 100.Fn rman_set_virtual "struct resource *r" "void *v" 101.Ft "void *" 102.Fn rman_get_virtual "struct resource *r" 103.Ft void 104.Fn rman_set_bustag "struct resource *r" "bus_space_tag_t t" 105.Ft bus_space_tag_t 106.Fn rman_get_bustag "struct resource *r" 107.Ft void 108.Fn rman_set_bushandle "struct resource *r" "bus_space_handle_t h" 109.Ft bus_space_handle_t 110.Fn rman_get_bushandle "struct resource *r" 111.\".Ft void 112.\".Fn rman_set_rid "struct resource *r" "int rid" 113.\".Ft int 114.\".Fn rman_get_rid "struct resource *r" 115.Sh DESCRIPTION 116The 117.Nm 118set of functions provides a flexible resource management abstraction, 119they are used extensively by the bus management code. 120It implements the abstractions of region and resource. 121A region descriptor is used to manage a region; this could be memory or 122some other form of bus space. 123.Pp 124Each region has a set of bounds. 125Within these bounds, allocated segments may reside. 126Each segment, termed a resource, has several properties which are 127represented by a 16-bit flag register, as follows. 128.Bd -literal 129#define RF_ALLOCATED 0x0001 /* resource has been reserved */ 130#define RF_ACTIVE 0x0002 /* resource allocation has been activated */ 131#define RF_SHAREABLE 0x0004 /* resource permits contemporaneous sharing */ 132#define RF_TIMESHARE 0x0008 /* resource permits time-division sharing */ 133#define RF_WANTED 0x0010 /* somebody is waiting for this resource */ 134#define RF_FIRSTSHARE 0x0020 /* first in sharing list */ 135#define RF_PREFETCHABLE 0x0040 /* resource is prefetchable */ 136.Ed 137.Pp 138The remainder of the flag bits are used to represent the desired alignment 139of the resource within the region. 140.Pp 141The 142.Fn rman_init 143function initializes the region descriptor, pointed to by the 144.Fa rm 145argument, for use with the resource management functions. 146It also initializes any mutexes associated with the structure. 147.Pp 148The 149.Fn rman_fini 150function frees any structures associated with the structure 151pointed to by the 152.Fa rm 153argument. 154If any of the resources within the managed region have the 155.Dv RF_ALLOCATED 156flag set, it will return 157.Er EBUSY ; 158otherwise, any mutexes associated with the structure will be released 159and destroyed, and the function will return 0. 160.Pp 161The 162.Fn rman_manage_region 163function establishes the concept of a region which is under 164.Nm 165control. 166The 167.Fa rman 168argument points to the region descriptor. 169The 170.Fa start 171and 172.Fa end 173arguments specify the bounds of the region. 174.Pp 175.Em NOTE : 176This interface is not robust against programming errors which 177add multiple copies of the same region. 178.\".Pp 179.\"The 180.\".Fn rman_reserve_resource_bound 181.\"function is where the bulk of the 182.\".Nm 183.\"logic is located. 184.\"It attempts to reserve a contiguous range in the specified region 185.\".Fa rm 186.\"for the use of the device 187.\".Fa dev . 188.\"The caller can specify the 189.\".Fa start 190.\"and 191.\".Fa end 192.\"of an acceptable range, as well as 193.\"alignment, and the code will attempt to find a free segment which fits. 194.\"The default behavior is to allocate an exclusive segment, unless the 195.\".Dv RF_SHAREABLE 196.\"or 197.\".Dv RF_TIMESHARE 198.\"flags are set, in which case a shared 199.\"segment will be allocated. 200.\"If this shared segment already exists, the caller has its device 201.\"added to the list of consumers. 202.Pp 203The 204.Fn rman_reserve_resource 205function is used to reserve resources within a previously established region. 206It is a simplified interface to 207.Fn rman_reserve_resource_bound 208which passes 0 for the 209.Fa flags 210argument. 211.Pp 212The 213.Fn rman_make_alignment_flags 214function returns the flag mask corresponding to the desired alignment 215.Fa size . 216This should be used when calling 217.Fn rman_reserve_resource_bound . 218.Pp 219The 220.Fn rman_release_resource 221function releases the reserved resource 222.Fa r . 223It may attempt to merge adjacent free resources. 224.Pp 225The 226.Fn rman_activate_resource 227function marks a resource as active, by setting the 228.Dv RF_ACTIVE 229flag. 230If this is a time shared resource, and the caller has not yet acquired 231the resource, the function returns 232.Er EBUSY . 233.Pp 234The 235.Fn rman_deactivate_resource 236function marks a resource 237.Fa r 238as inactive, by clearing the 239.Dv RF_ACTIVE 240flag. 241If other consumers are waiting for this range, it will wakeup their threads. 242.Pp 243The 244.Fn rman_await_resource 245function performs an asynchronous wait for a resource 246.Fa r 247to become inactive, that is, for the 248.Dv RF_ACTIVE 249flag to be cleared. 250It is used to enable cooperative sharing of a resource 251which can only be safely used by one thread at a time. 252The arguments 253.Fa pri 254and 255.Fa timo 256are passed to the 257.Fn rman_await_resource 258function. 259.Pp 260The 261.Fn rman_get_start , 262.Fn rman_get_end , 263.Fn rman_get_size , 264and 265.Fn rman_get_flags 266functions return the bounds, size and flags of the previously reserved 267resource 268.Fa r . 269.Pp 270The 271.Fn rman_set_bustag 272function associates a 273.Vt bus_space_tag_t 274.Fa t 275with the resource 276.Fa r . 277The 278.Fn rman_get_bustag 279function is used to retrieve this tag once set. 280.Pp 281The 282.Fn rman_set_bushandle 283function associates a 284.Vt bus_space_handle_t 285.Fa h 286with the resource 287.Fa r . 288The 289.Fn rman_get_bushandle 290function is used to retrieve this handle once set. 291.Pp 292The 293.Fn rman_set_virtual 294function is used to associate a kernel virtual address with a resource 295.Fa r . 296The 297.Fn rman_get_virtual 298function can be used to retrieve the KVA once set. 299.\".Pp 300.\"The 301.\".Fn rman_set_rid 302.\"function associates a resource identifier with a resource 303.\".Fa r . 304.\"The 305.\".Fn rman_get_rid 306.\"function retrieves this RID. 307.Pp 308The 309.Fn rman_get_device 310function returns a pointer to the device which reserved the resource 311.Fa r . 312.Pp 313.Sh SEE ALSO 314.\".Xr bus_activate_resource 9 , 315.Xr bus_alloc_resource 9 316.Xr bus_release_resource 9 , 317.\".Xr bus_set_resource 9 , 318.Sh AUTHORS 319.An -nosplit 320This manual page was written by 321.An Bruce M Simpson Aq bms@spc.org , 322later revised by 323.An Hiten Pandya Aq hmp@backplane.com . 324