2 .\" Copyright (c) 2003 Bruce M Simpson <bms@spc.org>
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
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.
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
33 .Nm rman_activate_resource ,
34 .Nm rman_adjust_resource ,
35 .Nm rman_await_resource ,
36 .Nm rman_deactivate_resource ,
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 ,
53 .Nm rman_set_virtual ,
54 .Nm rman_get_virtual ,
57 .Nm rman_set_bushandle ,
58 .Nm rman_get_bushandle ,
61 .Nd resource management functions
66 .Fn rman_activate_resource "struct resource *r"
68 .Fn rman_adjust_resource "struct resource *r" "u_long start" "u_long end"
70 .Fn rman_await_resource "struct resource *r" "int pri2" "int timo"
72 .Fn rman_deactivate_resource "struct resource *r"
74 .Fn rman_fini "struct rman *rm"
76 .Fn rman_init "struct rman *rm"
78 .Fn rman_init_from_resource "struct rman *rm" "struct resource *r"
80 .Fn rman_is_region_manager "struct resource *r" "struct rman *rm"
82 .Fn rman_manage_region "struct rman *rm" "u_long start" "u_long end"
84 .Fn rman_first_free_region "struct rman *rm" "u_long *start" "u_long *end"
86 .Fn rman_last_free_region "struct rman *rm" "u_long *start" "u_long *end"
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"
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"
100 .Fn rman_make_alignment_flags "uint32_t size"
102 .Fn rman_get_start "struct resource *r"
104 .Fn rman_get_end "struct resource *r"
105 .Ft "struct device *"
106 .Fn rman_get_device "struct resource *r"
108 .Fn rman_get_size "struct resource *r"
110 .Fn rman_get_flags "struct resource *r"
112 .Fn rman_set_virtual "struct resource *r" "void *v"
114 .Fn rman_get_virtual "struct resource *r"
116 .Fn rman_set_bustag "struct resource *r" "bus_space_tag_t t"
118 .Fn rman_get_bustag "struct resource *r"
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"
124 .Fn rman_set_rid "struct resource *r" "int rid"
126 .Fn rman_get_rid "struct resource *r"
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.
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.
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 */
150 The remainder of the flag bits are used to represent the desired alignment
151 of the resource within the region.
155 function initializes the region descriptor, pointed to by the
157 argument, for use with the resource management functions.
158 It is required that the fields
164 be set before calling
172 shall be set to a string that describes the resource to be managed.
177 fields may be set to limit the range of acceptable resource addresses.
178 If these fields are not set,
180 will initialize them to allow the entire range of resource addresses.
181 It also initializes any mutexes associated with the structure.
184 fails to initialize the mutex, it will return
185 .Er ENOMEM ; otherwise it will return 0 and
191 function frees any structures associated with the structure
195 If any of the resources within the managed region have the
197 flag set, it will return
199 otherwise, any mutexes associated with the structure will be released
200 and destroyed, and the function will return 0.
203 .Fn rman_manage_region
204 function establishes the concept of a region which is under
209 argument points to the region descriptor.
214 arguments specify the bounds of the region.
216 .Fn rman_manage_region
218 If the region overlaps with an existing region, it will return
220 If any part of the region falls outside of the valid address range for
225 will be returned when
226 .Fn rman_manage_region
227 failed to allocate memory for the region.
230 .Fn rman_init_from_resource
231 function is a wrapper routine to create a resource manager backed by an
237 and then adds a region to
239 corresponding to the address range allocated to
242 .Fn rman_manage_region .
245 .Fn rman_first_free_region
247 .Fn rman_last_free_region
248 functions can be used to query a resource manager for its first
253 contains no free region,
254 these functions will return
260 are set to the bounds of the free region and zero is returned.
263 .Fn rman_reserve_resource_bound
264 function is where the bulk of the
267 It attempts to reserve a contiguous range in the specified region
269 for the use of the device
271 The caller can specify the
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.
280 argument is the lowest acceptable starting value of the resource.
283 argument is the highest acceptable ending value of the resource.
285 .Fa start No + Fa count No \- 1
288 for any allocation to happen.
289 The aligment requirement
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
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
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.
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
321 .Fn rman_make_alignment_flags
322 function returns the flag mask corresponding to the desired alignment
324 This should be used when calling
325 .Fn rman_reserve_resource_bound .
328 .Fn rman_is_region_manager
329 function returns true if the allocated resource
337 .Fn rman_adjust_resource
338 function is used to adjust the reserved address range of an allocated resource
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
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
353 .Fn rman_adjust_resource
354 function does not support adjusting the resource range for shared resources
355 and will fail such attempts with
360 will have a start address of
362 and an end address of
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.
371 .Fn rman_release_resource
372 function releases the reserved resource
374 It may attempt to merge adjacent free resources.
377 .Fn rman_activate_resource
378 function marks a resource as active, by setting the
381 If this is a time shared resource, and the caller has not yet acquired
382 the resource, the function returns
386 .Fn rman_deactivate_resource
387 function marks a resource
389 as inactive, by clearing the
392 If other consumers are waiting for this range, it will wakeup their threads.
395 .Fn rman_await_resource
396 function performs an asynchronous wait for a resource
398 to become inactive, that is, for the
401 It is used to enable cooperative sharing of a resource
402 which can only be safely used by one thread at a time.
408 .Fn rman_await_resource
417 functions return the bounds, size and flags of the previously reserved
423 function associates a
430 function is used to retrieve this tag once set.
433 .Fn rman_set_bushandle
434 function associates a
435 .Vt bus_space_handle_t
440 .Fn rman_get_bushandle
441 function is used to retrieve this handle once set.
445 function is used to associate a kernel virtual address with a resource
449 function can be used to retrieve the KVA once set.
453 function associates a resource identifier with a resource
457 function retrieves this RID.
461 function returns a pointer to the device which reserved the resource
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 ,
471 This manual page was written by
472 .An Bruce M Simpson Aq bms@spc.org .