rman.9: Comment out documentation for rman_await_resource().
[dragonfly.git] / share / man / man9 / rman.9
CommitLineData
96bce568 1.\"
9cca02b8
HP
2.\" Copyright (c) 2004 The DragonFly Project. All rights reserved.
3.\"
4.\" This code is derived from software contributed to The DragonFly Project
5.\" by Hiten Pandya <hmp@backplane.com>.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\"
11.\" 1. Redistributions of source code must retain the above copyright
12.\" notice, this list of conditions and the following disclaimer.
13.\" 2. Redistributions in binary form must reproduce the above copyright
14.\" notice, this list of conditions and the following disclaimer in
15.\" the documentation and/or other materials provided with the
16.\" distribution.
17.\" 3. Neither the name of The DragonFly Project nor the names of its
18.\" contributors may be used to endorse or promote products derived
19.\" from this software without specific, prior written permission.
20.\"
21.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
24.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
25.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
26.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
27.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
28.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
29.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
30.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
31.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32.\" SUCH DAMAGE.
33.\"
96bce568
HP
34.\" Copyright (c) 2003 Bruce M Simpson <bms@spc.org>
35.\" All rights reserved.
36.\"
37.\" Redistribution and use in source and binary forms, with or without
38.\" modification, are permitted provided that the following conditions
39.\" are met:
40.\" 1. Redistributions of source code must retain the above copyright
41.\" notice, this list of conditions and the following disclaimer.
42.\" 2. Redistributions in binary form must reproduce the above copyright
43.\" notice, this list of conditions and the following disclaimer in the
44.\" documentation and/or other materials provided with the distribution.
45.\"
46.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
47.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
48.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
49.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
50.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
51.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
52.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
53.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
54.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
55.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
56.\" SUCH DAMAGE.
57.\"
58.\" $FreeBSD: src/share/man/man9/rman.9,v 1.2 2003/05/30 21:13:32 ru Exp $
01d6ccad 59.\" $DragonFly: src/share/man/man9/rman.9,v 1.4 2006/10/27 22:39:05 swildner Exp $
96bce568
HP
60.\"
61.Dd May 12, 2003
62.Dt RMAN 9
63.Os
64.Sh NAME
65.Nm rman ,
66.Nm rman_activate_resource ,
577cd717 67.\".Nm rman_await_resource ,
96bce568
HP
68.Nm rman_deactivate_resource ,
69.Nm rman_fini ,
70.Nm rman_init ,
71.Nm rman_manage_region ,
72.Nm rman_release_resource ,
73.Nm rman_reserve_resource ,
74.\".Nm rman_reserve_resource_bound ,
75.Nm rman_make_alignment_flags ,
76.Nm rman_get_start ,
77.Nm rman_get_end ,
78.Nm rman_get_device ,
79.Nm rman_get_size ,
80.Nm rman_get_flags ,
81.Nm rman_set_virtual ,
82.Nm rman_get_virtual ,
83.Nm rman_set_bustag ,
84.Nm rman_get_bustag ,
85.Nm rman_set_bushandle ,
86.Nm rman_get_bushandle ,
87.\".Nm rman_set_rid ,
88.\".Nm rman_get_rid
89.Nd resource management functions
90.Sh SYNOPSIS
91.In sys/param.h
92.In sys/rman.h
93.Ft int
94.Fn rman_activate_resource "struct resource *r"
577cd717
SW
95.\".Ft int
96.\".Fn rman_await_resource "struct resource *r" "int pri2" "int timo"
96bce568
HP
97.Ft int
98.Fn rman_deactivate_resource "struct resource *r"
99.Ft int
100.Fn rman_fini "struct rman *rm"
101.Ft int
102.Fn rman_init "struct rman *rm"
103.Ft int
104.Fn rman_manage_region "struct rman *rm" "u_long start" "u_long end"
105.Ft int
106.Fn rman_release_resource "struct resource *r"
107.Ft "struct resource *"
108.Fo rman_reserve_resource
109.Fa "struct rman *rm" "u_long start" "u_long end" "u_long count"
110.Fa "u_int flags" "struct device *dev"
111.Fc
112.\".Ft "struct resource *"
113.\".Fo rman_reserve_resource_bound
114.\".Fa "struct rman *rm" "u_long start" "u_long end" "u_long count"
115.\".Fa "u_long bound" "u_int flags" "struct device *dev"
116.\".Fc
117.Ft uint32_t
118.Fn rman_make_alignment_flags "uint32_t size"
119.Pp
120.Ft u_long
121.Fn rman_get_start "struct resource *r"
122.Ft u_long
123.Fn rman_get_end "struct resource *r"
124.Ft "struct device *"
125.Fn rman_get_device "struct resource *r"
126.Ft u_long
127.Fn rman_get_size "struct resource *r"
128.Ft u_int
129.Fn rman_get_flags "struct resource *r"
130.Ft void
131.Fn rman_set_virtual "struct resource *r" "void *v"
132.Ft "void *"
133.Fn rman_get_virtual "struct resource *r"
134.Ft void
135.Fn rman_set_bustag "struct resource *r" "bus_space_tag_t t"
136.Ft bus_space_tag_t
137.Fn rman_get_bustag "struct resource *r"
138.Ft void
139.Fn rman_set_bushandle "struct resource *r" "bus_space_handle_t h"
140.Ft bus_space_handle_t
141.Fn rman_get_bushandle "struct resource *r"
142.\".Ft void
143.\".Fn rman_set_rid "struct resource *r" "int rid"
144.\".Ft int
145.\".Fn rman_get_rid "struct resource *r"
146.Sh DESCRIPTION
147The
148.Nm
149set of functions provides a flexible resource management abstraction,
150they are used extensively by the bus management code.
151It implements the abstractions of region and resource.
152A region descriptor is used to manage a region; this could be memory or
153some other form of bus space.
154.Pp
155Each region has a set of bounds.
156Within these bounds, allocated segments may reside.
157Each segment, termed a resource, has several properties which are
158represented by a 16-bit flag register, as follows.
159.Bd -literal
160#define RF_ALLOCATED 0x0001 /* resource has been reserved */
161#define RF_ACTIVE 0x0002 /* resource allocation has been activated */
162#define RF_SHAREABLE 0x0004 /* resource permits contemporaneous sharing */
163#define RF_TIMESHARE 0x0008 /* resource permits time-division sharing */
164#define RF_WANTED 0x0010 /* somebody is waiting for this resource */
165#define RF_FIRSTSHARE 0x0020 /* first in sharing list */
166#define RF_PREFETCHABLE 0x0040 /* resource is prefetchable */
167.Ed
168.Pp
169The remainder of the flag bits are used to represent the desired alignment
170of the resource within the region.
171.Pp
172The
173.Fn rman_init
174function initializes the region descriptor, pointed to by the
175.Fa rm
176argument, for use with the resource management functions.
177It also initializes any mutexes associated with the structure.
178.Pp
179The
180.Fn rman_fini
181function frees any structures associated with the structure
182pointed to by the
183.Fa rm
184argument.
185If any of the resources within the managed region have the
186.Dv RF_ALLOCATED
187flag set, it will return
188.Er EBUSY ;
189otherwise, any mutexes associated with the structure will be released
190and destroyed, and the function will return 0.
191.Pp
192The
193.Fn rman_manage_region
194function establishes the concept of a region which is under
195.Nm
196control.
197The
198.Fa rman
199argument points to the region descriptor.
200The
201.Fa start
202and
203.Fa end
204arguments specify the bounds of the region.
205.Pp
206.Em NOTE :
207This interface is not robust against programming errors which
208add multiple copies of the same region.
209.\".Pp
210.\"The
211.\".Fn rman_reserve_resource_bound
212.\"function is where the bulk of the
213.\".Nm
214.\"logic is located.
215.\"It attempts to reserve a contiguous range in the specified region
216.\".Fa rm
217.\"for the use of the device
218.\".Fa dev .
219.\"The caller can specify the
220.\".Fa start
221.\"and
222.\".Fa end
223.\"of an acceptable range, as well as
224.\"alignment, and the code will attempt to find a free segment which fits.
225.\"The default behavior is to allocate an exclusive segment, unless the
226.\".Dv RF_SHAREABLE
227.\"or
228.\".Dv RF_TIMESHARE
229.\"flags are set, in which case a shared
230.\"segment will be allocated.
231.\"If this shared segment already exists, the caller has its device
232.\"added to the list of consumers.
233.Pp
234The
235.Fn rman_reserve_resource
236function is used to reserve resources within a previously established region.
01d6ccad
SW
237.\"It is a simplified interface to
238.\".Fn rman_reserve_resource_bound
239.\"which passes 0 for the
240.\".Fa flags
241.\"argument.
96bce568
HP
242.Pp
243The
244.Fn rman_make_alignment_flags
245function returns the flag mask corresponding to the desired alignment
246.Fa size .
01d6ccad
SW
247.\"This should be used when calling
248.\".Fn rman_reserve_resource_bound .
96bce568
HP
249.Pp
250The
251.Fn rman_release_resource
252function releases the reserved resource
253.Fa r .
254It may attempt to merge adjacent free resources.
255.Pp
256The
257.Fn rman_activate_resource
258function marks a resource as active, by setting the
259.Dv RF_ACTIVE
260flag.
261If this is a time shared resource, and the caller has not yet acquired
262the resource, the function returns
263.Er EBUSY .
264.Pp
265The
266.Fn rman_deactivate_resource
267function marks a resource
268.Fa r
269as inactive, by clearing the
270.Dv RF_ACTIVE
271flag.
272If other consumers are waiting for this range, it will wakeup their threads.
273.Pp
577cd717
SW
274.\"The
275.\".Fn rman_await_resource
276.\"function performs an asynchronous wait for a resource
277.\".Fa r
278.\"to become inactive, that is, for the
279.\".Dv RF_ACTIVE
280.\"flag to be cleared.
281.\"It is used to enable cooperative sharing of a resource
282.\"which can only be safely used by one thread at a time.
283.\"The arguments
284.\".Fa pri
285.\"and
286.\".Fa timo
287.\"are passed to the
288.\".Fn rman_await_resource
289.\"function.
290.\".Pp
96bce568
HP
291The
292.Fn rman_get_start ,
293.Fn rman_get_end ,
294.Fn rman_get_size ,
295and
296.Fn rman_get_flags
297functions return the bounds, size and flags of the previously reserved
298resource
299.Fa r .
300.Pp
301The
302.Fn rman_set_bustag
303function associates a
304.Vt bus_space_tag_t
305.Fa t
306with the resource
307.Fa r .
308The
309.Fn rman_get_bustag
310function is used to retrieve this tag once set.
311.Pp
312The
313.Fn rman_set_bushandle
314function associates a
315.Vt bus_space_handle_t
316.Fa h
317with the resource
318.Fa r .
319The
320.Fn rman_get_bushandle
321function is used to retrieve this handle once set.
322.Pp
323The
324.Fn rman_set_virtual
325function is used to associate a kernel virtual address with a resource
326.Fa r .
327The
328.Fn rman_get_virtual
329function can be used to retrieve the KVA once set.
330.\".Pp
331.\"The
332.\".Fn rman_set_rid
333.\"function associates a resource identifier with a resource
334.\".Fa r .
335.\"The
336.\".Fn rman_get_rid
337.\"function retrieves this RID.
338.Pp
339The
340.Fn rman_get_device
341function returns a pointer to the device which reserved the resource
342.Fa r .
96bce568
HP
343.Sh SEE ALSO
344.\".Xr bus_activate_resource 9 ,
345.Xr bus_alloc_resource 9
346.Xr bus_release_resource 9 ,
347.\".Xr bus_set_resource 9 ,
348.Sh AUTHORS
349.An -nosplit
350This manual page was written by
351.An Bruce M Simpson Aq bms@spc.org ,
352later revised by
353.An Hiten Pandya Aq hmp@backplane.com .