6/share/man/man9/rman.9

   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 March 15, 2005
  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
 112 The
 113 .Nm
 114 set of functions provides a flexible resource management abstraction.
 115 It is used extensively by the bus management code.
 116 It implements the abstractions of region and resource.
 117 A region descriptor is used to manage a region; this could be memory or
 118 some other form of bus space.
 119 .Pp
 120 Each region has a set of bounds.
 121 Within these bounds, allocated segments may reside.
 122 Each segment, termed a resource, has several properties which are
 123 represented 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
 134 The remainder of the flag bits are used to represent the desired alignment
 135 of the resource within the region.
 136 .Pp
 137 The
 138 .Fn rman_init
 139 function initializes the region descriptor, pointed to by the
 140 .Fa rm
 141 argument, for use with the resource management functions.
 142 It also initializes any mutexes associated with the structure.
 143 .Pp
 144 The
 145 .Fn rman_fini
 146 function frees any structures associated with the structure
 147 pointed to by the
 148 .Fa rm
 149 argument.
 150 If any of the resources within the managed region have the
 151 .Dv RF_ALLOCATED
 152 flag set, it will return
 153 .Er EBUSY ;
 154 otherwise, any mutexes associated with the structure will be released
 155 and destroyed, and the function will return 0.
 156 .Pp
 157 The
 158 .Fn rman_manage_region
 159 function establishes the concept of a region which is under
 160 .Nm
 161 control.
 162 The
 163 .Fa rman
 164 argument points to the region descriptor.
 165 The
 166 .Fa start
 167 and
 168 .Fa end
 169 arguments specify the bounds of the region.
 170 .Pp
 171 .Em NOTE :
 172 This interface is not robust against programming errors which
 173 add multiple copies of the same region.
 174 .Pp
 175 The
 176 .Fn rman_reserve_resource_bound
 177 function is where the bulk of the
 178 .Nm
 179 logic is located.
 180 It attempts to reserve a contiguous range in the specified region
 181 .Fa rm
 182 for the use of the device
 183 .Fa dev .
 184 The caller can specify the
 185 .Fa start
 186 and
 187 .Fa end
 188 of an acceptable range, as well as
 189 alignment, and the code will attempt to find a free segment which fits.
 190 The
 191 .Fa start
 192 argument is the lowest acceptable starting value of the resource.
 193 The
 194 .Fa end
 195 argument is the highest acceptable ending value of the resource.
 196 Therefore,
 197 .Fa start No + Fa count No \- 1
 198 must be \[<=]
 199 .Fa end
 200 for any allocation to happen.
 201 The default behavior is to allocate an exclusive segment, unless the
 202 .Dv RF_SHAREABLE
 203 or
 204 .Dv RF_TIMESHARE
 205 flags are set, in which case a shared
 206 segment will be allocated.
 207 If this shared segment already exists, the caller has its device
 208 added to the list of consumers.
 209 .Pp
 210 The
 211 .Fn rman_reserve_resource
 212 function is used to reserve resources within a previously established region.
 213 It is a simplified interface to
 214 .Fn rman_reserve_resource_bound
 215 which passes 0 for the
 216 .Fa flags
 217 argument.
 218 .Pp
 219 The
 220 .Fn rman_make_alignment_flags
 221 function returns the flag mask corresponding to the desired alignment
 222 .Fa size .
 223 This should be used when calling
 224 .Fn rman_reserve_resource_bound .
 225 .Pp
 226 The
 227 .Fn rman_release_resource
 228 function releases the reserved resource
 229 .Fa r .
 230 It may attempt to merge adjacent free resources.
 231 .Pp
 232 The
 233 .Fn rman_activate_resource
 234 function marks a resource as active, by setting the
 235 .Dv RF_ACTIVE
 236 flag.
 237 If this is a time shared resource, and the caller has not yet acquired
 238 the resource, the function returns
 239 .Er EBUSY .
 240 .Pp
 241 The
 242 .Fn rman_deactivate_resource
 243 function marks a resource
 244 .Fa r
 245 as inactive, by clearing the
 246 .Dv RF_ACTIVE
 247 flag.
 248 If other consumers are waiting for this range, it will wakeup their threads.
 249 .Pp
 250 The
 251 .Fn rman_await_resource
 252 function performs an asynchronous wait for a resource
 253 .Fa r
 254 to become inactive, that is, for the
 255 .Dv RF_ACTIVE
 256 flag to be cleared.
 257 It is used to enable cooperative sharing of a resource
 258 which can only be safely used by one thread at a time.
 259 The arguments
 260 .Fa pri
 261 and
 262 .Fa timo
 263 are passed to the
 264 .Fn rman_await_resource
 265 function.
 266 .Pp
 267 The
 268 .Fn rman_get_start ,
 269 .Fn rman_get_end ,
 270 .Fn rman_get_size ,
 271 and
 272 .Fn rman_get_flags
 273 functions return the bounds, size and flags of the previously reserved
 274 resource
 275 .Fa r .
 276 .Pp
 277 The
 278 .Fn rman_set_bustag
 279 function associates a
 280 .Vt bus_space_tag_t
 281 .Fa t
 282 with the resource
 283 .Fa r .
 284 The
 285 .Fn rman_get_bustag
 286 function is used to retrieve this tag once set.
 287 .Pp
 288 The
 289 .Fn rman_set_bushandle
 290 function associates a
 291 .Vt bus_space_handle_t
 292 .Fa h
 293 with the resource
 294 .Fa r .
 295 The
 296 .Fn rman_get_bushandle
 297 function is used to retrieve this handle once set.
 298 .Pp
 299 The
 300 .Fn rman_set_virtual
 301 function is used to associate a kernel virtual address with a resource
 302 .Fa r .
 303 The
 304 .Fn rman_get_virtual
 305 function can be used to retrieve the KVA once set.
 306 .Pp
 307 The
 308 .Fn rman_set_rid
 309 function associates a resource identifier with a resource
 310 .Fa r .
 311 The
 312 .Fn rman_get_rid
 313 function retrieves this RID.
 314 .Pp
 315 The
 316 .Fn rman_get_device
 317 function returns a pointer to the device which reserved the resource
 318 .Fa r .
 319 .Pp
 320 .Sh SEE ALSO
 321 .Xr bus_activate_resource 9 ,
 322 .Xr bus_alloc_resource 9 ,
 323 .Xr bus_release_resource 9 ,
 324 .Xr bus_set_resource 9 ,
 325 .Xr mutex 9
 326 .Sh AUTHORS
 327 This manual page was written by
 328 .An Bruce M Simpson Aq bms@spc.org .