NAME

ddi_add_intr, ddi_remove_intr - add and remove an interrupt handler

SYNOPSIS

#include <sys/conf.h>

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

int ddi_add_intr(dev_info_t * dip, u_int inumber, ddi_iblock_cookie_t * iblock_cookiep,

        ddi_idevice_cookie_t * idevice_cookiep, u_int (* int_handler)(caddr_t),
        caddr_t int_handler_arg);

void ddi_remove_intr(dev_info_t * dip, u_int inumber, ddi_iblock_cookie_t iblock_cookie);

ARGUMENTS

ddi_add_intr( )

dip

Pointer to dev_info structure.

inumber

Interrupt number.

iblock_cookiep

Pointer to an interrupt block cookie.

idevice_cookiep

Pointer to an interrupt device cookie.

int_handler

Pointer to interrupt handler.

int_handler_arg

Argument for interrupt handler.

ddi_remove_intr( )

dip

Pointer to dev_info structure.

inumber

Interrupt number.

iblock_cookie

Block cookie which identifies the interrupt handler to be removed.

INTERFACE LEVEL

Solaris DDI specific (Solaris DDI).

DESCRIPTION

ddi_add_intr( ) adds an interrupt handler to the system. The interrupt number inumber determines which interrupt the handler will be associated with. The parameter inumber is associated with information provided either by the device (see sbus(4)) or the hardware configuration file (see vme(4) and driver.conf(4)). If only one interrupt is associated with the device, inumber should be 0.

On a successful return, iblock_cookiep contains information needed for initializing mutexes associated with this interrupt specification (see mutex_init(9F)). If iblock_cookiep is set to NULL, no value will be returned.

On a successful return, idevice_cookiep contains a pointer to a structure containing information useful for some devices that have programmable interrupts. The idev_priority field of the returned structure contains the bus interrupt priority level and the idev_vector field contains the vector number for vectored bus architectures such as VMEbus. If idevice_cookiep is set to NULL, no value is returned.

The routine intr_handler, with its argument int_handler_arg, is called upon receipt of the appropriate interrupt. The interrupt handler should return DDI_INTR_CLAIMED if the interrupt was claimed, DDI_INTR_UNCLAIMED otherwise.

If successful, ddi_add_intr( ) will return DDI_SUCCESS; if the interrupt information cannot be found, it will return DDI_INTR_NOTFOUND.

ddi_remove_intr( ) removes an interrupt handler from the system. Unloadable drivers should call this routine during their detach(9E) routine to remove their interrupt handler from the system.

The device interrupt routine for this instance of the device will not execute after ddi_remove_intr( ) returns. ddi_remove_intr( ) may need to wait for the device interrupt routine to complete before returning. Therefore, locks acquired by the interrupt handler should not be held across the call to ddi_remove_intr( ) or deadlock may result.

RETURN VALUES

ddi_add_intr( ) returns:

DDI_SUCCESS

on success.

DDI_INTR_NOTFOUND

on failure to find the interrupt.

CONTEXT

ddi_add_intr( ) and ddi_remove_intr( ) can be called from user or interrupt context.

SEE ALSO

driver.conf(4), sbus(4), vme(4), attach(9E), detach(9E), ddi_intr_hilevel(9F), mutex_init(9F)

Writing Device Drivers

BUGS

The idevice_cookiep should really point to a data structure that is specific to the bus architecture that the device operates on. Currently only VMEbus and SBus are supported and a single data structure is used to describe both.

It is possible that a driver's interrupt handler will be called immediately after the driver has called ddi_add_intr( ) but before the driver has had an opportunity to initialize its mutexes. This can happen when an interrupt for a different device occurs on the same interrupt level. If the interrupt routine acquires the mutex before it has been initialized, undefined behavior may result.

The solution to this problem is to add a temporary interrupt handler using ddi_add_intr( ). The temporary interrupt routine must be a function that performs no action, such as nulldev(9F). This allows the driver to obtain the interrupt block cookie for the interrupt, which it can then use to initialize any mutexes. After the mutexes are initialized, the temporary interrupt handler can be removed, and the real one installed. nulldev(9F) can be used as the temporary interrupt handler, though it needs to be cast properly.