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