sys/dev/fdt/fdt_ic_if.m

   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  */
  40 INTERFACE 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  */
  64 METHOD 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  */
  80 METHOD 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  */
  93 METHOD 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  */
 106 METHOD 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  */
 134 METHOD 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  */
 158 METHOD 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  */
 174 METHOD 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  */
 190 METHOD 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  */
 208 METHOD 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  */
 223 METHOD 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  */
 237 METHOD 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  */
 250 METHOD 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  */
 263 METHOD void clear_ipi {
 264         device_t        _dev;
 265         u_int           _tid;
 266 };