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/types.h 59.In sys/rman.h 60.Ft int 61.Fn rman_activate_resource "struct resource *r" 62.Ft int 63.Fn rman_await_resource "struct resource *r" "int pri2" "int timo" 64.Ft int 65.Fn rman_deactivate_resource "struct resource *r" 66.Ft int 67.Fn rman_fini "struct rman *rm" 68.Ft int 69.Fn rman_init "struct rman *rm" 70.Ft int 71.Fn rman_manage_region "struct rman *rm" "u_long start" "u_long end" 72.Ft int 73.Fn rman_release_resource "struct resource *r" 74.Ft "struct resource *" 75.Fo rman_reserve_resource 76.Fa "struct rman *rm" "u_long start" "u_long end" "u_long count" 77.Fa "u_int flags" "struct device *dev" 78.Fc 79.Ft "struct resource *" 80.Fo rman_reserve_resource_bound 81.Fa "struct rman *rm" "u_long start" "u_long end" "u_long count" 82.Fa "u_long bound" "u_int flags" "struct device *dev" 83.Fc 84.Ft uint32_t 85.Fn rman_make_alignment_flags "uint32_t size" 86.Ft u_long 87.Fn rman_get_start "struct resource *r" 88.Ft u_long 89.Fn rman_get_end "struct resource *r" 90.Ft "struct device *" 91.Fn rman_get_device "struct resource *r" 92.Ft u_long 93.Fn rman_get_size "struct resource *r" 94.Ft u_int 95.Fn rman_get_flags "struct resource *r" 96.Ft void 97.Fn rman_set_virtual "struct resource *r" "void *v" 98.Ft "void *" 99.Fn rman_get_virtual "struct resource *r" 100.Ft void 101.Fn rman_set_bustag "struct resource *r" "bus_space_tag_t t" 102.Ft bus_space_tag_t 103.Fn rman_get_bustag "struct resource *r" 104.Ft void 105.Fn rman_set_bushandle "struct resource *r" "bus_space_handle_t h" 106.Ft bus_space_handle_t 107.Fn rman_get_bushandle "struct resource *r" 108.Ft void 109.Fn rman_set_rid "struct resource *r" "int rid" 110.Ft int 111.Fn rman_get_rid "struct resource *r" 112.Sh DESCRIPTION 113The 114.Nm 115set of functions provides a flexible resource management abstraction. 116It is used extensively by the bus management code. 117It implements the abstractions of region and resource. 118A region descriptor is used to manage a region; this could be memory or 119some other form of bus space. 120.Pp 121Each region has a set of bounds. 122Within these bounds, allocated segments may reside. 123Each segment, termed a resource, has several properties which are 124represented by a 16-bit flag register, as follows. 125.Bd -literal 126#define RF_ALLOCATED 0x0001 /* resource has been reserved */ 127#define RF_ACTIVE 0x0002 /* resource allocation has been activated */ 128#define RF_SHAREABLE 0x0004 /* resource permits contemporaneous sharing */ 129#define RF_TIMESHARE 0x0008 /* resource permits time-division sharing */ 130#define RF_WANTED 0x0010 /* somebody is waiting for this resource */ 131#define RF_FIRSTSHARE 0x0020 /* first in sharing list */ 132#define RF_PREFETCHABLE 0x0040 /* resource is prefetchable */ 133.Ed 134.Pp 135The remainder of the flag bits are used to represent the desired alignment 136of the resource within the region. 137.Pp 138The 139.Fn rman_init 140function initializes the region descriptor, pointed to by the 141.Fa rm 142argument, for use with the resource management functions. 143It is required that the fields 144.Va rm_type 145and 146.Va rm_descr 147of 148.Vt "struct rman" 149be set before calling 150.Fn rman_init . 151The field 152.Va rm_type 153shall be set to 154.Dv RMAN_ARRAY . 155The field 156.Va rm_descr 157shall be set to a string that describes the resource to be managed. 158It also initializes any mutexes associated with the structure. 159If 160.Fn rman_init 161fails to initialize the mutex, it will return 162.Er ENOMEM ; otherwise it will return 0 and 163.Fa rm 164will be initialized. 165.Pp 166The 167.Fn rman_fini 168function frees any structures associated with the structure 169pointed to by the 170.Fa rm 171argument. 172If any of the resources within the managed region have the 173.Dv RF_ALLOCATED 174flag set, it will return 175.Er EBUSY ; 176otherwise, any mutexes associated with the structure will be released 177and destroyed, and the function will return 0. 178.Pp 179The 180.Fn rman_manage_region 181function establishes the concept of a region which is under 182.Nm 183control. 184The 185.Fa rman 186argument points to the region descriptor. 187The 188.Fa start 189and 190.Fa end 191arguments specify the bounds of the region. 192If successful, 193.Fn rman_manage_region 194will return 0. 195If the region overlaps with an existing region, it will return 196.Er EBUSY . 197.Er ENOMEM 198will be return when 199.Fn rman_manage_region 200failed to allocate memory for the region. 201.Pp 202The 203.Fn rman_reserve_resource_bound 204function is where the bulk of the 205.Nm 206logic is located. 207It attempts to reserve a contiguous range in the specified region 208.Fa rm 209for the use of the device 210.Fa dev . 211The caller can specify the 212.Fa start 213and 214.Fa end 215of an acceptable range, as well as 216alignment, and the code will attempt to find a free segment which fits. 217The 218.Fa start 219argument is the lowest acceptable starting value of the resource. 220The 221.Fa end 222argument is the highest acceptable ending value of the resource. 223Therefore, 224.Fa start No + Fa count No \- 1 225must be \[<=] 226.Fa end 227for any allocation to happen. 228The default behavior is to allocate an exclusive segment, unless the 229.Dv RF_SHAREABLE 230or 231.Dv RF_TIMESHARE 232flags are set, in which case a shared 233segment will be allocated. 234If this shared segment already exists, the caller has its device 235added to the list of consumers. 236.Pp 237The 238.Fn rman_reserve_resource 239function is used to reserve resources within a previously established region. 240It is a simplified interface to 241.Fn rman_reserve_resource_bound 242which passes 0 for the 243.Fa flags 244argument. 245.Pp 246The 247.Fn rman_make_alignment_flags 248function returns the flag mask corresponding to the desired alignment 249.Fa size . 250This should be used when calling 251.Fn rman_reserve_resource_bound . 252.Pp 253The 254.Fn rman_release_resource 255function releases the reserved resource 256.Fa r . 257It may attempt to merge adjacent free resources. 258.Pp 259The 260.Fn rman_activate_resource 261function marks a resource as active, by setting the 262.Dv RF_ACTIVE 263flag. 264If this is a time shared resource, and the caller has not yet acquired 265the resource, the function returns 266.Er EBUSY . 267.Pp 268The 269.Fn rman_deactivate_resource 270function marks a resource 271.Fa r 272as inactive, by clearing the 273.Dv RF_ACTIVE 274flag. 275If other consumers are waiting for this range, it will wakeup their threads. 276.Pp 277The 278.Fn rman_await_resource 279function performs an asynchronous wait for a resource 280.Fa r 281to become inactive, that is, for the 282.Dv RF_ACTIVE 283flag to be cleared. 284It is used to enable cooperative sharing of a resource 285which can only be safely used by one thread at a time. 286The arguments 287.Fa pri 288and 289.Fa timo 290are passed to the 291.Fn rman_await_resource 292function. 293.Pp 294The 295.Fn rman_get_start , 296.Fn rman_get_end , 297.Fn rman_get_size , 298and 299.Fn rman_get_flags 300functions return the bounds, size and flags of the previously reserved 301resource 302.Fa r . 303.Pp 304The 305.Fn rman_set_bustag 306function associates a 307.Vt bus_space_tag_t 308.Fa t 309with the resource 310.Fa r . 311The 312.Fn rman_get_bustag 313function is used to retrieve this tag once set. 314.Pp 315The 316.Fn rman_set_bushandle 317function associates a 318.Vt bus_space_handle_t 319.Fa h 320with the resource 321.Fa r . 322The 323.Fn rman_get_bushandle 324function is used to retrieve this handle once set. 325.Pp 326The 327.Fn rman_set_virtual 328function is used to associate a kernel virtual address with a resource 329.Fa r . 330The 331.Fn rman_get_virtual 332function can be used to retrieve the KVA once set. 333.Pp 334The 335.Fn rman_set_rid 336function associates a resource identifier with a resource 337.Fa r . 338The 339.Fn rman_get_rid 340function retrieves this RID. 341.Pp 342The 343.Fn rman_get_device 344function returns a pointer to the device which reserved the resource 345.Fa r . 346.Sh SEE ALSO 347.Xr bus_activate_resource 9 , 348.Xr bus_alloc_resource 9 , 349.Xr bus_release_resource 9 , 350.Xr bus_set_resource 9 , 351.Xr mutex 9 352.Sh AUTHORS 353This manual page was written by 354.An Bruce M Simpson Aq bms@spc.org . 355