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 April 29, 2011
  29 .Dt RMAN 9
  30 .Os
  31 .Sh NAME
  32 .Nm rman ,
  33 .Nm rman_activate_resource ,
  34 .Nm rman_adjust_resource ,
  35 .Nm rman_await_resource ,
  36 .Nm rman_deactivate_resource ,
  37 .Nm rman_fini ,
  38 .Nm rman_init ,
  39 .Nm rman_init_from_resource ,
  40 .Nm rman_is_region_manager ,
  41 .Nm rman_manage_region ,
  42 .Nm rman_first_free_region ,
  43 .Nm rman_last_free_region ,
  44 .Nm rman_release_resource ,
  45 .Nm rman_reserve_resource ,
  46 .Nm rman_reserve_resource_bound ,
  47 .Nm rman_make_alignment_flags ,
  48 .Nm rman_get_start ,
  49 .Nm rman_get_end ,
  50 .Nm rman_get_device ,
  51 .Nm rman_get_size ,
  52 .Nm rman_get_flags ,
  53 .Nm rman_set_virtual ,
  54 .Nm rman_get_virtual ,
  55 .Nm rman_set_bustag ,
  56 .Nm rman_get_bustag ,
  57 .Nm rman_set_bushandle ,
  58 .Nm rman_get_bushandle ,
  59 .Nm rman_set_rid ,
  60 .Nm rman_get_rid
  61 .Nd resource management functions
  62 .Sh SYNOPSIS
  63 .In sys/rman.h
  64 .Ft int
  65 .Fn rman_activate_resource "struct resource *r"
  66 .Ft int
  67 .Fn rman_adjust_resource "struct resource *r" "u_long start" "u_long end"
  68 .Ft int
  69 .Fn rman_await_resource "struct resource *r" "int pri2" "int timo"
  70 .Ft int
  71 .Fn rman_deactivate_resource "struct resource *r"
  72 .Ft int
  73 .Fn rman_fini "struct rman *rm"
  74 .Ft int
  75 .Fn rman_init "struct rman *rm"
  76 .Ft int
  77 .Fn rman_init_from_resource "struct rman *rm" "struct resource *r"
  78 .Ft int
  79 .Fn rman_is_region_manager "struct resource *r" "struct rman *rm"
  80 .Ft int
  81 .Fn rman_manage_region "struct rman *rm" "u_long start" "u_long end"
  82 .Ft int
  83 .Fn rman_first_free_region "struct rman *rm" "u_long *start" "u_long *end"
  84 .Ft int
  85 .Fn rman_last_free_region "struct rman *rm" "u_long *start" "u_long *end"
  86 .Ft int
  87 .Fn rman_release_resource "struct resource *r"
  88 .Ft "struct resource *"
  89 .Fo rman_reserve_resource
  90 .Fa "struct rman *rm" "u_long start" "u_long end" "u_long count"
  91 .Fa "u_int flags" "struct device *dev"
  92 .Fc
  93 .Ft "struct resource *"
  94 .Fo rman_reserve_resource_bound
  95 .Fa "struct rman *rm" "u_long start" "u_long end" "u_long count"
  96 .Fa "u_long bound" "u_int flags" "struct device *dev"
  97 .Fc
  98 .Ft uint32_t
  99 .Fn rman_make_alignment_flags "uint32_t size"
 100 .Ft u_long
 101 .Fn rman_get_start "struct resource *r"
 102 .Ft u_long
 103 .Fn rman_get_end "struct resource *r"
 104 .Ft "struct device *"
 105 .Fn rman_get_device "struct resource *r"
 106 .Ft u_long
 107 .Fn rman_get_size "struct resource *r"
 108 .Ft u_int
 109 .Fn rman_get_flags "struct resource *r"
 110 .Ft void
 111 .Fn rman_set_virtual "struct resource *r" "void *v"
 112 .Ft "void *"
 113 .Fn rman_get_virtual "struct resource *r"
 114 .Ft void
 115 .Fn rman_set_bustag "struct resource *r" "bus_space_tag_t t"
 116 .Ft bus_space_tag_t
 117 .Fn rman_get_bustag "struct resource *r"
 118 .Ft void
 119 .Fn rman_set_bushandle "struct resource *r" "bus_space_handle_t h"
 120 .Ft bus_space_handle_t
 121 .Fn rman_get_bushandle "struct resource *r"
 122 .Ft void
 123 .Fn rman_set_rid "struct resource *r" "int rid"
 124 .Ft int
 125 .Fn rman_get_rid "struct resource *r"
 126 .Sh DESCRIPTION
 127 The
 128 .Nm
 129 set of functions provides a flexible resource management abstraction.
 130 It is used extensively by the bus management code.
 131 It implements the abstractions of region and resource.
 132 A region descriptor is used to manage a region; this could be memory or
 133 some other form of bus space.
 134 .Pp
 135 Each region has a set of bounds.
 136 Within these bounds, allocated segments may reside.
 137 Each segment, termed a resource, has several properties which are
 138 represented by a 16-bit flag register, as follows.
 139 .Bd -literal
 140 #define RF_ALLOCATED    0x0001 /* resource has been reserved */
 141 #define RF_ACTIVE       0x0002 /* resource allocation has been activated */
 142 #define RF_SHAREABLE    0x0004 /* resource permits contemporaneous sharing */
 143 #define RF_TIMESHARE    0x0008 /* resource permits time-division sharing */
 144 #define RF_WANTED       0x0010 /* somebody is waiting for this resource */
 145 #define RF_FIRSTSHARE   0x0020 /* first in sharing list */
 146 #define RF_PREFETCHABLE 0x0040 /* resource is prefetchable */
 147 .Ed
 148 .Pp
 149 The remainder of the flag bits are used to represent the desired alignment
 150 of the resource within the region.
 151 .Pp
 152 The
 153 .Fn rman_init
 154 function initializes the region descriptor, pointed to by the
 155 .Fa rm
 156 argument, for use with the resource management functions.
 157 It is required that the fields
 158 .Va rm_type
 159 and
 160 .Va rm_descr
 161 of
 162 .Vt "struct rman"
 163 be set before calling
 164 .Fn rman_init .
 165 The field
 166 .Va rm_type
 167 shall be set to
 168 .Dv RMAN_ARRAY .
 169 The field
 170 .Va rm_descr
 171 shall be set to a string that describes the resource to be managed.
 172 The
 173 .Va rm_start
 174 and
 175 .Va rm_end
 176 fields may be set to limit the range of acceptable resource addresses.
 177 If these fields are not set,
 178 .Fn rman_init
 179 will initialize them to allow the entire range of resource addresses.
 180 It also initializes any mutexes associated with the structure.
 181 If
 182 .Fn rman_init
 183 fails to initalize the mutex, it will return
 184 .Er ENOMEM ; otherwise it will return 0 and
 185 .Fa rm
 186 will be initalized.
 187 .Pp
 188 The
 189 .Fn rman_fini
 190 function frees any structures associated with the structure
 191 pointed to by the
 192 .Fa rm
 193 argument.
 194 If any of the resources within the managed region have the
 195 .Dv RF_ALLOCATED
 196 flag set, it will return
 197 .Er EBUSY ;
 198 otherwise, any mutexes associated with the structure will be released
 199 and destroyed, and the function will return 0.
 200 .Pp
 201 The
 202 .Fn rman_manage_region
 203 function establishes the concept of a region which is under
 204 .Nm
 205 control.
 206 The
 207 .Fa rman
 208 argument points to the region descriptor.
 209 The
 210 .Fa start
 211 and
 212 .Fa end
 213 arguments specify the bounds of the region.
 214 If successful,
 215 .Fn rman_manage_region
 216 will return 0.
 217 If the region overlaps with an existing region, it will return
 218 .Er EBUSY .
 219 If any part of the region falls outside of the valid address range for
 220 .Fa rm ,
 221 it will return
 222 .Er EINVAL .
 223 .Er ENOMEM
 224 will be returned when
 225 .Fn rman_manage_region
 226 failed to allocate memory for the region.
 227 .Pp
 228 The
 229 .Fn rman_init_from_resource
 230 function is a wrapper routine to create a resource manager backed by an
 231 existing resource.
 232 It initializes
 233 .Fa rm
 234 using
 235 .Fn rman_init
 236 and then adds a region to
 237 .Fa rm
 238 corresponding to the address range allocated to
 239 .Fa r
 240 via
 241 .Fn rman_manage_region .
 242 .Pp
 243 The
 244 .Fn rman_first_free_region
 245 and
 246 .Fn rman_last_free_region
 247 functions can be used to query a resource manager for its first
 248 .Pq or last
 249 unallocated region.
 250 If
 251 .Fa rm
 252 contains no free region,
 253 these functions will return
 254 .Er ENOENT .
 255 Otherwise,
 256 .Fa *start
 257 and
 258 .Fa *end
 259 are set to the bounds of the free region and zero is returned.
 260 .Pp
 261 The
 262 .Fn rman_reserve_resource_bound
 263 function is where the bulk of the
 264 .Nm
 265 logic is located.
 266 It attempts to reserve a contiguous range in the specified region
 267 .Fa rm
 268 for the use of the device
 269 .Fa dev .
 270 The caller can specify the
 271 .Fa start
 272 and
 273 .Fa end
 274 of an acceptable range,
 275 as well as a boundary restriction and required aligment,
 276 and the code will attempt to find a free segment which fits.
 277 The
 278 .Fa start
 279 argument is the lowest acceptable starting value of the resource.
 280 The
 281 .Fa end
 282 argument is the highest acceptable ending value of the resource.
 283 Therefore,
 284 .Fa start No + Fa count No \- 1
 285 must be \[<=]
 286 .Fa end
 287 for any allocation to happen.
 288 The aligment requirement
 289 .Pq if any
 290 is specified in
 291 .Fa flags .
 292 The
 293 .Fa bound
 294 argument may be set to specify a boundary restriction such that an
 295 allocated region may cross an address that is a multiple of the
 296 boundary.
 297 The
 298 .Fa bound
 299 argument must be a power of two.
 300 It may be set to zero to specify no boundary restriction.
 301 The default behavior is to allocate an exclusive segment, unless the
 302 .Dv RF_SHAREABLE
 303 or
 304 .Dv RF_TIMESHARE
 305 flags are set, in which case a shared
 306 segment will be allocated.
 307 If this shared segment already exists, the caller has its device
 308 added to the list of consumers.
 309 .Pp
 310 The
 311 .Fn rman_reserve_resource
 312 function is used to reserve resources within a previously established region.
 313 It is a simplified interface to
 314 .Fn rman_reserve_resource_bound
 315 which passes 0 for the
 316 .Fa bound
 317 argument.
 318 .Pp
 319 The
 320 .Fn rman_make_alignment_flags
 321 function returns the flag mask corresponding to the desired alignment
 322 .Fa size .
 323 This should be used when calling
 324 .Fn rman_reserve_resource_bound .
 325 .Pp
 326 The
 327 .Fn rman_is_region_manager
 328 function returns true if the allocated resource
 329 .Fa r
 330 was allocated from
 331 .Fa rm .
 332 Otherwise,
 333 it returns false.
 334 .Pp
 335 The
 336 .Fn rman_adjust_resource
 337 function is used to adjust the reserved address range of an allocated resource
 338 to reserve
 339 .Fa start
 340 through
 341 .Fa end .
 342 It can be used to grow or shrink one or both ends of the resource range.
 343 The current implementation does not support entirely relocating the resource
 344 and will fail with
 345 .Er EINVAL
 346 if the new resource range does not overlap the old resource range.
 347 If either end of the resource range grows and the new resource range would
 348 conflict with another allocated resource,
 349 the function will fail with
 350 .Er EBUSY .
 351 The
 352 .Fn rman_adjust_resource
 353 function does not support adjusting the resource range for shared resources
 354 and will fail such attempts with
 355 .Er EINVAL .
 356 Upon success,
 357 the resource
 358 .Fa r
 359 will have a start address of
 360 .Fa start
 361 and an end address of
 362 .Fa end
 363 and the function will return zero.
 364 Note that none of the constraints of the original allocation request such
 365 as alignment or boundary restrictions are checked by
 366 .Fn rman_adjust_resource .
 367 It is the caller's responsibility to enforce any such requirements.
 368 .Pp
 369 The
 370 .Fn rman_release_resource
 371 function releases the reserved resource
 372 .Fa r .
 373 It may attempt to merge adjacent free resources.
 374 .Pp
 375 The
 376 .Fn rman_activate_resource
 377 function marks a resource as active, by setting the
 378 .Dv RF_ACTIVE
 379 flag.
 380 If this is a time shared resource, and the caller has not yet acquired
 381 the resource, the function returns
 382 .Er EBUSY .
 383 .Pp
 384 The
 385 .Fn rman_deactivate_resource
 386 function marks a resource
 387 .Fa r
 388 as inactive, by clearing the
 389 .Dv RF_ACTIVE
 390 flag.
 391 If other consumers are waiting for this range, it will wakeup their threads.
 392 .Pp
 393 The
 394 .Fn rman_await_resource
 395 function performs an asynchronous wait for a resource
 396 .Fa r
 397 to become inactive, that is, for the
 398 .Dv RF_ACTIVE
 399 flag to be cleared.
 400 It is used to enable cooperative sharing of a resource
 401 which can only be safely used by one thread at a time.
 402 The arguments
 403 .Fa pri
 404 and
 405 .Fa timo
 406 are passed to the
 407 .Fn rman_await_resource
 408 function.
 409 .Pp
 410 The
 411 .Fn rman_get_start ,
 412 .Fn rman_get_end ,
 413 .Fn rman_get_size ,
 414 and
 415 .Fn rman_get_flags
 416 functions return the bounds, size and flags of the previously reserved
 417 resource
 418 .Fa r .
 419 .Pp
 420 The
 421 .Fn rman_set_bustag
 422 function associates a
 423 .Vt bus_space_tag_t
 424 .Fa t
 425 with the resource
 426 .Fa r .
 427 The
 428 .Fn rman_get_bustag
 429 function is used to retrieve this tag once set.
 430 .Pp
 431 The
 432 .Fn rman_set_bushandle
 433 function associates a
 434 .Vt bus_space_handle_t
 435 .Fa h
 436 with the resource
 437 .Fa r .
 438 The
 439 .Fn rman_get_bushandle
 440 function is used to retrieve this handle once set.
 441 .Pp
 442 The
 443 .Fn rman_set_virtual
 444 function is used to associate a kernel virtual address with a resource
 445 .Fa r .
 446 The
 447 .Fn rman_get_virtual
 448 function can be used to retrieve the KVA once set.
 449 .Pp
 450 The
 451 .Fn rman_set_rid
 452 function associates a resource identifier with a resource
 453 .Fa r .
 454 The
 455 .Fn rman_get_rid
 456 function retrieves this RID.
 457 .Pp
 458 The
 459 .Fn rman_get_device
 460 function returns a pointer to the device which reserved the resource
 461 .Fa r .
 462 .Sh SEE ALSO
 463 .Xr bus_activate_resource 9 ,
 464 .Xr bus_adjust_resource 9 ,
 465 .Xr bus_alloc_resource 9 ,
 466 .Xr bus_release_resource 9 ,
 467 .Xr bus_set_resource 9 ,
 468 .Xr mutex 9
 469 .Sh AUTHORS
 470 This manual page was written by
 471 .An Bruce M Simpson Aq bms@spc.org .