1#- 2# Copyright (c) 2013 SRI International 3# Copyright (c) 1998-2004 Doug Rabson 4# All rights reserved. 5# 6# Redistribution and use in source and binary forms, with or without 7# modification, are permitted provided that the following conditions 8# are met: 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. 14# 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 25# SUCH DAMAGE. 26# 27# $FreeBSD$ 28# 29 30#include <sys/types.h> 31#include <sys/systm.h> 32#include <sys/bus.h> 33 34/** 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. 38 * @{ 39 */ 40INTERFACE fdt_ic; 41 42/** 43 * @brief Allocate an interrupt resource 44 * 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 51 * the interupt. 52 * 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 60 * 61 * @returns the interrupt which was allocated or @c NULL if no 62 * resource could be allocated 63 */ 64METHOD struct resource * alloc_intr { 65 device_t _dev; 66 device_t _child; 67 int *_rid; 68 u_long _irq; 69 u_int _flags; 70}; 71 72/** 73 * @brief Activate an interrupt 74 * 75 * Activate an interrupt previously allocated with FDT_IC_ALLOC_INTR(). 76 * 77 * @param _dev the parent device of @p _child 78 * @param _r interrupt to activate 79 */ 80METHOD int activate_intr { 81 device_t _dev; 82 struct resource *_r; 83}; 84 85/** 86 * @brief Deactivate an interrupt 87 * 88 * Deactivate a resource previously allocated with FDT_IC_ALLOC_INTR(). 89 * 90 * @param _dev the parent device of @p _child 91 * @param _r the interrupt to deactivate 92 */ 93METHOD int deactivate_intr { 94 device_t _dev; 95 struct resource *_r; 96}; 97 98/** 99 * @brief Release an interrupt 100 * 101 * Free an interupt allocated by the FDT_IC_ALLOC_INTR. 102 * 103 * @param _dev the parent device of @p _child 104 * @param _r the resource to release 105 */ 106METHOD int release_intr { 107 device_t _dev; 108 struct resource *_res; 109}; 110 111/** 112 * @brief Install an interrupt handler 113 * 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(). 120 * 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 127 * triggers 128 * @param _arg a value to use as the single argument in calls 129 * to @p _intr 130 * @param _cookiep a pointer to a location to recieve a cookie 131 * value that may be used to remove the interrupt 132 * handler 133 */ 134METHOD int setup_intr { 135 device_t _dev; 136 device_t _child; 137 struct resource *_irq; 138 int _flags; 139 driver_filter_t *_filter; 140 driver_intr_t *_intr; 141 void *_arg; 142 void **_cookiep; 143}; 144 145/** 146 * @brief Uninstall an interrupt handler 147 * 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(). 151 * 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 157 */ 158METHOD int teardown_intr { 159 device_t _dev; 160 device_t _child; 161 struct resource *_irq; 162 void *_cookie; 163}; 164 165/** 166 * @brief Allow drivers to request that an interrupt be bound to a specific 167 * CPU. 168 * 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 173 */ 174METHOD int bind_intr { 175 device_t _dev; 176 device_t _child; 177 struct resource *_irq; 178 int _cpu; 179}; 180 181/** 182 * @brief Allow drivers to specify the trigger mode and polarity 183 * of the specified interrupt. 184 * 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 189 */ 190METHOD int config_intr { 191 device_t _dev; 192 int _irq; 193 enum intr_trigger _trig; 194 enum intr_polarity _pol; 195}; 196 197/** 198 * @brief Allow drivers to associate a description with an active 199 * interrupt handler. 200 * 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 207 */ 208METHOD int describe_intr { 209 device_t _dev; 210 device_t _child; 211 struct resource *_irq; 212 void *_cookie; 213 const char *_descr; 214}; 215 216/** 217 * @brief Notify an ic that specified child's IRQ should be remapped. 218 * 219 * @param _dev the interrupt-parent device 220 * @param _child the child device 221 * @param _irq the irq number 222 */ 223METHOD int remap_intr { 224 device_t _dev; 225 device_t _child; 226 u_int _irq; 227}; 228 229/** 230 * @brief Enable an IPI source. 231 * 232 * @param _dev the interrupt controller 233 * @param _tid the thread ID (relative to the interrupt controller) 234 * to enable IPIs for 235 * @param _ipi_irq hardware IRQ to send IPIs to 236 */ 237METHOD void setup_ipi { 238 device_t _dev; 239 u_int _tid; 240 u_int _irq; 241}; 242 243/** 244 * @brief Send an IPI to the specified thread. 245 * 246 * @param _dev the interrupt controller 247 * @param _tid the thread ID (relative to the interrupt controller) 248 * to send IPIs to 249 */ 250METHOD void send_ipi { 251 device_t _dev; 252 u_int _tid; 253}; 254 255/** 256 * @brief Clear the IPI on the specfied thread. Only call with the 257 * local hardware thread or interrupts may be lost! 258 * 259 * @param _dev the interrupt controller 260 * @param _tid the thread ID (relative to the interrupt controller) 261 * to clear the IPI on 262 */ 263METHOD void clear_ipi { 264 device_t _dev; 265 u_int _tid; 266}; 267