FreeBSD/Linux Kernel Cross Reference
sys/kern/bus_if.m
1 #-
2 # Copyright (c) 1998-2004 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: releng/7.4/sys/kern/bus_if.m 213196 2010-09-27 06:04:17Z avg $
27 #
28
29 #include <sys/types.h>
30 #include <sys/systm.h>
31 #include <sys/bus.h>
32
33 /**
34 * @defgroup BUS bus - KObj methods for drivers of devices with children
35 * @brief A set of methods required device drivers that support
36 * child devices.
37 * @{
38 */
39 INTERFACE bus;
40
41 #
42 # Default implementations of some methods.
43 #
44 CODE {
45 static struct resource *
46 null_alloc_resource(device_t dev, device_t child,
47 int type, int *rid, u_long start, u_long end,
48 u_long count, u_int flags)
49 {
50 return (0);
51 }
52
53 static device_t
54 null_add_child(device_t bus, int order, const char *name,
55 int unit)
56 {
57
58 panic("bus_add_child is not implemented");
59 }
60 };
61
62 /**
63 * @brief Print a description of a child device
64 *
65 * This is called from system code which prints out a description of a
66 * device. It should describe the attachment that the child has with
67 * the parent. For instance the TurboLaser bus prints which node the
68 * device is attached to. See bus_generic_print_child() for more
69 * information.
70 *
71 * @param _dev the device whose child is being printed
72 * @param _child the child device to describe
73 *
74 * @returns the number of characters output.
75 */
76 METHOD int print_child {
77 device_t _dev;
78 device_t _child;
79 } DEFAULT bus_generic_print_child;
80
81 /**
82 * @brief Print a notification about an unprobed child device.
83 *
84 * Called for each child device that did not succeed in probing for a
85 * driver.
86 *
87 * @param _dev the device whose child was being probed
88 * @param _child the child device which failed to probe
89 */
90 METHOD void probe_nomatch {
91 device_t _dev;
92 device_t _child;
93 };
94
95 /**
96 * @brief Read the value of a bus-specific attribute of a device
97 *
98 * This method, along with BUS_WRITE_IVAR() manages a bus-specific set
99 * of instance variables of a child device. The intention is that
100 * each different type of bus defines a set of appropriate instance
101 * variables (such as ports and irqs for ISA bus etc.)
102 *
103 * This information could be given to the child device as a struct but
104 * that makes it hard for a bus to add or remove variables without
105 * forcing an edit and recompile for all drivers which may not be
106 * possible for vendor supplied binary drivers.
107 *
108 * This method copies the value of an instance variable to the
109 * location specified by @p *_result.
110 *
111 * @param _dev the device whose child was being examined
112 * @param _child the child device whose instance variable is
113 * being read
114 * @param _index the instance variable to read
115 * @param _result a loction to recieve the instance variable
116 * value
117 *
118 * @retval 0 success
119 * @retval ENOENT no such instance variable is supported by @p
120 * _dev
121 */
122 METHOD int read_ivar {
123 device_t _dev;
124 device_t _child;
125 int _index;
126 uintptr_t *_result;
127 };
128
129 /**
130 * @brief Write the value of a bus-specific attribute of a device
131 *
132 * This method sets the value of an instance variable to @p _value.
133 *
134 * @param _dev the device whose child was being updated
135 * @param _child the child device whose instance variable is
136 * being written
137 * @param _index the instance variable to write
138 * @param _value the value to write to that instance variable
139 *
140 * @retval 0 success
141 * @retval ENOENT no such instance variable is supported by @p
142 * _dev
143 * @retval EINVAL the instance variable was recognised but
144 * contains a read-only value
145 */
146 METHOD int write_ivar {
147 device_t _dev;
148 device_t _child;
149 int _indx;
150 uintptr_t _value;
151 };
152
153 /**
154 * @brief Notify a bus that a child was detached
155 *
156 * Called after the child's DEVICE_DETACH() method to allow the parent
157 * to reclaim any resources allocated on behalf of the child.
158 *
159 * @param _dev the device whose child changed state
160 * @param _child the child device which changed state
161 */
162 METHOD void child_detached {
163 device_t _dev;
164 device_t _child;
165 };
166
167 /**
168 * @brief Notify a bus that a new driver was added
169 *
170 * Called when a new driver is added to the devclass which owns this
171 * bus. The generic implementation of this method attempts to probe and
172 * attach any un-matched children of the bus.
173 *
174 * @param _dev the device whose devclass had a new driver
175 * added to it
176 * @param _driver the new driver which was added
177 */
178 METHOD void driver_added {
179 device_t _dev;
180 driver_t *_driver;
181 } DEFAULT bus_generic_driver_added;
182
183 /**
184 * @brief Create a new child device
185 *
186 * For busses which use use drivers supporting DEVICE_IDENTIFY() to
187 * enumerate their devices, this method is used to create new
188 * device instances. The new device will be added after the last
189 * existing child with the same order.
190 *
191 * @param _dev the bus device which will be the parent of the
192 * new child device
193 * @param _order a value which is used to partially sort the
194 * children of @p _dev - devices created using
195 * lower values of @p _order appear first in @p
196 * _dev's list of children
197 * @param _name devclass name for new device or @c NULL if not
198 * specified
199 * @param _unit unit number for new device or @c -1 if not
200 * specified
201 */
202 METHOD device_t add_child {
203 device_t _dev;
204 u_int _order;
205 const char *_name;
206 int _unit;
207 } DEFAULT null_add_child;
208
209 /**
210 * @brief Allocate a system resource
211 *
212 * This method is called by child devices of a bus to allocate resources.
213 * The types are defined in <machine/resource.h>; the meaning of the
214 * resource-ID field varies from bus to bus (but @p *rid == 0 is always
215 * valid if the resource type is). If a resource was allocated and the
216 * caller did not use the RF_ACTIVE to specify that it should be
217 * activated immediately, the caller is responsible for calling
218 * BUS_ACTIVATE_RESOURCE() when it actually uses the resource.
219 *
220 * @param _dev the parent device of @p _child
221 * @param _child the device which is requesting an allocation
222 * @param _type the type of resource to allocate
223 * @param _rid a pointer to the resource identifier
224 * @param _start hint at the start of the resource range - pass
225 * @c 0UL for any start address
226 * @param _end hint at the end of the resource range - pass
227 * @c ~0UL for any end address
228 * @param _count hint at the size of range required - pass @c 1
229 * for any size
230 * @param _flags any extra flags to control the resource
231 * allocation - see @c RF_XXX flags in
232 * <sys/rman.h> for details
233 *
234 * @returns the resource which was allocated or @c NULL if no
235 * resource could be allocated
236 */
237 METHOD struct resource * alloc_resource {
238 device_t _dev;
239 device_t _child;
240 int _type;
241 int *_rid;
242 u_long _start;
243 u_long _end;
244 u_long _count;
245 u_int _flags;
246 } DEFAULT null_alloc_resource;
247
248 /**
249 * @brief Activate a resource
250 *
251 * Activate a resource previously allocated with
252 * BUS_ALLOC_RESOURCE(). This may for instance map a memory region
253 * into the kernel's virtual address space.
254 *
255 * @param _dev the parent device of @p _child
256 * @param _child the device which allocated the resource
257 * @param _type the type of resource
258 * @param _rid the resource identifier
259 * @param _r the resource to activate
260 */
261 METHOD int activate_resource {
262 device_t _dev;
263 device_t _child;
264 int _type;
265 int _rid;
266 struct resource *_r;
267 };
268
269 /**
270 * @brief Deactivate a resource
271 *
272 * Deactivate a resource previously allocated with
273 * BUS_ALLOC_RESOURCE(). This may for instance unmap a memory region
274 * from the kernel's virtual address space.
275 *
276 * @param _dev the parent device of @p _child
277 * @param _child the device which allocated the resource
278 * @param _type the type of resource
279 * @param _rid the resource identifier
280 * @param _r the resource to deactivate
281 */
282 METHOD int deactivate_resource {
283 device_t _dev;
284 device_t _child;
285 int _type;
286 int _rid;
287 struct resource *_r;
288 };
289
290 /**
291 * @brief Release a resource
292 *
293 * Free a resource allocated by the BUS_ALLOC_RESOURCE. The @p _rid
294 * value must be the same as the one returned by BUS_ALLOC_RESOURCE()
295 * (which is not necessarily the same as the one the client passed).
296 *
297 * @param _dev the parent device of @p _child
298 * @param _child the device which allocated the resource
299 * @param _type the type of resource
300 * @param _rid the resource identifier
301 * @param _r the resource to release
302 */
303 METHOD int release_resource {
304 device_t _dev;
305 device_t _child;
306 int _type;
307 int _rid;
308 struct resource *_res;
309 };
310
311 /**
312 * @brief Install an interrupt handler
313 *
314 * This method is used to associate an interrupt handler function with
315 * an irq resource. When the interrupt triggers, the function @p _intr
316 * will be called with the value of @p _arg as its single
317 * argument. The value returned in @p *_cookiep is used to cancel the
318 * interrupt handler - the caller should save this value to use in a
319 * future call to BUS_TEARDOWN_INTR().
320 *
321 * @param _dev the parent device of @p _child
322 * @param _child the device which allocated the resource
323 * @param _irq the resource representing the interrupt
324 * @param _flags a set of bits from enum intr_type specifying
325 * the class of interrupt
326 * @param _intr the function to call when the interrupt
327 * triggers
328 * @param _arg a value to use as the single argument in calls
329 * to @p _intr
330 * @param _cookiep a pointer to a location to recieve a cookie
331 * value that may be used to remove the interrupt
332 * handler
333 */
334 METHOD int setup_intr {
335 device_t _dev;
336 device_t _child;
337 struct resource *_irq;
338 int _flags;
339 driver_filter_t *_filter;
340 driver_intr_t *_intr;
341 void *_arg;
342 void **_cookiep;
343 };
344
345 /**
346 * @brief Uninstall an interrupt handler
347 *
348 * This method is used to disassociate an interrupt handler function
349 * with an irq resource. The value of @p _cookie must be the value
350 * returned from a previous call to BUS_SETUP_INTR().
351 *
352 * @param _dev the parent device of @p _child
353 * @param _child the device which allocated the resource
354 * @param _irq the resource representing the interrupt
355 * @param _cookie the cookie value returned when the interrupt
356 * was originally registered
357 */
358 METHOD int teardown_intr {
359 device_t _dev;
360 device_t _child;
361 struct resource *_irq;
362 void *_cookie;
363 };
364
365 /**
366 * @brief Define a resource which can be allocated with
367 * BUS_ALLOC_RESOURCE().
368 *
369 * This method is used by some busses (typically ISA) to allow a
370 * driver to describe a resource range that it would like to
371 * allocate. The resource defined by @p _type and @p _rid is defined
372 * to start at @p _start and to include @p _count indices in its
373 * range.
374 *
375 * @param _dev the parent device of @p _child
376 * @param _child the device which owns the resource
377 * @param _type the type of resource
378 * @param _rid the resource identifier
379 * @param _start the start of the resource range
380 * @param _count the size of the resource range
381 */
382 METHOD int set_resource {
383 device_t _dev;
384 device_t _child;
385 int _type;
386 int _rid;
387 u_long _start;
388 u_long _count;
389 };
390
391 /**
392 * @brief Describe a resource
393 *
394 * This method allows a driver to examine the range used for a given
395 * resource without actually allocating it.
396 *
397 * @param _dev the parent device of @p _child
398 * @param _child the device which owns the resource
399 * @param _type the type of resource
400 * @param _rid the resource identifier
401 * @param _start the address of a location to recieve the start
402 * index of the resource range
403 * @param _count the address of a location to recieve the size
404 * of the resource range
405 */
406 METHOD int get_resource {
407 device_t _dev;
408 device_t _child;
409 int _type;
410 int _rid;
411 u_long *_startp;
412 u_long *_countp;
413 };
414
415 /**
416 * @brief Delete a resource.
417 *
418 * Use this to delete a resource (possibly one previously added with
419 * BUS_SET_RESOURCE()).
420 *
421 * @param _dev the parent device of @p _child
422 * @param _child the device which owns the resource
423 * @param _type the type of resource
424 * @param _rid the resource identifier
425 */
426 METHOD void delete_resource {
427 device_t _dev;
428 device_t _child;
429 int _type;
430 int _rid;
431 };
432
433 /**
434 * @brief Return a struct resource_list.
435 *
436 * Used by drivers which use bus_generic_rl_alloc_resource() etc. to
437 * implement their resource handling. It should return the resource
438 * list of the given child device.
439 *
440 * @param _dev the parent device of @p _child
441 * @param _child the device which owns the resource list
442 */
443 METHOD struct resource_list * get_resource_list {
444 device_t _dev;
445 device_t _child;
446 } DEFAULT bus_generic_get_resource_list;
447
448 /**
449 * @brief Is the hardware described by @p _child still attached to the
450 * system?
451 *
452 * This method should return 0 if the device is not present. It
453 * should return -1 if it is present. Any errors in determining
454 * should be returned as a normal errno value. Client drivers are to
455 * assume that the device is present, even if there is an error
456 * determining if it is there. Busses are to try to avoid returning
457 * errors, but newcard will return an error if the device fails to
458 * implement this method.
459 *
460 * @param _dev the parent device of @p _child
461 * @param _child the device which is being examined
462 */
463 METHOD int child_present {
464 device_t _dev;
465 device_t _child;
466 } DEFAULT bus_generic_child_present;
467
468 /**
469 * @brief Returns the pnp info for this device.
470 *
471 * Return it as a string. If the string is insufficient for the
472 * storage, then return EOVERFLOW.
473 *
474 * @param _dev the parent device of @p _child
475 * @param _child the device which is being examined
476 * @param _buf the address of a buffer to receive the pnp
477 * string
478 * @param _buflen the size of the buffer pointed to by @p _buf
479 */
480 METHOD int child_pnpinfo_str {
481 device_t _dev;
482 device_t _child;
483 char *_buf;
484 size_t _buflen;
485 };
486
487 /**
488 * @brief Returns the location for this device.
489 *
490 * Return it as a string. If the string is insufficient for the
491 * storage, then return EOVERFLOW.
492 *
493 * @param _dev the parent device of @p _child
494 * @param _child the device which is being examined
495 * @param _buf the address of a buffer to receive the location
496 * string
497 * @param _buflen the size of the buffer pointed to by @p _buf
498 */
499 METHOD int child_location_str {
500 device_t _dev;
501 device_t _child;
502 char *_buf;
503 size_t _buflen;
504 };
505
506 /**
507 * @brief Allow drivers to request that an interrupt be bound to a specific
508 * CPU.
509 *
510 * @param _dev the parent device of @p _child
511 * @param _child the device which allocated the resource
512 * @param _irq the resource representing the interrupt
513 * @param _cpu the CPU to bind the interrupt to
514 */
515 METHOD int bind_intr {
516 device_t _dev;
517 device_t _child;
518 struct resource *_irq;
519 int _cpu;
520 } DEFAULT bus_generic_bind_intr;
521
522 /**
523 * @brief Allow (bus) drivers to specify the trigger mode and polarity
524 * of the specified interrupt.
525 *
526 * @param _dev the bus device
527 * @param _irq the interrupt number to modify
528 * @param _trig the trigger mode required
529 * @param _pol the interrupt polarity required
530 */
531 METHOD int config_intr {
532 device_t _dev;
533 int _irq;
534 enum intr_trigger _trig;
535 enum intr_polarity _pol;
536 } DEFAULT bus_generic_config_intr;
537
538 /**
539 * @brief Allow drivers to associate a description with an active
540 * interrupt handler.
541 *
542 * @param _dev the parent device of @p _child
543 * @param _child the device which allocated the resource
544 * @param _irq the resource representing the interrupt
545 * @param _cookie the cookie value returned when the interrupt
546 * was originally registered
547 * @param _descr the description to associate with the interrupt
548 */
549 METHOD int describe_intr {
550 device_t _dev;
551 device_t _child;
552 struct resource *_irq;
553 void *_cookie;
554 const char *_descr;
555 } DEFAULT bus_generic_describe_intr;
556
557 /**
558 * @brief Notify a (bus) driver about a child that the hints mechanism
559 * believes it has discovered.
560 *
561 * The bus is responsible for then adding the child in the right order
562 * and discovering other things about the child. The bus driver is
563 * free to ignore this hint, to do special things, etc. It is all up
564 * to the bus driver to interpret.
565 *
566 * This method is only called in response to the parent bus asking for
567 * hinted devices to be enumerated.
568 *
569 * @param _dev the bus device
570 * @param _dname the name of the device w/o unit numbers
571 * @param _dunit the unit number of the device
572 */
573 METHOD void hinted_child {
574 device_t _dev;
575 const char * _dname;
576 int _dunit;
577 };
578
579 /**
580 * @brief Returns bus_dma_tag_t for use w/ devices on the bus.
581 *
582 * @param _dev the parent device of @p _child
583 * @param _child the device to which the tag will belong
584 */
585 METHOD bus_dma_tag_t get_dma_tag {
586 device_t _dev;
587 device_t _child;
588 } DEFAULT bus_generic_get_dma_tag;
Cache object: 8e9c9929a0198bbf16f9ae6ca3dfc7f2
|