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