2 # Copyright (c) 2013 SRI International
3 # Copyright (c) 1998-2004 Doug Rabson
6 # Redistribution and use in source and binary forms, with or without
7 # modification, are permitted provided that the following conditions
9 # 1. Redistributions of source code must retain the above copyright
10 # notice, this list of conditions and the following disclaimer.
11 # 2. Redistributions in binary form must reproduce the above copyright
12 # notice, this list of conditions and the following disclaimer in the
13 # documentation and/or other materials provided with the distribution.
15 # THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
16 # ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17 # IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18 # ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
19 # FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20 # DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
21 # OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
22 # HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23 # LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24 # OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30 #include <sys/types.h>
31 #include <sys/systm.h>
35 * @defgroup FST_IC fdt_ic - KObj methods for interrupt controllers
36 * @brief A set of methods required device drivers that are interrupt
37 * controllers. Derived from sys/kern/bus_if.m.
43 * @brief Allocate an interrupt resource
45 * This method is called by child devices of an interrupt controller to
46 * allocate an interrup. The meaning of the resource-ID field varies
47 * from bus to bus and is opaque to the interrupt controller. If a
48 * resource was allocated and the caller did not use the RF_ACTIVE
49 * to specify that it should be activated immediately, the caller is
50 * responsible for calling FDT_IC_ACTIVATE_INTR() when it actually uses
53 * @param _dev the interrupt-parent device of @p _child
54 * @param _child the device which is requesting an allocation
55 * @param _rid a pointer to the resource identifier
56 * @param _irq interrupt source to allocate
57 * @param _flags any extra flags to control the resource
58 * allocation - see @c RF_XXX flags in
59 * <sys/rman.h> for details
61 * @returns the interrupt which was allocated or @c NULL if no
62 * resource could be allocated
64 METHOD struct resource * alloc_intr {
73 * @brief Activate an interrupt
75 * Activate an interrupt previously allocated with FDT_IC_ALLOC_INTR().
77 * @param _dev the parent device of @p _child
78 * @param _r interrupt to activate
80 METHOD int activate_intr {
86 * @brief Deactivate an interrupt
88 * Deactivate a resource previously allocated with FDT_IC_ALLOC_INTR().
90 * @param _dev the parent device of @p _child
91 * @param _r the interrupt to deactivate
93 METHOD int deactivate_intr {
99 * @brief Release an interrupt
101 * Free an interupt allocated by the FDT_IC_ALLOC_INTR.
103 * @param _dev the parent device of @p _child
104 * @param _r the resource to release
106 METHOD int release_intr {
108 struct resource *_res;
112 * @brief Install an interrupt handler
114 * This method is used to associate an interrupt handler function with
115 * an irq resource. When the interrupt triggers, the function @p _intr
116 * will be called with the value of @p _arg as its single
117 * argument. The value returned in @p *_cookiep is used to cancel the
118 * interrupt handler - the caller should save this value to use in a
119 * future call to FDT_IC_TEARDOWN_INTR().
121 * @param _dev the interrupt-parent device of @p _child
122 * @param _child the device which allocated the resource
123 * @param _irq the resource representing the interrupt
124 * @param _flags a set of bits from enum intr_type specifying
125 * the class of interrupt
126 * @param _intr the function to call when the interrupt
128 * @param _arg a value to use as the single argument in calls
130 * @param _cookiep a pointer to a location to recieve a cookie
131 * value that may be used to remove the interrupt
134 METHOD int setup_intr {
137 struct resource *_irq;
139 driver_filter_t *_filter;
140 driver_intr_t *_intr;
146 * @brief Uninstall an interrupt handler
148 * This method is used to disassociate an interrupt handler function
149 * with an irq resource. The value of @p _cookie must be the value
150 * returned from a previous call to FDT_IC_SETUP_INTR().
152 * @param _dev the interrupt-parent device of @p _child
153 * @param _child the device which allocated the resource
154 * @param _irq the resource representing the interrupt
155 * @param _cookie the cookie value returned when the interrupt
156 * was originally registered
158 METHOD int teardown_intr {
161 struct resource *_irq;
166 * @brief Allow drivers to request that an interrupt be bound to a specific
169 * @param _dev the interrupt-parent device of @p _child
170 * @param _child the device which allocated the resource
171 * @param _irq the resource representing the interrupt
172 * @param _cpu the CPU to bind the interrupt to
174 METHOD int bind_intr {
177 struct resource *_irq;
182 * @brief Allow drivers to specify the trigger mode and polarity
183 * of the specified interrupt.
185 * @param _dev the interrupt-parent device
186 * @param _irq the interrupt number to modify
187 * @param _trig the trigger mode required
188 * @param _pol the interrupt polarity required
190 METHOD int config_intr {
193 enum intr_trigger _trig;
194 enum intr_polarity _pol;
198 * @brief Allow drivers to associate a description with an active
201 * @param _dev the interrupt-parent device of @p _child
202 * @param _child the device which allocated the resource
203 * @param _irq the resource representing the interrupt
204 * @param _cookie the cookie value returned when the interrupt
205 * was originally registered
206 * @param _descr the description to associate with the interrupt
208 METHOD int describe_intr {
211 struct resource *_irq;
217 * @brief Notify an ic that specified child's IRQ should be remapped.
219 * @param _dev the interrupt-parent device
220 * @param _child the child device
221 * @param _irq the irq number
223 METHOD int remap_intr {
230 * @brief Enable an IPI source.
232 * @param _dev the interrupt controller
233 * @param _tid the thread ID (relative to the interrupt controller)
235 * @param _ipi_irq hardware IRQ to send IPIs to
237 METHOD void setup_ipi {
244 * @brief Send an IPI to the specified thread.
246 * @param _dev the interrupt controller
247 * @param _tid the thread ID (relative to the interrupt controller)
250 METHOD void send_ipi {
256 * @brief Clear the IPI on the specfied thread. Only call with the
257 * local hardware thread or interrupts may be lost!
259 * @param _dev the interrupt controller
260 * @param _tid the thread ID (relative to the interrupt controller)
261 * to clear the IPI on
263 METHOD void clear_ipi {