ddi_intr_add_handler(9F)                                                                                                  ddi_intr_add_handler(9F)

NAME

       ddi_intr_add_handler, ddi_intr_remove_handler - add or remove interrupt handler

SYNOPSIS

       #include <sys/types.h>
       #include <sys/conf.h>
       #include <sys/ddi.h>
       #include <sys/sunddi.h>

       int ddi_intr_add_handler(ddi_intr_handle_t *h, ddi_intr_handler_t inthandler, void *arg1, void *arg2);

       int ddi_intr_remove_handler(ddi_intr_handle_t h);

INTERFACE LEVEL

       Solaris DDI specific (Solaris DDI).

       ddi_intr_add_handler()

       h               Pointer to the DDI interrupt handle

       inthandler      Pointer to interrupt handler

       arg1            First argument for the interrupt handler

       arg2            Second, optional, argument for the interrupt handler

       ddi_intr_remove_handler()

       h               DDI interrupt handle

       The  ddi_intr_add_handler()  function  adds  an interrupt handler given by the inthandler argument to the system with the handler arguments
       arg1 and arg2 for the previously allocated interrupt handle specified by the h pointer. The arguments arg1 and arg2 are passed as the first
       and second arguments, respectively, to the interrupt handler inthandler. See <sys/ddi_intr.h> for the definition of the interrupt handler.

       The  routine  inthandler with the arguments arg1 and arg2 is called upon receipt of the appropriate interrupt. The interrupt handler should
       return DDI_INTR_CLAIMED if the interrupt is claimed and DDI_INTR_UNCLAIMED otherwise.

       The ddi_intr_add_handler() function must be called after ddi_intr_alloc(), but before ddi_intr_enable() is called. The  interrupt  must  be
       enabled through ddi_intr_enable() or ddi_intr_block_enable() before it can be used.

       The  ddi_intr_remove_handler()  function  removes  the handler association, added previously with ddi_intr_add_handler(), for the interrupt
       identified by the interrupt handle h argument. Unloadable drivers should call this routine during their detach(9E) routine  to  remove  the
       interrupt handler from the system.

       The  ddi_intr_remove_handler() function is used to disassociate the handler after the interrupt is disabled to remove dup-ed interrupt han-
       dles. See ddi_intr_dup_handler(9F) for dup-ed interrupt handles. If a handler is duplicated with the ddi_intr_dup_handler()  function,  all
       added  and  duplicated  instances  of  the handler must be removed with ddi_intr_remove_handler() in order for the handler to be completely
       removed.

       The ddi_intr_add_handler() and ddi_intr_remove_handler() functions return:

       DDI_SUCCESS             On success.

       DDI_EINVAL              On encountering invalid input parameters.

       DDI_FAILURE             On any implementation specific failure.

CONTEXT

       The ddi_intr_add_handler() and ddi_intr_remove_handler() functions can be called from kernel non-interrupt context.

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE         |      ATTRIBUTE VALUE        |
       +-----------------------------+-----------------------------+
       |Interface Stability          |Evolving                     |
       +-----------------------------+-----------------------------+

       attributes(5),  attach(9E),  detach(9E),  ddi_intr_alloc(9F),  ddi_intr_block_enable(9F),  ddi_intr_disable(9F),  ddi_intr_dup_handler(9F),
       ddi_intr_enable(9F), ddi_intr_free(9F), ddi_intr_get_supported_types(9F), mutex(9F), mutex_init(9F), rw_init(9F), rwlock(9F)

       Consumers  of these interfaces should verify that the return value is not equal to DDI_SUCCESS. Incomplete checking for failure codes could
       result in inconsistent behavior among platforms.

       If a device driver that uses MSI and MSI-X interrupts resets the device, the device might reset its configuration space modifications. Such
       a reset could cause a device driver to lose any MSI and MSI-X interrupt usage settings that have been applied.

       The  second argument, arg2, is optional. Device drivers are free to use the two arguments however they see fit. There is no officially rec-
       ommended model or restrictions. For example, an interrupt handler may wish to use the first argument as the pointer to  its  softstate  and
       the second argument as the value of the MSI vector.

                                                                    22 Apr 2005                                           ddi_intr_add_handler(9F)