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_deactivate_resource ,
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 ,
52 .Nm rman_set_mapping ,
53 .Nm rman_get_mapping ,
54 .Nm rman_set_virtual ,
55 .Nm rman_get_virtual ,
58 .Nm rman_set_bushandle ,
59 .Nm rman_get_bushandle ,
62 .Nd resource management functions
67 .Fn rman_activate_resource "struct resource *r"
69 .Fn rman_adjust_resource "struct resource *r" "rman_res_t start" "rman_res_t end"
71 .Fn rman_deactivate_resource "struct resource *r"
73 .Fn rman_fini "struct rman *rm"
75 .Fn rman_init "struct rman *rm"
77 .Fn rman_init_from_resource "struct rman *rm" "struct resource *r"
79 .Fn rman_is_region_manager "struct resource *r" "struct rman *rm"
81 .Fn rman_manage_region "struct rman *rm" "rman_res_t start" "rman_res_t end"
83 .Fn rman_first_free_region "struct rman *rm" "rman_res_t *start" "rman_res_t *end"
85 .Fn rman_last_free_region "struct rman *rm" "rman_res_t *start" "rman_res_t *end"
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"
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"
99 .Fn rman_make_alignment_flags "uint32_t size"
101 .Fn rman_get_start "struct resource *r"
103 .Fn rman_get_end "struct resource *r"
104 .Ft "struct device *"
105 .Fn rman_get_device "struct resource *r"
107 .Fn rman_get_size "struct resource *r"
109 .Fn rman_get_flags "struct resource *r"
111 .Fn rman_set_mapping "struct resource *r" "struct resource_map *map"
113 .Fn rman_get_mapping "struct resource *r" "struct resource_map *map"
115 .Fn rman_set_virtual "struct resource *r" "void *v"
117 .Fn rman_get_virtual "struct resource *r"
119 .Fn rman_set_bustag "struct resource *r" "bus_space_tag_t t"
121 .Fn rman_get_bustag "struct resource *r"
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"
127 .Fn rman_set_rid "struct resource *r" "int rid"
129 .Fn rman_get_rid "struct resource *r"
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.
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.
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 */
152 Bits 15:10 of the flag register are used to represent the desired alignment
153 of the resource within the region.
157 function initializes the region descriptor, pointed to by the
159 argument, for use with the resource management functions.
160 It is required that the fields
166 be set before calling
174 shall be set to a string that describes the resource to be managed.
179 fields may be set to limit the range of acceptable resource addresses.
180 If these fields are not set,
182 will initialize them to allow the entire range of resource addresses.
183 It also initializes any mutexes associated with the structure.
186 fails to initialize the mutex, it will return
187 .Er ENOMEM ; otherwise it will return 0 and
193 function frees any structures associated with the structure
197 If any of the resources within the managed region have the
199 flag set, it will return
201 otherwise, any mutexes associated with the structure will be released
202 and destroyed, and the function will return 0.
205 .Fn rman_manage_region
206 function establishes the concept of a region which is under
211 argument points to the region descriptor.
216 arguments specify the bounds of the region.
218 .Fn rman_manage_region
220 If the region overlaps with an existing region, it will return
222 If any part of the region falls outside of the valid address range for
227 will be returned when
228 .Fn rman_manage_region
229 failed to allocate memory for the region.
232 .Fn rman_init_from_resource
233 function is a wrapper routine to create a resource manager backed by an
239 and then adds a region to
241 corresponding to the address range allocated to
244 .Fn rman_manage_region .
247 .Fn rman_first_free_region
249 .Fn rman_last_free_region
250 functions can be used to query a resource manager for its first
255 contains no free region,
256 these functions will return
262 are set to the bounds of the free region and zero is returned.
265 .Fn rman_reserve_resource_bound
266 function is where the bulk of the
269 It attempts to reserve a contiguous range in the specified region
271 for the use of the device
273 The caller can specify the
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.
282 argument is the lowest acceptable starting value of the resource.
285 argument is the highest acceptable ending value of the resource.
287 .Fa start No + Fa count No \- 1
290 for any allocation to happen.
291 The aligment requirement
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
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
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.
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
320 .Fn rman_make_alignment_flags
321 function returns the flag mask corresponding to the desired alignment
323 This should be used when calling
324 .Fn rman_reserve_resource_bound .
327 .Fn rman_is_region_manager
328 function returns true if the allocated resource
336 .Fn rman_adjust_resource
337 function is used to adjust the reserved address range of an allocated resource
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
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
352 .Fn rman_adjust_resource
353 function does not support adjusting the resource range for shared resources
354 and will fail such attempts with
359 will have a start address of
361 and an end address of
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.
370 .Fn rman_release_resource
371 function releases the reserved resource
373 It may attempt to merge adjacent free resources.
376 .Fn rman_activate_resource
377 function marks a resource as active, by setting the
380 If this is a time shared resource, and the caller has not yet acquired
381 the resource, the function returns
385 .Fn rman_deactivate_resource
386 function marks a resource
388 as inactive, by clearing the
391 If other consumers are waiting for this range, it will wakeup their threads.
399 functions return the bounds, size and flags of the previously reserved
405 function associates a
412 function is used to retrieve this tag once set.
415 .Fn rman_set_bushandle
416 function associates a
417 .Vt bus_space_handle_t
422 .Fn rman_get_bushandle
423 function is used to retrieve this handle once set.
427 function is used to associate a kernel virtual address with a resource
431 function can be used to retrieve the KVA once set.
435 function is used to associate a resource mapping with a resource
437 The mapping must cover the entire resource.
438 Setting a mapping sets the associated
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 ,
447 .Fn rman_get_virtual .
451 function can be used to retrieve the associated resource mapping once set.
455 function associates a resource identifier with a resource
459 function retrieves this RID.
463 function returns a pointer to the device which reserved the resource
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 ,
475 This manual page was written by
476 .An Bruce M Simpson Aq Mt bms@spc.org .