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 May 20, 2016
  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_deactivate_resource ,
  36 .Nm rman_fini ,
  37 .Nm rman_init ,
  38 .Nm rman_init_from_resource ,
  39 .Nm rman_is_region_manager ,
  40 .Nm rman_manage_region ,
  41 .Nm rman_first_free_region ,
  42 .Nm rman_last_free_region ,
  43 .Nm rman_release_resource ,
  44 .Nm rman_reserve_resource ,
  45 .Nm rman_reserve_resource_bound ,
  46 .Nm rman_make_alignment_flags ,
  47 .Nm rman_get_start ,
  48 .Nm rman_get_end ,
  49 .Nm rman_get_device ,
  50 .Nm rman_get_size ,
  51 .Nm rman_get_flags ,
  52 .Nm rman_set_mapping ,
  53 .Nm rman_get_mapping ,
  54 .Nm rman_set_virtual ,
  55 .Nm rman_get_virtual ,
  56 .Nm rman_set_bustag ,
  57 .Nm rman_get_bustag ,
  58 .Nm rman_set_bushandle ,
  59 .Nm rman_get_bushandle ,
  60 .Nm rman_set_rid ,
  61 .Nm rman_get_rid
  62 .Nd resource management functions
  63 .Sh SYNOPSIS
  64 .In sys/types.h
  65 .In sys/rman.h
  66 .Ft int
  67 .Fn rman_activate_resource "struct resource *r"
  68 .Ft int
  69 .Fn rman_adjust_resource "struct resource *r" "rman_res_t start" "rman_res_t end"
  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" "rman_res_t start" "rman_res_t end"
  82 .Ft int
  83 .Fn rman_first_free_region "struct rman *rm" "rman_res_t *start" "rman_res_t *end"
  84 .Ft int
  85 .Fn rman_last_free_region "struct rman *rm" "rman_res_t *start" "rman_res_t *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" "rman_res_t start" "rman_res_t end" "rman_res_t 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" "rman_res_t start" "rman_res_t end" "rman_res_t count"
  96 .Fa "rman_res_t bound" "u_int flags" "struct device *dev"
  97 .Fc
  98 .Ft uint32_t
  99 .Fn rman_make_alignment_flags "uint32_t size"
 100 .Ft rman_res_t
 101 .Fn rman_get_start "struct resource *r"
 102 .Ft rman_res_t
 103 .Fn rman_get_end "struct resource *r"
 104 .Ft "struct device *"
 105 .Fn rman_get_device "struct resource *r"
 106 .Ft rman_res_t
 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_mapping "struct resource *r" "struct resource_map *map"
 112 .Ft void
 113 .Fn rman_get_mapping "struct resource *r" "struct resource_map *map"
 114 .Ft void
 115 .Fn rman_set_virtual "struct resource *r" "void *v"
 116 .Ft "void *"
 117 .Fn rman_get_virtual "struct resource *r"
 118 .Ft void
 119 .Fn rman_set_bustag "struct resource *r" "bus_space_tag_t t"
 120 .Ft bus_space_tag_t
 121 .Fn rman_get_bustag "struct resource *r"
 122 .Ft void
 123 .Fn rman_set_bushandle "struct resource *r" "bus_space_handle_t h"
 124 .Ft bus_space_handle_t
 125 .Fn rman_get_bushandle "struct resource *r"
 126 .Ft void
 127 .Fn rman_set_rid "struct resource *r" "int rid"
 128 .Ft int
 129 .Fn rman_get_rid "struct resource *r"
 130 .Sh DESCRIPTION
 131 The
 132 .Nm
 133 set of functions provides a flexible resource management abstraction.
 134 It is used extensively by the bus management code.
 135 It implements the abstractions of region and resource.
 136 A region descriptor is used to manage a region; this could be memory or
 137 some other form of bus space.
 138 .Pp
 139 Each region has a set of bounds.
 140 Within these bounds, allocated segments may reside.
 141 Each segment, termed a resource, has several properties which are
 142 represented by a 16-bit flag register, as follows.
 143 .Bd -literal
 144 #define RF_ALLOCATED    0x0001 /* resource has been reserved */
 145 #define RF_ACTIVE       0x0002 /* resource allocation has been activated */
 146 #define RF_SHAREABLE    0x0004 /* resource permits contemporaneous sharing */
 147 #define RF_FIRSTSHARE   0x0020 /* first in sharing list */
 148 #define RF_PREFETCHABLE 0x0040 /* resource is prefetchable */
 149 #define RF_UNMAPPED     0x0100 /* don't map resource when activating */
 150 .Ed
 151 .Pp
 152 Bits 15:10  of the flag register are used to represent the desired alignment
 153 of the resource within the region.
 154 .Pp
 155 The
 156 .Fn rman_init
 157 function initializes the region descriptor, pointed to by the
 158 .Fa rm
 159 argument, for use with the resource management functions.
 160 It is required that the fields
 161 .Va rm_type
 162 and
 163 .Va rm_descr
 164 of
 165 .Vt "struct rman"
 166 be set before calling
 167 .Fn rman_init .
 168 The field
 169 .Va rm_type
 170 shall be set to
 171 .Dv RMAN_ARRAY .
 172 The field
 173 .Va rm_descr
 174 shall be set to a string that describes the resource to be managed.
 175 The
 176 .Va rm_start
 177 and
 178 .Va rm_end
 179 fields may be set to limit the range of acceptable resource addresses.
 180 If these fields are not set,
 181 .Fn rman_init
 182 will initialize them to allow the entire range of resource addresses.
 183 It also initializes any mutexes associated with the structure.
 184 If
 185 .Fn rman_init
 186 fails to initialize the mutex, it will return
 187 .Er ENOMEM ; otherwise it will return 0 and
 188 .Fa rm
 189 will be initialized.
 190 .Pp
 191 The
 192 .Fn rman_fini
 193 function frees any structures associated with the structure
 194 pointed to by the
 195 .Fa rm
 196 argument.
 197 If any of the resources within the managed region have the
 198 .Dv RF_ALLOCATED
 199 flag set, it will return
 200 .Er EBUSY ;
 201 otherwise, any mutexes associated with the structure will be released
 202 and destroyed, and the function will return 0.
 203 .Pp
 204 The
 205 .Fn rman_manage_region
 206 function establishes the concept of a region which is under
 207 .Nm
 208 control.
 209 The
 210 .Fa rman
 211 argument points to the region descriptor.
 212 The
 213 .Fa start
 214 and
 215 .Fa end
 216 arguments specify the bounds of the region.
 217 If successful,
 218 .Fn rman_manage_region
 219 will return 0.
 220 If the region overlaps with an existing region, it will return
 221 .Er EBUSY .
 222 If any part of the region falls outside of the valid address range for
 223 .Fa rm ,
 224 it will return
 225 .Er EINVAL .
 226 .Er ENOMEM
 227 will be returned when
 228 .Fn rman_manage_region
 229 failed to allocate memory for the region.
 230 .Pp
 231 The
 232 .Fn rman_init_from_resource
 233 function is a wrapper routine to create a resource manager backed by an
 234 existing resource.
 235 It initializes
 236 .Fa rm
 237 using
 238 .Fn rman_init
 239 and then adds a region to
 240 .Fa rm
 241 corresponding to the address range allocated to
 242 .Fa r
 243 via
 244 .Fn rman_manage_region .
 245 .Pp
 246 The
 247 .Fn rman_first_free_region
 248 and
 249 .Fn rman_last_free_region
 250 functions can be used to query a resource manager for its first
 251 .Pq or last
 252 unallocated region.
 253 If
 254 .Fa rm
 255 contains no free region,
 256 these functions will return
 257 .Er ENOENT .
 258 Otherwise,
 259 .Fa *start
 260 and
 261 .Fa *end
 262 are set to the bounds of the free region and zero is returned.
 263 .Pp
 264 The
 265 .Fn rman_reserve_resource_bound
 266 function is where the bulk of the
 267 .Nm
 268 logic is located.
 269 It attempts to reserve a contiguous range in the specified region
 270 .Fa rm
 271 for the use of the device
 272 .Fa dev .
 273 The caller can specify the
 274 .Fa start
 275 and
 276 .Fa end
 277 of an acceptable range,
 278 as well as a boundary restriction and required aligment,
 279 and the code will attempt to find a free segment which fits.
 280 The
 281 .Fa start
 282 argument is the lowest acceptable starting value of the resource.
 283 The
 284 .Fa end
 285 argument is the highest acceptable ending value of the resource.
 286 Therefore,
 287 .Fa start No + Fa count No \- 1
 288 must be \[<=]
 289 .Fa end
 290 for any allocation to happen.
 291 The aligment requirement
 292 .Pq if any
 293 is specified in
 294 .Fa flags .
 295 The
 296 .Fa bound
 297 argument may be set to specify a boundary restriction such that an
 298 allocated region may cross an address that is a multiple of the
 299 boundary.
 300 The
 301 .Fa bound
 302 argument must be a power of two.
 303 It may be set to zero to specify no boundary restriction.
 304 A shared segment will be allocated if the
 305 .Dv RF_SHAREABLE
 306 flag is set, otherwise an exclusive 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_get_start ,
 395 .Fn rman_get_end ,
 396 .Fn rman_get_size ,
 397 and
 398 .Fn rman_get_flags
 399 functions return the bounds, size and flags of the previously reserved
 400 resource
 401 .Fa r .
 402 .Pp
 403 The
 404 .Fn rman_set_bustag
 405 function associates a
 406 .Vt bus_space_tag_t
 407 .Fa t
 408 with the resource
 409 .Fa r .
 410 The
 411 .Fn rman_get_bustag
 412 function is used to retrieve this tag once set.
 413 .Pp
 414 The
 415 .Fn rman_set_bushandle
 416 function associates a
 417 .Vt bus_space_handle_t
 418 .Fa h
 419 with the resource
 420 .Fa r .
 421 The
 422 .Fn rman_get_bushandle
 423 function is used to retrieve this handle once set.
 424 .Pp
 425 The
 426 .Fn rman_set_virtual
 427 function is used to associate a kernel virtual address with a resource
 428 .Fa r .
 429 The
 430 .Fn rman_get_virtual
 431 function can be used to retrieve the KVA once set.
 432 .Pp
 433 The
 434 .Fn rman_set_mapping
 435 function is used to associate a resource mapping with a resource
 436 .Fa r .
 437 The mapping must cover the entire resource.
 438 Setting a mapping sets the associated
 439 .Xr bus_space 9
 440 handle and tag for
 441 .Fa r
 442 as well as the kernel virtual address if the mapping contains one.
 443 These individual values can be retrieved via
 444 .Fn rman_get_bushandle ,
 445 .Fn rman_get_bustag ,
 446 and
 447 .Fn rman_get_virtual .
 448 .Pp
 449 The
 450 .Fn rman_get_mapping
 451 function can be used to retrieve the associated resource mapping once set.
 452 .Pp
 453 The
 454 .Fn rman_set_rid
 455 function associates a resource identifier with a resource
 456 .Fa r .
 457 The
 458 .Fn rman_get_rid
 459 function retrieves this RID.
 460 .Pp
 461 The
 462 .Fn rman_get_device
 463 function returns a pointer to the device which reserved the resource
 464 .Fa r .
 465 .Sh SEE ALSO
 466 .Xr bus_activate_resource 9 ,
 467 .Xr bus_adjust_resource 9 ,
 468 .Xr bus_alloc_resource 9 ,
 469 .Xr bus_map_resource 9 ,
 470 .Xr bus_release_resource 9 ,
 471 .Xr bus_set_resource 9 ,
 472 .Xr bus_space 9 ,
 473 .Xr mutex 9
 474 .Sh AUTHORS
 475 This manual page was written by
 476 .An Bruce M Simpson Aq Mt bms@spc.org .