share/man/man9/rman.9

   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
 116 The
 117 .Nm
 118 set of functions provides a flexible resource management abstraction,
 119 they are used extensively by the bus management code.
 120 It implements the abstractions of region and resource.
 121 A region descriptor is used to manage a region; this could be memory or
 122 some other form of bus space.
 123 .Pp
 124 Each region has a set of bounds.
 125 Within these bounds, allocated segments may reside.
 126 Each segment, termed a resource, has several properties which are
 127 represented 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
 138 The remainder of the flag bits are used to represent the desired alignment
 139 of the resource within the region.
 140 .Pp
 141 The
 142 .Fn rman_init
 143 function initializes the region descriptor, pointed to by the
 144 .Fa rm
 145 argument, for use with the resource management functions.
 146 It also initializes any mutexes associated with the structure.
 147 .Pp
 148 The
 149 .Fn rman_fini
 150 function frees any structures associated with the structure
 151 pointed to by the
 152 .Fa rm
 153 argument.
 154 If any of the resources within the managed region have the
 155 .Dv RF_ALLOCATED
 156 flag set, it will return
 157 .Er EBUSY ;
 158 otherwise, any mutexes associated with the structure will be released
 159 and destroyed, and the function will return 0.
 160 .Pp
 161 The
 162 .Fn rman_manage_region
 163 function establishes the concept of a region which is under
 164 .Nm
 165 control.
 166 The
 167 .Fa rman
 168 argument points to the region descriptor.
 169 The
 170 .Fa start
 171 and
 172 .Fa end
 173 arguments specify the bounds of the region.
 174 .Pp
 175 .Em NOTE :
 176 This interface is not robust against programming errors which
 177 add 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
 203 The
 204 .Fn rman_reserve_resource
 205 function is used to reserve resources within a previously established region.
 206 It is a simplified interface to
 207 .Fn rman_reserve_resource_bound
 208 which passes 0 for the
 209 .Fa flags
 210 argument.
 211 .Pp
 212 The
 213 .Fn rman_make_alignment_flags
 214 function returns the flag mask corresponding to the desired alignment
 215 .Fa size .
 216 This should be used when calling
 217 .Fn rman_reserve_resource_bound .
 218 .Pp
 219 The
 220 .Fn rman_release_resource
 221 function releases the reserved resource
 222 .Fa r .
 223 It may attempt to merge adjacent free resources.
 224 .Pp
 225 The
 226 .Fn rman_activate_resource
 227 function marks a resource as active, by setting the
 228 .Dv RF_ACTIVE
 229 flag.
 230 If this is a time shared resource, and the caller has not yet acquired
 231 the resource, the function returns
 232 .Er EBUSY .
 233 .Pp
 234 The
 235 .Fn rman_deactivate_resource
 236 function marks a resource
 237 .Fa r
 238 as inactive, by clearing the
 239 .Dv RF_ACTIVE
 240 flag.
 241 If other consumers are waiting for this range, it will wakeup their threads.
 242 .Pp
 243 The
 244 .Fn rman_await_resource
 245 function performs an asynchronous wait for a resource
 246 .Fa r
 247 to become inactive, that is, for the
 248 .Dv RF_ACTIVE
 249 flag to be cleared.
 250 It is used to enable cooperative sharing of a resource
 251 which can only be safely used by one thread at a time.
 252 The arguments
 253 .Fa pri
 254 and
 255 .Fa timo
 256 are passed to the
 257 .Fn rman_await_resource
 258 function.
 259 .Pp
 260 The
 261 .Fn rman_get_start ,
 262 .Fn rman_get_end ,
 263 .Fn rman_get_size ,
 264 and
 265 .Fn rman_get_flags
 266 functions return the bounds, size and flags of the previously reserved
 267 resource
 268 .Fa r .
 269 .Pp
 270 The
 271 .Fn rman_set_bustag
 272 function associates a
 273 .Vt bus_space_tag_t
 274 .Fa t
 275 with the resource
 276 .Fa r .
 277 The
 278 .Fn rman_get_bustag
 279 function is used to retrieve this tag once set.
 280 .Pp
 281 The
 282 .Fn rman_set_bushandle
 283 function associates a
 284 .Vt bus_space_handle_t
 285 .Fa h
 286 with the resource
 287 .Fa r .
 288 The
 289 .Fn rman_get_bushandle
 290 function is used to retrieve this handle once set.
 291 .Pp
 292 The
 293 .Fn rman_set_virtual
 294 function is used to associate a kernel virtual address with a resource
 295 .Fa r .
 296 The
 297 .Fn rman_get_virtual
 298 function 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
 308 The
 309 .Fn rman_get_device
 310 function 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
 320 This manual page was written by
 321 .An Bruce M Simpson Aq bms@spc.org ,
 322 later revised by
 323 .An Hiten Pandya Aq hmp@backplane.com .