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