xref: /freebsd/share/man/man9/rman.9 (revision 85ee63c9238483c787a12547328a6b1c196264db)
15f616912SHiten Pandya.\"
25f616912SHiten Pandya.\" Copyright (c) 2003 Bruce M Simpson <bms@spc.org>
35f616912SHiten Pandya.\" All rights reserved.
45f616912SHiten Pandya.\"
55f616912SHiten Pandya.\" Redistribution and use in source and binary forms, with or without
65f616912SHiten Pandya.\" modification, are permitted provided that the following conditions
75f616912SHiten Pandya.\" are met:
85f616912SHiten Pandya.\" 1. Redistributions of source code must retain the above copyright
95f616912SHiten Pandya.\"    notice, this list of conditions and the following disclaimer.
105f616912SHiten Pandya.\" 2. Redistributions in binary form must reproduce the above copyright
115f616912SHiten Pandya.\"    notice, this list of conditions and the following disclaimer in the
125f616912SHiten Pandya.\"    documentation and/or other materials provided with the distribution.
135f616912SHiten Pandya.\"
145f616912SHiten Pandya.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
155f616912SHiten Pandya.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
165f616912SHiten Pandya.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
175f616912SHiten Pandya.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
185f616912SHiten Pandya.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
195f616912SHiten Pandya.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
205f616912SHiten Pandya.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
215f616912SHiten Pandya.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
225f616912SHiten Pandya.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
235f616912SHiten Pandya.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
245f616912SHiten Pandya.\" SUCH DAMAGE.
255f616912SHiten Pandya.\"
265f616912SHiten Pandya.\" $FreeBSD$
275f616912SHiten Pandya.\"
28bb82622cSJohn Baldwin.Dd April 29, 2011
295f616912SHiten Pandya.Dt RMAN 9
305f616912SHiten Pandya.Os
315f616912SHiten Pandya.Sh NAME
325f616912SHiten Pandya.Nm rman ,
335f616912SHiten Pandya.Nm rman_activate_resource ,
34bb82622cSJohn Baldwin.Nm rman_adjust_resource ,
355f616912SHiten Pandya.Nm rman_await_resource ,
365f616912SHiten Pandya.Nm rman_deactivate_resource ,
375f616912SHiten Pandya.Nm rman_fini ,
385f616912SHiten Pandya.Nm rman_init ,
39bb82622cSJohn Baldwin.Nm rman_init_from_resource ,
40bb82622cSJohn Baldwin.Nm rman_is_region_manager ,
415f616912SHiten Pandya.Nm rman_manage_region ,
42bb82622cSJohn Baldwin.Nm rman_first_free_region ,
43bb82622cSJohn Baldwin.Nm rman_last_free_region ,
445f616912SHiten Pandya.Nm rman_release_resource ,
455f616912SHiten Pandya.Nm rman_reserve_resource ,
465f616912SHiten Pandya.Nm rman_reserve_resource_bound ,
475f616912SHiten Pandya.Nm rman_make_alignment_flags ,
485f616912SHiten Pandya.Nm rman_get_start ,
495f616912SHiten Pandya.Nm rman_get_end ,
5011053af5SHiten Pandya.Nm rman_get_device ,
515f616912SHiten Pandya.Nm rman_get_size ,
525f616912SHiten Pandya.Nm rman_get_flags ,
535f616912SHiten Pandya.Nm rman_set_virtual ,
545f616912SHiten Pandya.Nm rman_get_virtual ,
555f616912SHiten Pandya.Nm rman_set_bustag ,
565f616912SHiten Pandya.Nm rman_get_bustag ,
575f616912SHiten Pandya.Nm rman_set_bushandle ,
585f616912SHiten Pandya.Nm rman_get_bushandle ,
595f616912SHiten Pandya.Nm rman_set_rid ,
605f616912SHiten Pandya.Nm rman_get_rid
615f616912SHiten Pandya.Nd resource management functions
625f616912SHiten Pandya.Sh SYNOPSIS
639f6985c4SWarner Losh.In sys/types.h
645f616912SHiten Pandya.In sys/rman.h
655f616912SHiten Pandya.Ft int
665f616912SHiten Pandya.Fn rman_activate_resource "struct resource *r"
675f616912SHiten Pandya.Ft int
68bb82622cSJohn Baldwin.Fn rman_adjust_resource "struct resource *r" "u_long start" "u_long end"
69bb82622cSJohn Baldwin.Ft int
705f616912SHiten Pandya.Fn rman_await_resource "struct resource *r" "int pri2" "int timo"
715f616912SHiten Pandya.Ft int
725f616912SHiten Pandya.Fn rman_deactivate_resource "struct resource *r"
735f616912SHiten Pandya.Ft int
745f616912SHiten Pandya.Fn rman_fini "struct rman *rm"
755f616912SHiten Pandya.Ft int
765f616912SHiten Pandya.Fn rman_init "struct rman *rm"
775f616912SHiten Pandya.Ft int
78bb82622cSJohn Baldwin.Fn rman_init_from_resource "struct rman *rm" "struct resource *r"
79bb82622cSJohn Baldwin.Ft int
80bb82622cSJohn Baldwin.Fn rman_is_region_manager "struct resource *r" "struct rman *rm"
81bb82622cSJohn Baldwin.Ft int
825f616912SHiten Pandya.Fn rman_manage_region "struct rman *rm" "u_long start" "u_long end"
835f616912SHiten Pandya.Ft int
84bb82622cSJohn Baldwin.Fn rman_first_free_region "struct rman *rm" "u_long *start" "u_long *end"
85bb82622cSJohn Baldwin.Ft int
86bb82622cSJohn Baldwin.Fn rman_last_free_region "struct rman *rm" "u_long *start" "u_long *end"
87bb82622cSJohn Baldwin.Ft int
885f616912SHiten Pandya.Fn rman_release_resource "struct resource *r"
893e1cee04SRuslan Ermilov.Ft "struct resource *"
903e1cee04SRuslan Ermilov.Fo rman_reserve_resource
913e1cee04SRuslan Ermilov.Fa "struct rman *rm" "u_long start" "u_long end" "u_long count"
923e1cee04SRuslan Ermilov.Fa "u_int flags" "struct device *dev"
933e1cee04SRuslan Ermilov.Fc
943e1cee04SRuslan Ermilov.Ft "struct resource *"
953e1cee04SRuslan Ermilov.Fo rman_reserve_resource_bound
963e1cee04SRuslan Ermilov.Fa "struct rman *rm" "u_long start" "u_long end" "u_long count"
973e1cee04SRuslan Ermilov.Fa "u_long bound" "u_int flags" "struct device *dev"
983e1cee04SRuslan Ermilov.Fc
995f616912SHiten Pandya.Ft uint32_t
1005f616912SHiten Pandya.Fn rman_make_alignment_flags "uint32_t size"
1015f616912SHiten Pandya.Ft u_long
1023e1cee04SRuslan Ermilov.Fn rman_get_start "struct resource *r"
1035f616912SHiten Pandya.Ft u_long
1043e1cee04SRuslan Ermilov.Fn rman_get_end "struct resource *r"
10511053af5SHiten Pandya.Ft "struct device *"
10611053af5SHiten Pandya.Fn rman_get_device "struct resource *r"
1075f616912SHiten Pandya.Ft u_long
1083e1cee04SRuslan Ermilov.Fn rman_get_size "struct resource *r"
1095f616912SHiten Pandya.Ft u_int
1103e1cee04SRuslan Ermilov.Fn rman_get_flags "struct resource *r"
1115f616912SHiten Pandya.Ft void
1123e1cee04SRuslan Ermilov.Fn rman_set_virtual "struct resource *r" "void *v"
1133e1cee04SRuslan Ermilov.Ft "void *"
1143e1cee04SRuslan Ermilov.Fn rman_get_virtual "struct resource *r"
1155f616912SHiten Pandya.Ft void
1163e1cee04SRuslan Ermilov.Fn rman_set_bustag "struct resource *r" "bus_space_tag_t t"
1175f616912SHiten Pandya.Ft bus_space_tag_t
1183e1cee04SRuslan Ermilov.Fn rman_get_bustag "struct resource *r"
1195f616912SHiten Pandya.Ft void
1203e1cee04SRuslan Ermilov.Fn rman_set_bushandle "struct resource *r" "bus_space_handle_t h"
1215f616912SHiten Pandya.Ft bus_space_handle_t
1223e1cee04SRuslan Ermilov.Fn rman_get_bushandle "struct resource *r"
1235f616912SHiten Pandya.Ft void
1243e1cee04SRuslan Ermilov.Fn rman_set_rid "struct resource *r" "int rid"
1255f616912SHiten Pandya.Ft int
1263e1cee04SRuslan Ermilov.Fn rman_get_rid "struct resource *r"
1275f616912SHiten Pandya.Sh DESCRIPTION
1285f616912SHiten PandyaThe
1295f616912SHiten Pandya.Nm
1305f616912SHiten Pandyaset of functions provides a flexible resource management abstraction.
1315f616912SHiten PandyaIt is used extensively by the bus management code.
1325f616912SHiten PandyaIt implements the abstractions of region and resource.
1335f616912SHiten PandyaA region descriptor is used to manage a region; this could be memory or
1345f616912SHiten Pandyasome other form of bus space.
1355f616912SHiten Pandya.Pp
1365f616912SHiten PandyaEach region has a set of bounds.
1375f616912SHiten PandyaWithin these bounds, allocated segments may reside.
1385f616912SHiten PandyaEach segment, termed a resource, has several properties which are
1395f616912SHiten Pandyarepresented by a 16-bit flag register, as follows.
1405f616912SHiten Pandya.Bd -literal
1415f616912SHiten Pandya#define RF_ALLOCATED    0x0001 /* resource has been reserved */
1425f616912SHiten Pandya#define RF_ACTIVE       0x0002 /* resource allocation has been activated */
1435f616912SHiten Pandya#define RF_SHAREABLE    0x0004 /* resource permits contemporaneous sharing */
1445f616912SHiten Pandya#define RF_TIMESHARE    0x0008 /* resource permits time-division sharing */
1455f616912SHiten Pandya#define RF_WANTED       0x0010 /* somebody is waiting for this resource */
1465f616912SHiten Pandya#define RF_FIRSTSHARE   0x0020 /* first in sharing list */
1475f616912SHiten Pandya#define RF_PREFETCHABLE 0x0040 /* resource is prefetchable */
1485f616912SHiten Pandya.Ed
1495f616912SHiten Pandya.Pp
1505f616912SHiten PandyaThe remainder of the flag bits are used to represent the desired alignment
1515f616912SHiten Pandyaof the resource within the region.
1525f616912SHiten Pandya.Pp
1535f616912SHiten PandyaThe
1545f616912SHiten Pandya.Fn rman_init
1555f616912SHiten Pandyafunction initializes the region descriptor, pointed to by the
1565f616912SHiten Pandya.Fa rm
1575f616912SHiten Pandyaargument, for use with the resource management functions.
158bc956811SJohn-Mark GurneyIt is required that the fields
159bc956811SJohn-Mark Gurney.Va rm_type
160bc956811SJohn-Mark Gurneyand
161bc956811SJohn-Mark Gurney.Va rm_descr
162bc956811SJohn-Mark Gurneyof
163bc956811SJohn-Mark Gurney.Vt "struct rman"
164bc956811SJohn-Mark Gurneybe set before calling
165bc956811SJohn-Mark Gurney.Fn rman_init .
166bc956811SJohn-Mark GurneyThe field
167bc956811SJohn-Mark Gurney.Va rm_type
168bc956811SJohn-Mark Gurneyshall be set to
169bc956811SJohn-Mark Gurney.Dv RMAN_ARRAY .
170bc956811SJohn-Mark GurneyThe field
171bc956811SJohn-Mark Gurney.Va rm_descr
172bc956811SJohn-Mark Gurneyshall be set to a string that describes the resource to be managed.
173bb82622cSJohn BaldwinThe
174bb82622cSJohn Baldwin.Va rm_start
175bb82622cSJohn Baldwinand
176bb82622cSJohn Baldwin.Va rm_end
177bb82622cSJohn Baldwinfields may be set to limit the range of acceptable resource addresses.
178bb82622cSJohn BaldwinIf these fields are not set,
179bb82622cSJohn Baldwin.Fn rman_init
180bb82622cSJohn Baldwinwill initialize them to allow the entire range of resource addresses.
1815f616912SHiten PandyaIt also initializes any mutexes associated with the structure.
182ebf750a9SJohn-Mark GurneyIf
183ebf750a9SJohn-Mark Gurney.Fn rman_init
184f6ac2391SJoel Dahlfails to initialize the mutex, it will return
185ebf750a9SJohn-Mark Gurney.Er ENOMEM ; otherwise it will return 0 and
186ebf750a9SJohn-Mark Gurney.Fa rm
187f6ac2391SJoel Dahlwill be initialized.
1885f616912SHiten Pandya.Pp
1895f616912SHiten PandyaThe
1905f616912SHiten Pandya.Fn rman_fini
1915f616912SHiten Pandyafunction frees any structures associated with the structure
1925f616912SHiten Pandyapointed to by the
1935f616912SHiten Pandya.Fa rm
1943e1cee04SRuslan Ermilovargument.
1953e1cee04SRuslan ErmilovIf any of the resources within the managed region have the
1965f616912SHiten Pandya.Dv RF_ALLOCATED
1975f616912SHiten Pandyaflag set, it will return
1985f616912SHiten Pandya.Er EBUSY ;
1995f616912SHiten Pandyaotherwise, any mutexes associated with the structure will be released
2005f616912SHiten Pandyaand destroyed, and the function will return 0.
2015f616912SHiten Pandya.Pp
2025f616912SHiten PandyaThe
2035f616912SHiten Pandya.Fn rman_manage_region
2045f616912SHiten Pandyafunction establishes the concept of a region which is under
2055f616912SHiten Pandya.Nm
2065f616912SHiten Pandyacontrol.
2075f616912SHiten PandyaThe
2085f616912SHiten Pandya.Fa rman
2095f616912SHiten Pandyaargument points to the region descriptor.
2103e1cee04SRuslan ErmilovThe
2113e1cee04SRuslan Ermilov.Fa start
2123e1cee04SRuslan Ermilovand
2133e1cee04SRuslan Ermilov.Fa end
2143e1cee04SRuslan Ermilovarguments specify the bounds of the region.
215ebf750a9SJohn-Mark GurneyIf successful,
216ebf750a9SJohn-Mark Gurney.Fn rman_manage_region
217ebf750a9SJohn-Mark Gurneywill return 0.
218ebf750a9SJohn-Mark GurneyIf the region overlaps with an existing region, it will return
219ebf750a9SJohn-Mark Gurney.Er EBUSY .
220bb82622cSJohn BaldwinIf any part of the region falls outside of the valid address range for
221bb82622cSJohn Baldwin.Fa rm ,
222bb82622cSJohn Baldwinit will return
223bb82622cSJohn Baldwin.Er EINVAL .
224ebf750a9SJohn-Mark Gurney.Er ENOMEM
225bb82622cSJohn Baldwinwill be returned when
226ebf750a9SJohn-Mark Gurney.Fn rman_manage_region
227ebf750a9SJohn-Mark Gurneyfailed to allocate memory for the region.
2285f616912SHiten Pandya.Pp
2295f616912SHiten PandyaThe
230bb82622cSJohn Baldwin.Fn rman_init_from_resource
231bb82622cSJohn Baldwinfunction is a wrapper routine to create a resource manager backed by an
232bb82622cSJohn Baldwinexisting resource.
233bb82622cSJohn BaldwinIt initializes
234bb82622cSJohn Baldwin.Fa rm
235bb82622cSJohn Baldwinusing
236bb82622cSJohn Baldwin.Fn rman_init
237bb82622cSJohn Baldwinand then adds a region to
238bb82622cSJohn Baldwin.Fa rm
239bb82622cSJohn Baldwincorresponding to the address range allocated to
240bb82622cSJohn Baldwin.Fa r
241bb82622cSJohn Baldwinvia
242bb82622cSJohn Baldwin.Fn rman_manage_region .
243bb82622cSJohn Baldwin.Pp
244bb82622cSJohn BaldwinThe
245bb82622cSJohn Baldwin.Fn rman_first_free_region
246bb82622cSJohn Baldwinand
247bb82622cSJohn Baldwin.Fn rman_last_free_region
248bb82622cSJohn Baldwinfunctions can be used to query a resource manager for its first
249bb82622cSJohn Baldwin.Pq or last
250bb82622cSJohn Baldwinunallocated region.
251bb82622cSJohn BaldwinIf
252bb82622cSJohn Baldwin.Fa rm
253bb82622cSJohn Baldwincontains no free region,
254bb82622cSJohn Baldwinthese functions will return
255bb82622cSJohn Baldwin.Er ENOENT .
256bb82622cSJohn BaldwinOtherwise,
257bb82622cSJohn Baldwin.Fa *start
258bb82622cSJohn Baldwinand
259bb82622cSJohn Baldwin.Fa *end
260bb82622cSJohn Baldwinare set to the bounds of the free region and zero is returned.
261bb82622cSJohn Baldwin.Pp
262bb82622cSJohn BaldwinThe
2635f616912SHiten Pandya.Fn rman_reserve_resource_bound
2645f616912SHiten Pandyafunction is where the bulk of the
2653e1cee04SRuslan Ermilov.Nm
2663e1cee04SRuslan Ermilovlogic is located.
2675f616912SHiten PandyaIt attempts to reserve a contiguous range in the specified region
2685f616912SHiten Pandya.Fa rm
2695f616912SHiten Pandyafor the use of the device
2705f616912SHiten Pandya.Fa dev .
2713e1cee04SRuslan ErmilovThe caller can specify the
2723e1cee04SRuslan Ermilov.Fa start
2733e1cee04SRuslan Ermilovand
2743e1cee04SRuslan Ermilov.Fa end
275bb82622cSJohn Baldwinof an acceptable range,
276bb82622cSJohn Baldwinas well as a boundary restriction and required aligment,
277bb82622cSJohn Baldwinand the code will attempt to find a free segment which fits.
278f3011a7cSWarner LoshThe
279f3011a7cSWarner Losh.Fa start
280f3011a7cSWarner Loshargument is the lowest acceptable starting value of the resource.
281f3011a7cSWarner LoshThe
282f3011a7cSWarner Losh.Fa end
283f3011a7cSWarner Loshargument is the highest acceptable ending value of the resource.
284f3011a7cSWarner LoshTherefore,
2854f068961SRuslan Ermilov.Fa start No + Fa count No \- 1
2864f068961SRuslan Ermilovmust be \[<=]
287f3011a7cSWarner Losh.Fa end
288f3011a7cSWarner Loshfor any allocation to happen.
289bb82622cSJohn BaldwinThe aligment requirement
290bb82622cSJohn Baldwin.Pq if any
291bb82622cSJohn Baldwinis specified in
292bb82622cSJohn Baldwin.Fa flags .
293bb82622cSJohn BaldwinThe
294bb82622cSJohn Baldwin.Fa bound
295bb82622cSJohn Baldwinargument may be set to specify a boundary restriction such that an
296bb82622cSJohn Baldwinallocated region may cross an address that is a multiple of the
297bb82622cSJohn Baldwinboundary.
298bb82622cSJohn BaldwinThe
299bb82622cSJohn Baldwin.Fa bound
300bb82622cSJohn Baldwinargument must be a power of two.
301bb82622cSJohn BaldwinIt may be set to zero to specify no boundary restriction.
3025f616912SHiten PandyaThe default behavior is to allocate an exclusive segment, unless the
3035f616912SHiten Pandya.Dv RF_SHAREABLE
3045f616912SHiten Pandyaor
3055f616912SHiten Pandya.Dv RF_TIMESHARE
3065f616912SHiten Pandyaflags are set, in which case a shared
3075f616912SHiten Pandyasegment will be allocated.
3085f616912SHiten PandyaIf this shared segment already exists, the caller has its device
3095f616912SHiten Pandyaadded to the list of consumers.
3105f616912SHiten Pandya.Pp
3115f616912SHiten PandyaThe
3125f616912SHiten Pandya.Fn rman_reserve_resource
3135f616912SHiten Pandyafunction is used to reserve resources within a previously established region.
3145f616912SHiten PandyaIt is a simplified interface to
3155f616912SHiten Pandya.Fn rman_reserve_resource_bound
3165f616912SHiten Pandyawhich passes 0 for the
317bb82622cSJohn Baldwin.Fa bound
3185f616912SHiten Pandyaargument.
3195f616912SHiten Pandya.Pp
3205f616912SHiten PandyaThe
3215f616912SHiten Pandya.Fn rman_make_alignment_flags
3225f616912SHiten Pandyafunction returns the flag mask corresponding to the desired alignment
3235f616912SHiten Pandya.Fa size .
3245f616912SHiten PandyaThis should be used when calling
3255f616912SHiten Pandya.Fn rman_reserve_resource_bound .
3265f616912SHiten Pandya.Pp
3275f616912SHiten PandyaThe
328bb82622cSJohn Baldwin.Fn rman_is_region_manager
329bb82622cSJohn Baldwinfunction returns true if the allocated resource
330bb82622cSJohn Baldwin.Fa r
331bb82622cSJohn Baldwinwas allocated from
332bb82622cSJohn Baldwin.Fa rm .
333bb82622cSJohn BaldwinOtherwise,
334bb82622cSJohn Baldwinit returns false.
335bb82622cSJohn Baldwin.Pp
336bb82622cSJohn BaldwinThe
337bb82622cSJohn Baldwin.Fn rman_adjust_resource
338bb82622cSJohn Baldwinfunction is used to adjust the reserved address range of an allocated resource
339bb82622cSJohn Baldwinto reserve
340bb82622cSJohn Baldwin.Fa start
341bb82622cSJohn Baldwinthrough
342bb82622cSJohn Baldwin.Fa end .
343bb82622cSJohn BaldwinIt can be used to grow or shrink one or both ends of the resource range.
344bb82622cSJohn BaldwinThe current implementation does not support entirely relocating the resource
345bb82622cSJohn Baldwinand will fail with
346bb82622cSJohn Baldwin.Er EINVAL
347bb82622cSJohn Baldwinif the new resource range does not overlap the old resource range.
348bb82622cSJohn BaldwinIf either end of the resource range grows and the new resource range would
349bb82622cSJohn Baldwinconflict with another allocated resource,
350bb82622cSJohn Baldwinthe function will fail with
351bb82622cSJohn Baldwin.Er EBUSY .
352bb82622cSJohn BaldwinThe
353bb82622cSJohn Baldwin.Fn rman_adjust_resource
354bb82622cSJohn Baldwinfunction does not support adjusting the resource range for shared resources
355bb82622cSJohn Baldwinand will fail such attempts with
356bb82622cSJohn Baldwin.Er EINVAL .
357bb82622cSJohn BaldwinUpon success,
358bb82622cSJohn Baldwinthe resource
359bb82622cSJohn Baldwin.Fa r
360bb82622cSJohn Baldwinwill have a start address of
361bb82622cSJohn Baldwin.Fa start
362bb82622cSJohn Baldwinand an end address of
363bb82622cSJohn Baldwin.Fa end
364bb82622cSJohn Baldwinand the function will return zero.
365bb82622cSJohn BaldwinNote that none of the constraints of the original allocation request such
366bb82622cSJohn Baldwinas alignment or boundary restrictions are checked by
367bb82622cSJohn Baldwin.Fn rman_adjust_resource .
368bb82622cSJohn BaldwinIt is the caller's responsibility to enforce any such requirements.
369bb82622cSJohn Baldwin.Pp
370bb82622cSJohn BaldwinThe
3715f616912SHiten Pandya.Fn rman_release_resource
3725f616912SHiten Pandyafunction releases the reserved resource
3735f616912SHiten Pandya.Fa r .
3745f616912SHiten PandyaIt may attempt to merge adjacent free resources.
3755f616912SHiten Pandya.Pp
3765f616912SHiten PandyaThe
3775f616912SHiten Pandya.Fn rman_activate_resource
3785f616912SHiten Pandyafunction marks a resource as active, by setting the
3795f616912SHiten Pandya.Dv RF_ACTIVE
3805f616912SHiten Pandyaflag.
3815f616912SHiten PandyaIf this is a time shared resource, and the caller has not yet acquired
3825f616912SHiten Pandyathe resource, the function returns
3835f616912SHiten Pandya.Er EBUSY .
3845f616912SHiten Pandya.Pp
3855f616912SHiten PandyaThe
3865f616912SHiten Pandya.Fn rman_deactivate_resource
3875f616912SHiten Pandyafunction marks a resource
3885f616912SHiten Pandya.Fa r
3895f616912SHiten Pandyaas inactive, by clearing the
3905f616912SHiten Pandya.Dv RF_ACTIVE
3915f616912SHiten Pandyaflag.
3925f616912SHiten PandyaIf other consumers are waiting for this range, it will wakeup their threads.
3935f616912SHiten Pandya.Pp
3945f616912SHiten PandyaThe
3955f616912SHiten Pandya.Fn rman_await_resource
3965f616912SHiten Pandyafunction performs an asynchronous wait for a resource
3975f616912SHiten Pandya.Fa r
3985f616912SHiten Pandyato become inactive, that is, for the
3995f616912SHiten Pandya.Dv RF_ACTIVE
4005f616912SHiten Pandyaflag to be cleared.
4015f616912SHiten PandyaIt is used to enable cooperative sharing of a resource
4025f616912SHiten Pandyawhich can only be safely used by one thread at a time.
4035f616912SHiten PandyaThe arguments
4045f616912SHiten Pandya.Fa pri
4055f616912SHiten Pandyaand
4065f616912SHiten Pandya.Fa timo
4075f616912SHiten Pandyaare passed to the
4085f616912SHiten Pandya.Fn rman_await_resource
4095f616912SHiten Pandyafunction.
4105f616912SHiten Pandya.Pp
4115f616912SHiten PandyaThe
4125f616912SHiten Pandya.Fn rman_get_start ,
4135f616912SHiten Pandya.Fn rman_get_end ,
4143e1cee04SRuslan Ermilov.Fn rman_get_size ,
4153e1cee04SRuslan Ermilovand
4165f616912SHiten Pandya.Fn rman_get_flags
4175f616912SHiten Pandyafunctions return the bounds, size and flags of the previously reserved
4185f616912SHiten Pandyaresource
4195f616912SHiten Pandya.Fa r .
4205f616912SHiten Pandya.Pp
4215f616912SHiten PandyaThe
4225f616912SHiten Pandya.Fn rman_set_bustag
4233e1cee04SRuslan Ermilovfunction associates a
4243e1cee04SRuslan Ermilov.Vt bus_space_tag_t
4255f616912SHiten Pandya.Fa t
4265f616912SHiten Pandyawith the resource
4275f616912SHiten Pandya.Fa r .
4285f616912SHiten PandyaThe
4295f616912SHiten Pandya.Fn rman_get_bustag
4305f616912SHiten Pandyafunction is used to retrieve this tag once set.
4315f616912SHiten Pandya.Pp
4325f616912SHiten PandyaThe
4335f616912SHiten Pandya.Fn rman_set_bushandle
4343e1cee04SRuslan Ermilovfunction associates a
4353e1cee04SRuslan Ermilov.Vt bus_space_handle_t
4365f616912SHiten Pandya.Fa h
4375f616912SHiten Pandyawith the resource
4385f616912SHiten Pandya.Fa r .
4395f616912SHiten PandyaThe
4405f616912SHiten Pandya.Fn rman_get_bushandle
4415f616912SHiten Pandyafunction is used to retrieve this handle once set.
4425f616912SHiten Pandya.Pp
4435f616912SHiten PandyaThe
4445f616912SHiten Pandya.Fn rman_set_virtual
4455f616912SHiten Pandyafunction is used to associate a kernel virtual address with a resource
4465f616912SHiten Pandya.Fa r .
4475f616912SHiten PandyaThe
4485f616912SHiten Pandya.Fn rman_get_virtual
4495f616912SHiten Pandyafunction can be used to retrieve the KVA once set.
4505f616912SHiten Pandya.Pp
4515f616912SHiten PandyaThe
4525f616912SHiten Pandya.Fn rman_set_rid
4535f616912SHiten Pandyafunction associates a resource identifier with a resource
4545f616912SHiten Pandya.Fa r .
4553e1cee04SRuslan ErmilovThe
4563e1cee04SRuslan Ermilov.Fn rman_get_rid
4573e1cee04SRuslan Ermilovfunction retrieves this RID.
4585f616912SHiten Pandya.Pp
4595f616912SHiten PandyaThe
4605f616912SHiten Pandya.Fn rman_get_device
4615f616912SHiten Pandyafunction returns a pointer to the device which reserved the resource
4625f616912SHiten Pandya.Fa r .
4635f616912SHiten Pandya.Sh SEE ALSO
4645f616912SHiten Pandya.Xr bus_activate_resource 9 ,
465*85ee63c9SJohn Baldwin.Xr bus_adjust_resource 9 ,
4665f616912SHiten Pandya.Xr bus_alloc_resource 9 ,
4675f616912SHiten Pandya.Xr bus_release_resource 9 ,
4685f616912SHiten Pandya.Xr bus_set_resource 9 ,
4695f616912SHiten Pandya.Xr mutex 9
4705f616912SHiten Pandya.Sh AUTHORS
471571dba6eSHiten PandyaThis manual page was written by
4725f616912SHiten Pandya.An Bruce M Simpson Aq bms@spc.org .
473