include/sys/ddi_intr.h

   1 /*
   2  * CDDL HEADER START
   3  *
   4  * The contents of this file are subject to the terms of the
   5  * Common Development and Distribution License (the "License").
   6  * You may not use this file except in compliance with the License.
   7  *
   8  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
   9  * or http://www.opensolaris.org/os/licensing.
  10  * See the License for the specific language governing permissions
  11  * and limitations under the License.
  12  *
  13  * When distributing Covered Code, include this CDDL HEADER in each
  14  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  15  * If applicable, add the following below this CDDL HEADER, with the
  16  * fields enclosed by brackets "[]" replaced with your own identifying
  17  * information: Portions Copyright [yyyy] [name of copyright owner]
  18  *
  19  * CDDL HEADER END
  20  */
  21 /*
  22  * Copyright (c) 2005, 2010, Oracle and/or its affiliates. All rights reserved.
  23  */
  24
  25 #ifndef _SYS_DDI_INTR_H
  26 #define _SYS_DDI_INTR_H
  27
  28 /*
  29  * Sun DDI interrupt support definitions
  30  */
  31
  32 #include <sys/ddipropdefs.h>
  33 #include <sys/rwlock.h>
  34 #include <sys/processor.h>
  35
  36 #ifdef  __cplusplus
  37 extern "C" {
  38 #endif
  39
  40 #ifdef _KERNEL
  41
  42 /*
  43  * Interrupt related definitions.
  44  */
  45
  46 /*
  47  * Returned by ddi_add_intr or ddi_add_fastintr in order to signal
  48  * the the caller requested interrupt number to be added does not
  49  * exist.
  50  */
  51 #define DDI_INTR_NOTFOUND       1       /* interrupt not found error */
  52
  53 /*
  54  * For use by driver interrupt service routines to return to the
  55  * system whether an interrupt was for the driver or not.
  56  */
  57 #define DDI_INTR_CLAIMED        1       /* returned when driver claims intr */
  58 #define DDI_INTR_UNCLAIMED      0       /* returned when driver does not */
  59
  60 /* Hardware interrupt types */
  61 #define DDI_INTR_TYPE_FIXED     0x1
  62 #define DDI_INTR_TYPE_MSI       0x2
  63 #define DDI_INTR_TYPE_MSIX      0x4
  64
  65 /* Hardware interrupt priority must be a number within these min/max values */
  66 #define DDI_INTR_PRI_MIN        1
  67 #define DDI_INTR_PRI_MAX        12
  68
  69 /* Soft priority must be a number within these min/max values */
  70 #define DDI_INTR_SOFTPRI_MIN    1
  71 #define DDI_INTR_SOFTPRI_MAX    9
  72
  73 /* Used in calls to allocate soft interrupt priority. */
  74 #define DDI_INTR_SOFTPRI_DEFAULT        DDI_INTR_SOFTPRI_MIN
  75
  76 /*
  77  * Interrupt flags specify certain capabilities for a given
  78  * interrupt (by type and inum).
  79  * RO/RW refer to use by ddi_intr_set_cap(9f)
  80  *
  81  * DDI_INTR_FLAG_MSI64 is an internal flag not exposed to leaf drivers.
  82  */
  83 #define DDI_INTR_FLAG_LEVEL     0x0001  /* (RW) level trigger */
  84 #define DDI_INTR_FLAG_EDGE      0x0002  /* (RW) edge triggered */
  85 #define DDI_INTR_FLAG_MASKABLE  0x0010  /* (RO) maskable */
  86 #define DDI_INTR_FLAG_PENDING   0x0020  /* (RO) int pending supported */
  87 #define DDI_INTR_FLAG_BLOCK     0x0100  /* (RO) requires block enable */
  88 #define DDI_INTR_FLAG_MSI64     0x0200  /* (RO) MSI/X supports 64 bit addr */
  89
  90 /*
  91  * Macro to be used while passing interrupt priority
  92  * for lock initialization.
  93  */
  94 #define DDI_INTR_PRI(pri)       (void *)((uintptr_t)(pri))
  95
  96 /*
  97  * Typedef for interrupt handles
  98  */
  99 typedef struct __ddi_intr_handle *ddi_intr_handle_t;
 100 typedef struct __ddi_softint_handle *ddi_softint_handle_t;
 101
 102 /*
 103  * Definition for behavior flag which is used with ddi_intr_alloc(9f).
 104  */
 105 #define DDI_INTR_ALLOC_NORMAL   0       /* Non-strict alloc */
 106 #define DDI_INTR_ALLOC_STRICT   1       /* Strict allocation */
 107
 108 /*
 109  * Typedef for driver's interrupt handler
 110  */
 111 typedef uint_t (ddi_intr_handler_t)(caddr_t arg1, caddr_t arg2);
 112
 113 #endif  /* _KERNEL */
 114 #include <sys/ddi_intr_impl.h>
 115 #ifdef _KERNEL
 116
 117 /*
 118  * DDI interrupt function prototypes.
 119  *
 120  * New DDI interrupt interfaces.
 121  */
 122
 123 /*
 124  * ddi_intr_get_supported_types:
 125  *
 126  *      Return, as a bit mask, the hardware interrupt types supported by
 127  *      both the device and by the host in the integer pointed
 128  *      to be the 'typesp' argument.
 129  */
 130 int     ddi_intr_get_supported_types(dev_info_t *dip, int *typesp);
 131
 132 /*
 133  * ddi_intr_get_nintrs:
 134  *
 135  *      Return as an integer in the integer pointed to by the argument
 136  *      *nintrsp*, the number of interrupts the device supports for the
 137  *      given interrupt type.
 138  */
 139 int     ddi_intr_get_nintrs(dev_info_t *dip, int type, int *nintrsp);
 140
 141 /*
 142  * ddi_intr_get_navail:
 143  *
 144  *      Return as an integer in the integer pointed to by the argument
 145  *      *navailp*, the number of interrupts currently available for the
 146  *      given interrupt type.
 147  */
 148 int     ddi_intr_get_navail(dev_info_t *dip, int type, int *navailp);
 149
 150 /*
 151  * Interrupt resource allocate/free functions
 152  */
 153 int     ddi_intr_alloc(dev_info_t *dip, ddi_intr_handle_t *h_array,
 154             int type, int inum, int count, int *actualp, int behavior);
 155 int     ddi_intr_free(ddi_intr_handle_t h);
 156
 157 /*
 158  * Interrupt get/set capacity functions
 159  */
 160 int     ddi_intr_get_cap(ddi_intr_handle_t h, int *flagsp);
 161 int     ddi_intr_set_cap(ddi_intr_handle_t h, int flags);
 162
 163 /*
 164  * Interrupt priority management functions
 165  */
 166 uint_t  ddi_intr_get_hilevel_pri(void);
 167 int     ddi_intr_get_pri(ddi_intr_handle_t h, uint_t *prip);
 168 int     ddi_intr_set_pri(ddi_intr_handle_t h, uint_t pri);
 169
 170 /*
 171  * Interrupt add/duplicate/remove functions
 172  */
 173 int     ddi_intr_add_handler(ddi_intr_handle_t h,
 174             ddi_intr_handler_t inthandler, void *arg1, void *arg2);
 175 int     ddi_intr_dup_handler(ddi_intr_handle_t org, int vector,
 176             ddi_intr_handle_t *dup);
 177 int     ddi_intr_remove_handler(ddi_intr_handle_t h);
 178
 179
 180 /*
 181  * Interrupt enable/disable/block_enable/block_disable functions
 182  */
 183 int     ddi_intr_enable(ddi_intr_handle_t h);
 184 int     ddi_intr_disable(ddi_intr_handle_t h);
 185 int     ddi_intr_block_enable(ddi_intr_handle_t *h_array, int count);
 186 int     ddi_intr_block_disable(ddi_intr_handle_t *h_array, int count);
 187
 188 /*
 189  * Interrupt set/clr mask functions
 190  */
 191 int     ddi_intr_set_mask(ddi_intr_handle_t h);
 192 int     ddi_intr_clr_mask(ddi_intr_handle_t h);
 193
 194 /*
 195  * Interrupt get pending function
 196  */
 197 int     ddi_intr_get_pending(ddi_intr_handle_t h, int *pendingp);
 198
 199 /*
 200  * Interrupt resource management function
 201  */
 202 int     ddi_intr_set_nreq(dev_info_t *dip, int nreq);
 203
 204 /*
 205  * Soft interrupt functions
 206  */
 207 int     ddi_intr_add_softint(dev_info_t *dip, ddi_softint_handle_t *h,
 208             int soft_pri, ddi_intr_handler_t handler, void *arg1);
 209 int     ddi_intr_remove_softint(ddi_softint_handle_t h);
 210 int     ddi_intr_trigger_softint(ddi_softint_handle_t h, void *arg2);
 211 int     ddi_intr_get_softint_pri(ddi_softint_handle_t h, uint_t *soft_prip);
 212 int     ddi_intr_set_softint_pri(ddi_softint_handle_t h, uint_t soft_pri);
 213
 214 /*
 215  * Old DDI interrupt interfaces.
 216  *
 217  * The following DDI interrupt interfaces are obsolete.
 218  * Use the above new DDI interrupt interfaces instead.
 219  */
 220
 221 /*
 222  * Return non-zero if the specified interrupt exists and the handler
 223  * will be restricted to using only certain functions because the
 224  * interrupt level is not blocked by the scheduler.  I.e., it cannot
 225  * signal other threads.
 226  */
 227 int     ddi_intr_hilevel(dev_info_t *dip, uint_t inumber);
 228
 229 int     ddi_get_iblock_cookie(dev_info_t *dip, uint_t inumber,
 230             ddi_iblock_cookie_t *iblock_cookiep);
 231
 232 /*
 233  * ddi_dev_nintrs
 234  *
 235  *      If the device has h/w interrupt(s), report
 236  *      how many of them that there are into resultp.
 237  *      Return DDI_FAILURE if the device has no interrupts.
 238  */
 239 int     ddi_dev_nintrs(dev_info_t *dev, int *resultp);
 240
 241 /*
 242  * ddi_add_intr: Add an interrupt to the system.
 243  *
 244  *      The interrupt number "inumber" determines which interrupt will
 245  *      be added. The interrupt number is associated with interrupt
 246  *      information provided from self identifying devices or configuration
 247  *      information for non-self identifying devices. If only one interrupt
 248  *      is associated with the device then the interrupt number should be 0.
 249  *
 250  *      If successful, "*iblock_cookiep" will contain information necessary
 251  *      for initializing locks (mutex_init, cv_init, etc.) as well as for
 252  *      possible later removal of the interrupt from the system.
 253  *
 254  *      If successful, "*idevice_cookiep" will contain the correct programmable
 255  *      device interrupt value (see <sys/dditypes.h> in the form of the
 256  *      type ddi_idevice_cookie_t).
 257  *
 258  *      Either cookie pointer may be specified as a NULL pointer
 259  *      in which case no value will be returned.
 260  *
 261  *      The interrupt handler "int_handler" is the address of the routine
 262  *      to be called upon receipt of an appropriate interrupt. The
 263  *      interrupt handler should return DDI_INTR_CLAIMED if the
 264  *      interrupt was claimed, else DDI_INTR_UNCLAIMED. The argument
 265  *      "int_handler_arg" will be passed to the "int_handler"
 266  *      upon receipt of an appropriate interrupt.
 267  *
 268  *      If successful ddi_add_intr will return DDI_SUCCESS.
 269  *      If the interrupt information cannot be found it will
 270  *      return DDI_INTR_NOTFOUND.
 271  *
 272  */
 273 int     ddi_add_intr(dev_info_t *dip, uint_t inumber,
 274             ddi_iblock_cookie_t *iblock_cookiep,
 275             ddi_idevice_cookie_t *idevice_cookiep,
 276             uint_t (*int_handler)(caddr_t int_handler_arg),
 277             caddr_t int_handler_arg);
 278
 279 /*
 280  * The following function is for Sun's internal use only at present
 281  */
 282 int     ddi_add_fastintr(dev_info_t *dip, uint_t inumber,
 283             ddi_iblock_cookie_t *iblock_cookiep,
 284             ddi_idevice_cookie_t *idevice_cookiep,
 285             uint_t (*hi_int_handler)(void));
 286
 287 /*
 288  * ddi_remove_intr:     Remove interrupt set up by ddi_add_intr.
 289  *
 290  *      This routine is intended to be used by drivers that are
 291  *      preparing to unload themselves "detach" from the system.
 292  */
 293 void    ddi_remove_intr(dev_info_t *dip, uint_t inum,
 294             ddi_iblock_cookie_t iblock_cookie);
 295
 296 /*
 297  * For use by ddi_add_softintr in order to specify a priority preference.
 298  */
 299 #define DDI_SOFTINT_FIXED       0       /* Fixed priority soft interrupt */
 300 #define DDI_SOFTINT_LOW         8       /* Low priority soft interrupt */
 301 #define DDI_SOFTINT_MED         128     /* Medium priority soft interrupt */
 302 #define DDI_SOFTINT_HIGH        256     /* High priority soft interrupt */
 303
 304
 305 int     ddi_get_soft_iblock_cookie(dev_info_t *dip, int preference,
 306             ddi_iblock_cookie_t *iblock_cookiep);
 307
 308 /*
 309  * ddi_add_softintr:    Add a "soft" interrupt to the system.
 310  *
 311  *      Like ddi_add_intr, only for system interrupts that you can trigger
 312  *      yourself. You specify a preference (see above) for the level you
 313  *      want. You get an identifier back which you can use to either trigger
 314  *      a soft interrupt or, later, remove it.
 315  */
 316 int     ddi_add_softintr(dev_info_t *dip, int preference, ddi_softintr_t *idp,
 317             ddi_iblock_cookie_t *iblock_cookiep,
 318             ddi_idevice_cookie_t *idevice_cookiep,
 319             uint_t (*int_handler)(caddr_t int_handler_arg),
 320             caddr_t int_handler_arg);
 321
 322 void    ddi_remove_softintr(ddi_softintr_t id);
 323
 324 void    ddi_trigger_softintr(ddi_softintr_t id);
 325
 326 #endif  /* _KERNEL */
 327
 328 #ifdef  __cplusplus
 329 }
 330 #endif
 331
 332 #endif  /* _SYS_DDI_INTR_H */