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