Commit | Line | Data |
---|---|---|
984263bc MD |
1 | # |
2 | # Copyright (c) 1998 Doug Rabson | |
3 | # All rights reserved. | |
4 | # | |
5 | # Redistribution and use in source and binary forms, with or without | |
6 | # modification, are permitted provided that the following conditions | |
7 | # are met: | |
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. | |
13 | # | |
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 | |
24 | # SUCH DAMAGE. | |
25 | # | |
26 | # $FreeBSD: src/sys/kern/bus_if.m,v 1.16 1999/10/12 21:35:50 dfr Exp $ | |
27 | # | |
28 | ||
80eff43d JR |
29 | #include <sys/bus.h> |
30 | ||
984263bc MD |
31 | INTERFACE bus; |
32 | ||
33 | # | |
34 | # Default implementations of some methods. | |
35 | # | |
36 | CODE { | |
37 | static struct resource * | |
38 | null_alloc_resource(device_t dev, device_t child, | |
39 | int type, int *rid, | |
40 | u_long start, u_long end, | |
4f7fe8c7 | 41 | u_long count, u_int flags, int cpuid) |
984263bc MD |
42 | { |
43 | return 0; | |
44 | } | |
45 | }; | |
46 | ||
47 | # | |
48 | # This is called from system code which prints out a description of a | |
49 | # device. It should describe the attachment that the child has with | |
db825041 | 50 | # the parent. See bus_generic_print_child.9 for more information. |
984263bc MD |
51 | # This method returns the number of characters output. |
52 | # | |
53 | METHOD int print_child { | |
54 | device_t dev; | |
55 | device_t child; | |
e126caf1 | 56 | } DEFAULT bus_generic_print_child; |
984263bc MD |
57 | |
58 | # | |
59 | # Called for each child device that | |
60 | # did not succeed in probing for a | |
61 | # driver. | |
62 | # | |
63 | METHOD void probe_nomatch { | |
64 | device_t dev; | |
65 | device_t child; | |
66 | }; | |
67 | ||
68 | # | |
69 | # These two methods manage a bus specific set of instance variables of | |
70 | # a child device. The intention is that each different type of bus | |
71 | # defines a set of appropriate instance variables (such as ports and | |
72 | # irqs for ISA bus etc.) | |
73 | # | |
74 | # This information could be given to the child device as a struct but | |
75 | # that makes it hard for a bus to add or remove variables without | |
76 | # forcing an edit and recompile for all drivers which may not be | |
77 | # possible for vendor supplied binary drivers. | |
78 | ||
79 | # | |
80 | # Read an instance variable. Return 0 on success. | |
81 | # | |
82 | METHOD int read_ivar { | |
83 | device_t dev; | |
84 | device_t child; | |
85 | int index; | |
86 | uintptr_t *result; | |
87 | }; | |
88 | ||
89 | # | |
90 | # Write an instance variable. Return 0 on success. | |
91 | # | |
92 | METHOD int write_ivar { | |
93 | device_t dev; | |
94 | device_t child; | |
95 | int index; | |
96 | uintptr_t value; | |
97 | }; | |
98 | ||
99 | # | |
100 | # Called after the child's DEVICE_DETACH method to allow the parent | |
101 | # to reclaim any resources allocated on behalf of the child. | |
102 | # | |
103 | METHOD void child_detached { | |
104 | device_t dev; | |
105 | device_t child; | |
106 | }; | |
107 | ||
108 | # | |
109 | # Called when a new driver is added to the devclass which owns this | |
110 | # bus. The generic implementation of this method attempts to probe and | |
111 | # attach any un-matched children of the bus. | |
112 | # | |
113 | METHOD void driver_added { | |
114 | device_t dev; | |
115 | driver_t *driver; | |
116 | } DEFAULT bus_generic_driver_added; | |
117 | ||
118 | # | |
0319c0c8 | 119 | # For busses which use drivers supporting DEVICE_IDENTIFY to |
984263bc MD |
120 | # enumerate their devices, these methods are used to create new |
121 | # device instances. If place is non-NULL, the new device will be | |
122 | # added after the last existing child with the same order. | |
123 | # | |
2581072f MD |
124 | # bus is an entity which may iterate up through the bus heirarchy |
125 | # while parent is the parent device under which the child should be | |
126 | # added. | |
127 | # | |
984263bc | 128 | METHOD device_t add_child { |
2581072f MD |
129 | device_t bus; |
130 | device_t parent; | |
984263bc MD |
131 | int order; |
132 | const char *name; | |
133 | int unit; | |
134 | }; | |
135 | ||
136 | # | |
137 | # Allocate a system resource attached to `dev' on behalf of `child'. | |
1f7ab7c9 | 138 | # The types are defined in <sys/bus_resource.h>; the meaning of the |
984263bc MD |
139 | # resource-ID field varies from bus to bus (but *rid == 0 is always |
140 | # valid if the resource type is). start and end reflect the allowable | |
141 | # range, and should be passed as `0UL' and `~0UL', respectively, if | |
142 | # the client has no range restriction. count is the number of consecutive | |
143 | # indices in the resource required. flags is a set of sharing flags | |
144 | # as defined in <sys/rman.h>. | |
145 | # | |
146 | # Returns a resource or a null pointer on failure. The caller is | |
147 | # responsible for calling rman_activate_resource() when it actually | |
148 | # uses the resource. | |
149 | # | |
150 | METHOD struct resource * alloc_resource { | |
151 | device_t dev; | |
152 | device_t child; | |
153 | int type; | |
154 | int *rid; | |
155 | u_long start; | |
156 | u_long end; | |
157 | u_long count; | |
158 | u_int flags; | |
4f7fe8c7 | 159 | int cpuid; |
984263bc MD |
160 | } DEFAULT null_alloc_resource; |
161 | ||
162 | METHOD int activate_resource { | |
163 | device_t dev; | |
164 | device_t child; | |
165 | int type; | |
166 | int rid; | |
167 | struct resource *r; | |
168 | }; | |
169 | ||
170 | METHOD int deactivate_resource { | |
171 | device_t dev; | |
172 | device_t child; | |
173 | int type; | |
174 | int rid; | |
175 | struct resource *r; | |
176 | }; | |
177 | ||
178 | # | |
179 | # Free a resource allocated by the preceding method. The `rid' value | |
180 | # must be the same as the one returned by BUS_ALLOC_RESOURCE (which | |
181 | # is not necessarily the same as the one the client passed). | |
182 | # | |
183 | METHOD int release_resource { | |
184 | device_t dev; | |
185 | device_t child; | |
186 | int type; | |
187 | int rid; | |
188 | struct resource *res; | |
189 | }; | |
190 | ||
191 | METHOD int setup_intr { | |
192 | device_t dev; | |
193 | device_t child; | |
194 | struct resource *irq; | |
195 | int flags; | |
196 | driver_intr_t *intr; | |
197 | void *arg; | |
198 | void **cookiep; | |
e9cb6d99 | 199 | lwkt_serialize_t serializer; |
0e6f0e28 | 200 | const char *desc; |
984263bc MD |
201 | }; |
202 | ||
203 | METHOD int teardown_intr { | |
204 | device_t dev; | |
205 | device_t child; | |
206 | struct resource *irq; | |
207 | void *cookie; | |
208 | }; | |
209 | ||
67a2436e MD |
210 | # Enable or disable an interrupt. The device is generally expected to do |
211 | # the physical enablement and disablement. The bus code must flag the | |
212 | # condition so it does not call the handler from a scheduled interrupt thread, | |
213 | # since the hard interrupt might be disabled after the interrupt thread | |
214 | # has been scheduled but before it runs. | |
215 | # | |
e9cb6d99 MD |
216 | # The disable function returns an indication as to whether the handler |
217 | # is currently running (i.e. the disablement is racing the execution of | |
218 | # the interrupt handler). 0 is returned if it isn't, non-zero if it is. | |
219 | # | |
220 | # The disablement function does NOT interlock against a running handler, it | |
221 | # simply prevents future handler calls from being made. | |
222 | # | |
67a2436e MD |
223 | METHOD void enable_intr { |
224 | device_t dev; | |
225 | device_t child; | |
226 | void *cookie; | |
227 | } DEFAULT bus_generic_enable_intr; | |
228 | ||
e9cb6d99 | 229 | METHOD int disable_intr { |
67a2436e MD |
230 | device_t dev; |
231 | device_t child; | |
232 | void *cookie; | |
233 | } DEFAULT bus_generic_disable_intr; | |
234 | ||
984263bc MD |
235 | # |
236 | # Set the range used for a particular resource. Return EINVAL if | |
237 | # the type or rid are out of range. | |
238 | # | |
239 | METHOD int set_resource { | |
240 | device_t dev; | |
241 | device_t child; | |
242 | int type; | |
243 | int rid; | |
244 | u_long start; | |
245 | u_long count; | |
b47b3275 | 246 | int cpuid; |
984263bc MD |
247 | }; |
248 | ||
249 | # | |
250 | # Get the range for a resource. Return ENOENT if the type or rid are | |
251 | # out of range or have not been set. | |
252 | # | |
253 | METHOD int get_resource { | |
254 | device_t dev; | |
255 | device_t child; | |
256 | int type; | |
257 | int rid; | |
258 | u_long *startp; | |
259 | u_long *countp; | |
260 | }; | |
261 | ||
262 | # | |
263 | # Delete a resource. | |
264 | # | |
265 | METHOD void delete_resource { | |
266 | device_t dev; | |
267 | device_t child; | |
268 | int type; | |
269 | int rid; | |
270 | }; | |
22457186 | 271 | |
e126caf1 MD |
272 | # |
273 | # Return a struct resource_list. | |
274 | # | |
275 | METHOD struct resource_list * get_resource_list { | |
276 | device_t _dev; | |
277 | device_t _child; | |
278 | } DEFAULT bus_generic_get_resource_list; | |
279 | ||
22457186 JS |
280 | # |
281 | # Is the hardware described by _child still attached to the system? | |
282 | # | |
283 | # This method should return 0 if the device is not present. It should | |
284 | # return -1 if it is present. Any errors in determining should be | |
285 | # returned as a normal errno value. Client drivers are to assume that | |
286 | # the device is present, even if there is an error determining if it is | |
287 | # there. Busses are to try to avoid returning errors, but newcard will return | |
288 | # an error if the device fails to implement this method. | |
289 | # | |
290 | METHOD int child_present { | |
291 | device_t _dev; | |
292 | device_t _child; | |
293 | } DEFAULT bus_generic_child_present; | |
294 | ||
295 | # | |
296 | # Returns the pnp info for this device. Return it as a string. If the | |
297 | # string is insufficient for the storage, then return EOVERFLOW. | |
298 | # | |
299 | METHOD int child_pnpinfo_str { | |
300 | device_t _dev; | |
301 | device_t _child; | |
302 | char *_buf; | |
303 | size_t _buflen; | |
304 | }; | |
305 | ||
306 | # | |
307 | # Returns the location for this device. Return it as a string. If the | |
308 | # string is insufficient for the storage, then return EOVERFLOW. | |
309 | # | |
310 | METHOD int child_location_str { | |
311 | device_t _dev; | |
312 | device_t _child; | |
313 | char *_buf; | |
314 | size_t _buflen; | |
315 | }; | |
e126caf1 MD |
316 | |
317 | # | |
318 | # Allow (bus) drivers to specify the trigger mode and polarity of the | |
319 | # specified interrupt. | |
320 | # | |
321 | METHOD int config_intr { | |
322 | device_t _dev; | |
05065648 | 323 | device_t _child; |
e126caf1 MD |
324 | int _irq; |
325 | enum intr_trigger _trig; | |
326 | enum intr_polarity _pol; | |
327 | } DEFAULT bus_generic_config_intr; | |
328 | ||
9bddf981 FT |
329 | /** |
330 | * @brief Returns bus_dma_tag_t for use w/ devices on the bus. | |
331 | * | |
332 | * @param _dev the parent device of @p _child | |
333 | * @param _child the device to which the tag will belong | |
334 | */ | |
335 | METHOD bus_dma_tag_t get_dma_tag { | |
336 | device_t _dev; | |
337 | device_t _child; | |
338 | } DEFAULT bus_generic_get_dma_tag; |