1 .\" Copyright (c) 2000 Jeroen Ruigrok van der Werven
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
25 .\" $FreeBSD: src/share/man/man9/BUS_SETUP_INTR.9,v 1.20 2007/03/01 14:33:29 ru Exp $
26 .\" $DragonFly: src/share/man/man9/BUS_SETUP_INTR.9,v 1.5 2007/04/08 07:05:25 swildner Exp $
34 .Nm BUS_TEARDOWN_INTR ,
36 .Nd create, attach and teardown an interrupt handler
42 .Fa "device_t dev" "device_t child" "struct resource *irq" "int flags"
43 .Fa "driver_intr_t *intr" "void *arg" "void **cookiep"
44 .Fa "lwkt_serialize_t serializer"
48 .Fa "device_t dev" "struct resource *r" "int flags" "driver_intr_t handler"
49 .Fa "void *arg" "void **cookiep" "lwkt_serialize_t serializer"
53 .Fa "device_t dev" "device_t child" "struct resource *irq" "void *cookie"
56 .Fn bus_teardown_intr "device_t dev" "struct resource *r" "void *cookie"
61 will create and attach an interrupt handler to an interrupt
62 previously allocated by the resource manager's
63 .Xr BUS_ALLOC_RESOURCE 9
66 will be called with the value
72 argument is a pointer to a
76 will write a cookie for the parent bus' use to if it is successful in
77 establishing an interrupt.
78 Driver writers may assume that this cookie will be non-zero.
79 The nexus driver will write 0 on failure to
86 and tell the interrupt handlers about certain
87 device driver characteristics and are typically either
93 is specified the kernel is free to call the interrupt handler without
96 is also sometimes specified and allows the
97 interrupt handler to be directly called from the context of the thread
98 being interrupted, but is not recommended for most drivers.
99 Other interrupt flags exist for special purposes.
103 is non-NULL the interrupt handler will be called with the serializer held.
104 The serializer replaces the obsolete SPL calls that are no longer relevant on
106 Driver code can obtain the same serializer to interlock against
107 the driver interrupt.
108 The serializer also has enablement and disablement
109 features which mainline driver code can use to avoid races between interrupt
110 disablement and delayed interrupts executing from the device's interrupt
113 The interrupt handler will be detached by
114 .Fn BUS_TEARDOWN_INTR .
117 needs to be passed to
118 .Fn BUS_TEARDOWN_INTR
119 in order to tear down the correct interrupt handler.
121 .Fn BUS_TEARDOWN_INTR
122 returns, it is guaranteed that the interrupt function is not active and
123 will no longer be called.
125 The lowercase versions
128 .Fn bus_teardown_intr
129 are convenience functions to make it easier for drivers to use the
130 resource-management functions.
131 All they do is hide indirection through the parent's method table,
132 making for slightly less wordy code.
134 Zero is returned on success,
135 otherwise an appropriate error is returned.
142 This manual page was written by
143 .An Jeroen Ruigrok van der Werven
144 .Aq asmodai@FreeBSD.org
145 based on the manual pages for
151 .Aq dfr@FreeBSD.org .