'\" te .\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. .TH ddi_intr_enable 9F "22 Apr 2005" "SunOS 5.11" "Kernel Functions for Drivers" .SH NAME ddi_intr_enable, ddi_intr_block_enable, ddi_intr_disable, ddi_intr_block_disable \- enable or disable a given interrupt or range of interrupts .SH SYNOPSIS .LP .nf #include #include #include #include \fBint\fR \fBddi_intr_enable\fR(\fBddi_intr_handle_t\fR \fIh\fR); .fi .LP .nf \fBint\fR \fBddi_intr_block_enable\fR(\fBddi_intr_handle_t *\fR\fIh_array\fR, \fBint\fR \fIcount\fR); .fi .LP .nf \fBint\fR \fBddi_intr_disable\fR(\fBddi_intr_handle_t\fR \fIh\fR); .fi .LP .nf \fBint\fR \fBddi_intr_block_disable\fR(\fBddi_intr_handle_t *\fR\fIh_array\fR, \fBint\fR \fIcount\fR); .fi .SH INTERFACE LEVEL .sp .LP Solaris DDI specific (Solaris DDI). .SH PARAMETERS .sp .LP \fBddi_intr_enable()\fR .sp .ne 2 .mk .na \fB\fIh\fR\fR .ad .RS 5n .rt DDI interrupt handle .RE .sp .LP \fBddi_intr_block_enable()\fR .sp .ne 2 .mk .na \fB\fIh_array\fR\fR .ad .RS 11n .rt Pointer to an array of DDI interrupt handles .RE .sp .ne 2 .mk .na \fB\fIcount\fR\fR .ad .RS 11n .rt Number of interrupts .RE .sp .LP \fBddi_intr_disable()\fR .sp .ne 2 .mk .na \fB\fIh\fR\fR .ad .RS 5n .rt DDI interrupt handle .RE .sp .LP \fBddi_intr_block_disable()\fR .sp .ne 2 .mk .na \fB\fIh_array\fR\fR .ad .RS 11n .rt Pointer to an array of DDI interrupt handles .RE .sp .ne 2 .mk .na \fB\fIcount\fR\fR .ad .RS 11n .rt Number of interrupts .RE .SH DESCRIPTION .sp .LP The \fBddi_intr_enable()\fR function enables the interrupt given by the interrupt handle \fIh\fR. .sp .LP The \fBddi_intr_block_enable()\fR function enables a range of interrupts given by the \fIcount\fR and \fIh_array\fR arguments, where \fIcount\fR must be at least \fB1\fR and \fIh_array\fR is pointer to a count-sized array of interrupt handles. .sp .LP The \fBddi_intr_block_enable()\fR function can be used only if the device or host bridge supports the block enable/disable feature. The \fBddi_intr_get_cap()\fR function returns the \fBRO\fR flag \fBDDI_INTR_FLAG_BLOCK\fR if the device or host bridge supports the interrupt block enable/disable feature for the given interrupt type. The \fBddi_intr_block_enable()\fR function is useful for enabling MSI interrupts when the optional per-vector masking capability is not supported. .sp .LP The \fBddi_intr_enable()\fR or \fBddi_intr_block_enable()\fR functions must be called after the required interrupt resources are allocated with \fBddi_intr_alloc()\fR, the interrupt handlers are added through \fBddi_intr_add_handler()\fR, and the required locks are initialized by \fBmutex\fR(9F) or \fBrwlock\fR(9F). .sp .LP Once enabled by either of the enable calls, the interrupt can be taken and passed to the driver's interrupt service routine. Enabling an interrupt implies clearing any system or device mask bits associated with the interrupt. .sp .LP The \fBddi_intr_disable()\fR function disables the interrupt given by the interrupt handle \fIh\fR. .sp .LP The \fBddi_intr_block_disable()\fR function disables a range of interrupts given by the \fIcount\fR and \fIh_array\fR arguments, where \fIcount\fR must be at least \fB1\fR and \fIh_array\fR is pointer to a count-sized array of interrupt handles. .sp .LP The \fBddi_intr_block_disable()\fR function can be used only if the device or host bridge supports the block enable/disable feature. The \fBddi_intr_get_cap()\fR function returns the \fBRO\fR flag \fBDDI_INTR_FLAG_BLOCK\fR if the device or host bridge supports the interrupt block enable/disable feature for the given interrupt type. The \fBddi_intr_block_disable()\fR function is useful for disabling MSI interrupts when the optional per-vector masking capability is not supported. .sp .LP The \fBddi_intr_disable()\fR or \fBddi_intr_block_disable()\fR functions must be called before removing the interrupt handler and freeing the corresponding interrupt with \fBddi_intr_remove_handler()\fR and \fBddi_intr_free()\fR, respectively. The \fBddi_intr_block_disable()\fR function should be called if the \fBddi_intr_block_enable()\fR function was used to enable the interrupts. .SH RETURN VALUES .sp .LP The \fBddi_intr_enable()\fR, \fBddi_intr_block_enable()\fR, \fBddi_intr_disable()\fR, and \fBddi_intr_block_disable()\fR functions return: .sp .ne 2 .mk .na \fB\fBDDI_SUCCESS\fR\fR .ad .RS 15n .rt On success. .RE .sp .ne 2 .mk .na \fB\fBDDI_EINVAL\fR\fR .ad .RS 15n .rt On encountering invalid input parameters. .RE .sp .ne 2 .mk .na \fB\fBDDI_FAILURE\fR\fR .ad .RS 15n .rt On any implementation specific failure. .RE .SH CONTEXT .sp .LP The \fBddi_intr_enable()\fR, \fBddi_intr_block_enable()\fR, \fBddi_intr_disable()\fR, and \fBddi_intr_block_disable()\fR functions can be called from kernel non-interrupt 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 StabilityCommitted .TE .SH SEE ALSO .sp .LP \fBattributes\fR(5), \fBddi_intr_add_handler\fR(9F), \fBddi_intr_alloc\fR(9F), \fBddi_intr_dup_handler\fR(9F), \fBddi_intr_free\fR(9F), \fBddi_intr_get_cap\fR(9F), \fBddi_intr_remove_handler\fR(9F), \fBmutex\fR(9F), \fBrwlock\fR(9F) .sp .LP \fIWriting Device Drivers for Oracle Solaris 11.2\fR .SH NOTES .sp .LP Consumers of these interfaces should verify that the return value is not equal to \fBDDI_SUCCESS\fR. Incomplete checking for failure codes could result in inconsistent behavior among platforms. .sp .LP If a device driver that uses \fBMSI\fR and \fBMSI-X\fR interrupts resets the device, the device might reset its configuration space modifications. Such a reset could cause a device driver to lose any \fBMSI\fR and \fBMSI-X\fR interrupt usage settings that have been applied.