|DDI_ADD_INTR(9F)||Kernel Functions for Drivers||DDI_ADD_INTR(9F)|
#include <sys/types.h> #include <sys/conf.h> #include <sys/ddi.h> #include <sys/sunddi.h> int ddi_get_iblock_cookie(dev_info_t *dip, uint_t inumber, ddi_iblock_cookie_t *iblock_cookiep);
int ddi_add_intr(dev_info_t *dip, uint_t inumber, ddi_iblock_cookie_t *iblock_cookiep, ddi_idevice_cookie_t *idevice_cookiep, uint_t (*int_handler) (caddr_t), caddr_t int_handler_arg);
void ddi_remove_intr(dev_info_t *dip, uint_t inumber, ddi_iblock_cookie_t iblock_cookie);
On a successful return, *iblock_cookiep contains information needed for initializing locks associated with the interrupt specification corresponding to inumber (see mutex_init(9F) and rw_init(9F)). The driver can then initialize locks acquired by the interrupt routine before calling ddi_add_intr() which prevents a possible race condition where the driver's interrupt handler is called immediately after the driver has called ddi_add_intr() but before the driver has initialized the locks. This may happen when an interrupt for a different device occurs on the same interrupt level. If the interrupt routine acquires the lock before the lock has been initialized, undefined behavior may result.
On a successful return, iblock_cookiep contains information used for initializing locks associated with this interrupt specification (see mutex_init(9F) and rw_init(9F)). Note that the interrupt block cookie is usually obtained using ddi_get_iblock_cookie() to avoid the race conditions described above (refer to ddi_get_iblock_cookie() above). For this reason, iblock_cookiep is no longer useful and should be set to NULL.
On a successful return, idevice_cookiep contains a pointer to a ddi_idevice_cookie_t structure (see ddi_idevice_cookie(9S)) containing information useful for some devices that have programmable interrupts. 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() returns DDI_SUCCESS. If the interrupt information cannot be found on the sun4u architecture, either DDI_INTR_NOTFOUND or DDI_FAILURE can be returned. On i86pc and sun4m architectures, if the interrupt information cannot be found, DDI_INTR_NOTFOUND is returned.
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.
|ATTRIBUTE TYPE||ATTRIBUTE VALUE|
Writing Device Drivers
All consumers of these interfaces, checking return codes, should verify return_code != DDI_SUCCESS. Checking for specific failure codes can result in inconsistent behaviors among platforms.
|October 19, 2005||OmniOS|