'\" te .\" Copyright (c) 2005 Sun Microsystems, Inc. All Rights Reserved. .TH ddi_add_intr 9F "19 Oct 2005" "SunOS 5.11" "Kernel Functions for Drivers" .SH NAME ddi_add_intr, ddi_get_iblock_cookie, ddi_remove_intr \- hardware interrupt handling routines .SH SYNOPSIS .LP .nf #include #include #include #include \fBint\fR \fBddi_get_iblock_cookie\fR(\fBdev_info_t *\fR\fIdip\fR, \fBuint_t\fR \fIinumber\fR, \fBddi_iblock_cookie_t *\fR\fIiblock_cookiep\fR); .fi .LP .nf \fBint\fR \fBddi_add_intr\fR(\fBdev_info_t *\fR\fIdip\fR, \fBuint_t\fR \fIinumber\fR, \fBddi_iblock_cookie_t *\fR\fIiblock_cookiep\fR, \fBddi_idevice_cookie_t *\fR\fIidevice_cookiep\fR, \fBuint_t (*\fR\fIint_handler\fR) (caddr_t), \fBcaddr_t\fR \fIint_handler_arg\fR); .fi .LP .nf \fBvoid\fR \fBddi_remove_intr\fR(\fBdev_info_t *\fR\fIdip\fR, \fBuint_t\fR \fIinumber\fR, \fBddi_iblock_cookie_t\fR \fIiblock_cookie\fR); .fi .SH INTERFACE LEVEL .sp .LP Solaris DDI specific (Solaris DDI). These interfaces are obsolete. Use the new interrupt interfaces referenced in \fBIntro\fR(9F). Refer to \fIWriting Device Drivers for Oracle Solaris 11.2\fR for more information. .SH PARAMETERS .sp .LP For \fBddi_get_iblock_cookie()\fR: .sp .ne 2 .mk .na \fB\fIdip\fR\fR .ad .RS 18n .rt Pointer to \fBdev_info\fR structure. .RE .sp .ne 2 .mk .na \fB\fIinumber\fR\fR .ad .RS 18n .rt Interrupt number. .RE .sp .ne 2 .mk .na \fB\fIiblock_cookiep\fR\fR .ad .RS 18n .rt Pointer to an interrupt block cookie. .RE .sp .LP For \fBddi_add_intr()\fR: .sp .ne 2 .mk .na \fB\fIdip\fR\fR .ad .RS 19n .rt Pointer to \fBdev_info\fR structure. .RE .sp .ne 2 .mk .na \fB\fIinumber\fR\fR .ad .RS 19n .rt Interrupt number. .RE .sp .ne 2 .mk .na \fB\fIiblock_cookiep\fR\fR .ad .RS 19n .rt Optional pointer to an interrupt block cookie where a returned interrupt block cookie is stored. .RE .sp .ne 2 .mk .na \fB\fIidevice_cookiep\fR\fR .ad .RS 19n .rt Optional pointer to an interrupt device cookie where a returned interrupt device cookie is stored. .RE .sp .ne 2 .mk .na \fB\fIint_handler\fR\fR .ad .RS 19n .rt Pointer to interrupt handler. .RE .sp .ne 2 .mk .na \fB\fIint_handler_arg\fR\fR .ad .RS 19n .rt Argument for interrupt handler. .RE .sp .LP For \fBddi_remove_intr()\fR: .sp .ne 2 .mk .na \fB\fIdip\fR\fR .ad .RS 17n .rt Pointer to \fBdev_info\fR structure. .RE .sp .ne 2 .mk .na \fB\fIinumber\fR\fR .ad .RS 17n .rt Interrupt number. .RE .sp .ne 2 .mk .na \fB\fIiblock_cookie\fR\fR .ad .RS 17n .rt Block cookie which identifies the interrupt handler to be removed. .RE .SH DESCRIPTION .SS "ddi_get_iblock_cookie(\|)" .sp .LP \fBddi_get_iblock_cookie()\fR retrieves the interrupt block cookie associated with a particular interrupt specification. This routine should be called before \fBddi_add_intr()\fR to retrieve the interrupt block cookie needed to initialize locks (\fBmutex\fR(9F), \fBrwlock\fR(9F)) used by the interrupt routine. The interrupt number \fIinumber\fR determines for which interrupt specification to retrieve the cookie. \fIinumber\fR is associated with information provided either by the device or the hardware configuration file (see \fBsysbus\fR(4), \fBisa\fR(4), and \fBdriver.conf\fR(4)). If only one interrupt is associated with the device, \fIinumber\fR should be \fB0\fR. .sp .LP On a successful return, \fI*iblock_cookiep\fR contains information needed for initializing locks associated with the interrupt specification corresponding to \fIinumber\fR (see \fBmutex_init\fR(9F) and \fBrw_init\fR(9F)). The driver can then initialize locks acquired by the interrupt routine before calling \fBddi_add_intr()\fR which prevents a possible race condition where the driver's interrupt handler is called immediately \fBafter\fR the driver has called \fBddi_add_intr()\fR but \fBbefore\fR 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. .SS "ddi_add_intr(\|)" .sp .LP \fBddi_add_intr()\fR adds an interrupt handler to the system. The interrupt number \fIinumber\fR determines which interrupt the handler will be associated with. (Refer to \fBddi_get_iblock_cookie()\fR above.) .sp .LP On a successful return, \fIiblock_cookiep\fR contains information used for initializing locks associated with this interrupt specification (see \fBmutex_init\fR(9F) and \fBrw_init\fR(9F)). Note that the interrupt block cookie is usually obtained using \fBddi_get_iblock_cookie()\fR to avoid the race conditions described above (refer to \fBddi_get_iblock_cookie()\fR above). For this reason, \fIiblock_cookiep\fR is no longer useful and should be set to \fINULL\fR. .sp .LP On a successful return, \fIidevice_cookiep\fR contains a pointer to a \fBddi_idevice_cookie_t\fR structure (see \fBddi_idevice_cookie\fR(9S)) containing information useful for some devices that have programmable interrupts. If \fIidevice_cookiep\fR is set to \fINULL\fR, no value is returned. .sp .LP The routine \fIintr_handler\fR, with its argument \fIint_handler_arg\fR, is called upon receipt of the appropriate interrupt. The interrupt handler should return \fBDDI_INTR_CLAIMED\fR if the interrupt was claimed, \fBDDI_INTR_UNCLAIMED\fR otherwise. .sp .LP If successful, \fBddi_add_intr()\fR returns \fBDDI_SUCCESS\fR. If the interrupt information cannot be found on the sun4u architecture, either \fBDDI_INTR_NOTFOUND\fR or \fBDDI_FAILURE\fR can be returned. On i86pc and sun4m architectures, if the interrupt information cannot be found, \fBDDI_INTR_NOTFOUND\fR is returned. .SS "ddi_remove_intr(\|)" .sp .LP \fBddi_remove_intr()\fR removes an interrupt handler from the system. Unloadable drivers should call this routine during their \fBdetach\fR(9E) routine to remove their interrupt handler from the system. .sp .LP The device interrupt routine for this instance of the device will not execute after \fBddi_remove_intr()\fR returns. \fBddi_remove_intr()\fR 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 \fBddi_remove_intr()\fR or deadlock may result. .SS "For All Three Functions:" .sp .LP For certain bus types, you can call these \fBDDI\fR functions from a high-interrupt context. These types include \fBISA\fR and SBus buses. See \fBsysbus\fR(4) and \fBisa\fR(4) for details. .SH RETURN VALUES .sp .LP \fBddi_add_intr()\fR and \fBddi_get_iblock_cookie()\fR return: .sp .ne 2 .mk .na \fB\fBDDI_SUCCESS\fR\fR .ad .RS 21n .rt On success. .RE .sp .ne 2 .mk .na \fB\fBDDI_INTR_NOTFOUND\fR\fR .ad .RS 21n .rt On failure to find the interrupt. .RE .sp .ne 2 .mk .na \fB\fBDDI_FAILURE\fR\fR .ad .RS 21n .rt On failure. \fBDDI_FAILURE\fR can also be returned on failure to find interrupt (\fBsun4u\fR). .RE .SH CONTEXT .sp .LP \fBddi_add_intr()\fR, \fBddi_remove_intr()\fR, and \fBddi_get_iblock_cookie()\fR can be called from user or kernel context. .SH ATTRIBUTES .sp .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp .sp .TS tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) . ATTRIBUTE TYPEATTRIBUTE VALUE _ Interface StabilityObsolete .TE .SH SEE ALSO .sp .LP \fBdriver.conf\fR(4), \fBisa\fR(4), \fBsysbus\fR(4), \fBattach\fR(9E), \fBdetach\fR(9E), \fBddi_intr_hilevel\fR(9F), \fBIntro\fR(9F), \fBmutex\fR(9F), \fBmutex_init\fR(9F), \fBrw_init\fR(9F), \fBrwlock\fR(9F), \fBddi_idevice_cookie\fR(9S) .sp .LP \fIWriting Device Drivers for Oracle Solaris 11.2\fR .SH NOTES .sp .LP \fBddi_get_iblock_cookie()\fR must not be called \fBafter\fR the driver adds an interrupt handler for the interrupt specification corresponding to \fIinumber\fR. .sp .LP All consumers of these interfaces, checking return codes, should verify \fBreturn_code != DDI_SUCCESS\fR. Checking for specific failure codes can result in inconsistent behaviors among platforms. .SH BUGS .sp .LP The \fIidevice_cookiep\fR should really point to a data structure that is specific to the bus architecture that the device operates on. Currently the SBus and PCI buses are supported and a single data structure is used to describe both.