| blob | dd19627683bd4cede696238138a8f636b0467d90 |
1 .\" -*- nroff -*-
2 .\"
3 .\" Copyright (c) 2000 Alexander Langer
4 .\"
5 .\" All rights reserved.
6 .\"
7 .\" This program is free software.
8 .\"
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
11 .\" are met:
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in the
16 .\" documentation and/or other materials provided with the distribution.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
19 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
20 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
21 .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
22 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
23 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
24 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
25 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
26 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
27 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
28 .\"
29 .\" $FreeBSD$
30 .\"
31 .Dd May 18, 2000
32 .Dt BUS_ALLOC_RESOURCE 9
33 .Os
34 .Sh NAME
35 .Nm bus_alloc_resource ,
36 .Nm bus_alloc_resource_any
37 .Nd allocate resources from a parent bus
38 .Sh SYNOPSIS
39 .In sys/param.h
40 .In sys/bus.h
41 .Pp
42 .In machine/bus.h
43 .In sys/rman.h
44 .In machine/resource.h
45 .Ft struct resource *
46 .Fn bus_alloc_resource "device_t dev" "int type" "int *rid" "u_long start" "u_long end" "u_long count" "u_int flags"
47 .Ft struct resource *
48 .Fn bus_alloc_resource_any "device_t dev" "int type" "int *rid" "u_int flags"
49 .Sh DESCRIPTION
50 This is an easy interface to the resource-management functions.
51 It hides the indirection through the parent's method table.
52 This function generally should be called in attach, but (except in some
53 rare cases) never earlier.
54 .Pp
55 The
56 .Fn bus_alloc_resource_any
57 function is a convenience wrapper for
58 .Fn bus_alloc_resource .
59 It sets the values for
60 .Fa start ,
61 .Fa end ,
62 and
63 .Fa count
64 to the default resource (see description of
65 .Fa start
66 below).
67 .Pp
68 The arguments are as follows:
69 .Bl -item
70 .It
71 .Fa dev
72 is the device that requests ownership of the resource.
73 Before allocation, the resource is owned by the parent bus.
74 .It
75 .Fa type
76 is the type of resource you want to allocate.
77 It is one of:
78 .Bl -tag -width SYS_RES_MEMORY
79 .It Dv SYS_RES_IRQ
80 for IRQs
81 .It Dv SYS_RES_DRQ
82 for ISA DMA lines
83 .It Dv SYS_RES_IOPORT
84 for I/O ports
85 .It Dv SYS_RES_MEMORY
86 for I/O memory
87 .El
88 .It
89 .Fa rid
90 points to a bus specific handle that identifies the resource being allocated.
91 For ISA this is an index into an array of resources that have been setup
92 for this device by either the PnP mechanism, or via the hints mechanism.
93 For PCCARD, this is an index into the array of resources described by the PC Card's
94 CIS entry.
95 For PCI, the offset into pci config space which has the BAR to use to access
96 the resource.
97 The bus methods are free to change the RIDs that they are given as a parameter.
98 You must not depend on the value you gave it earlier.
99 .It
100 .Fa start
101 and
102 .Fa end
103 are the start/end addresses of the resource.
104 If you specify values of 0ul for
105 .Fa start
106 and ~0ul for
107 .Fa end
108 and 1 for
109 .Fa count ,
110 the default values for the bus are calculated.
111 .It
112 .Fa count
113 is the size of the resource.
114 For example, the size of an I/O port is usually 1 byte (but some devices
115 override this).
116 If you specified the default values for
117 .Fa start
118 and
119 .Fa end ,
120 then the default value of the bus is used if
121 .Fa count
122 is smaller than the default value and
123 .Fa count
124 is used, if it is bigger than the default value.
125 .It
126 .Fa flags
127 sets the flags for the resource.
128 You can set one or more of these flags:
129 .Bl -tag -width RF_SHAREABLE
130 .It Dv RF_ALLOCATED
131 resource has been reserved.
132 The resource still needs to be activated with
133 .Xr bus_activate_resource 9 .
134 .It Dv RF_ACTIVE
135 activate resource atomically.
136 .It Dv RF_SHAREABLE
137 resource permits contemporaneous sharing.
138 It should always be set unless you know that the resource cannot be shared.
139 It is the bus driver's task to filter out the flag if the bus does not
140 support sharing.
141 For example,
142 .Xr pccard 4
143 cannot share IRQs while
144 .Xr cardbus 4
145 can.
146 .It Dv RF_TIMESHARE
147 resource permits time-division sharing.
148 .El
149 .El
150 .Sh RETURN VALUES
151 A pointer to
152 .Va struct resource
153 is returned on success, a null pointer otherwise.
154 .Sh EXAMPLES
155 This is some example code that allocates a 32 byte I/O port range and an IRQ.
156 The values of
157 .Va portid
158 and
159 .Va irqid
160 should be saved in the softc of the device after these calls.
161 .Bd -literal
162 struct resource *portres, *irqres;
163 int portid, irqid;
165 portid = 0;
166 irqid = 0;
167 portres = bus_alloc_resource(dev, SYS_RES_IOPORT, &portid,
168 0ul, ~0ul, 32, RF_ACTIVE);
169 irqres = bus_alloc_resource_any(dev, SYS_RES_IRQ, &irqid,
170 RF_ACTIVE | RF_SHAREABLE);
171 .Ed
172 .Sh SEE ALSO
173 .Xr bus_activate_resource 9 ,
174 .Xr bus_release_resource 9 ,
175 .Xr device 9 ,
176 .Xr driver 9
177 .Sh AUTHORS
178 .An -nosplit
179 This manual page was written by
180 .An Alexander Langer Aq alex@big.endian.de
181 with parts by
182 .An Warner Losh Aq imp@FreeBSD.org .