'\" te .\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] .TH DDI_INTR_ADD_HANDLER 9F "Apr 22, 2005" .SH NAME ddi_intr_add_handler, ddi_intr_remove_handler \- add or remove interrupt handler .SH SYNOPSIS .LP .nf #include #include #include #include \fBint\fR \fBddi_intr_add_handler\fR(\fBddi_intr_handle_t *\fR\fIh\fR, \fBddi_intr_handler_t\fR \fIinthandler\fR, \fBvoid *\fR\fIarg1\fR, \fBvoid *\fR\fIarg2\fR); .fi .LP .nf \fBint\fR \fBddi_intr_remove_handler\fR(\fBddi_intr_handle_t\fR \fIh\fR); .fi .SH INTERFACE LEVEL .sp .LP Solaris DDI specific (Solaris DDI). .SH PARAMETERS .sp .LP \fBddi_intr_add_handler()\fR .sp .ne 2 .na \fB\fIh\fR\fR .ad .RS 14n Pointer to the DDI interrupt handle .RE .sp .ne 2 .na \fB\fIinthandler\fR\fR .ad .RS 14n Pointer to interrupt handler .RE .sp .ne 2 .na \fB\fIarg1\fR\fR .ad .RS 14n First argument for the interrupt handler .RE .sp .ne 2 .na \fB\fIarg2\fR\fR .ad .RS 14n Second, optional, argument for the interrupt handler .RE .sp .LP \fBddi_intr_remove_handler()\fR .sp .ne 2 .na \fB\fIh\fR\fR .ad .RS 5n DDI interrupt handle .RE .SH DESCRIPTION .sp .LP The \fBddi_intr_add_handler()\fR function adds an interrupt handler given by the \fIinthandler\fR argument to the system with the handler arguments \fIarg1\fR and \fIarg2\fR for the previously allocated interrupt handle specified by the \fIh\fR pointer. The arguments \fIarg1\fR and \fIarg2\fR are passed as the first and second arguments, respectively, to the interrupt handler \fIinthandler\fR. See \fB\fR for the definition of the interrupt handler. .sp .LP The routine \fIinthandler\fR with the arguments \fIarg1\fR and \fIarg2\fR is called upon receipt of the appropriate interrupt. The interrupt handler should return \fBDDI_INTR_CLAIMED\fR if the interrupt is claimed and \fBDDI_INTR_UNCLAIMED\fR otherwise. .sp .LP The \fBddi_intr_add_handler()\fR function must be called after \fBddi_intr_alloc()\fR, but before \fBddi_intr_enable()\fR is called. The interrupt must be enabled through \fBddi_intr_enable()\fR or \fBddi_intr_block_enable()\fR before it can be used. .sp .LP The \fBddi_intr_remove_handler()\fR function removes the handler association, added previously with \fBddi_intr_add_handler()\fR, for the interrupt identified by the interrupt handle \fIh\fR argument. Unloadable drivers should call this routine during their \fBdetach\fR(9E) routine to remove the interrupt handler from the system. .sp .LP The \fBddi_intr_remove_handler()\fR function is used to disassociate the handler after the interrupt is disabled to remove \fBdup-ed\fR interrupt handles. See \fBddi_intr_dup_handler\fR(9F) for \fBdup-ed\fR interrupt handles. If a handler is duplicated with the \fBddi_intr_dup_handler()\fR function, all added and duplicated instances of the handler must be removed with \fBddi_intr_remove_handler()\fR in order for the handler to be completely removed. .SH RETURN VALUES .sp .LP The \fBddi_intr_add_handler()\fR and \fBddi_intr_remove_handler()\fR functions return: .sp .ne 2 .na \fB\fBDDI_SUCCESS\fR\fR .ad .RS 15n On success. .RE .sp .ne 2 .na \fB\fBDDI_EINVAL\fR\fR .ad .RS 15n On encountering invalid input parameters. .RE .sp .ne 2 .na \fB\fBDDI_FAILURE\fR\fR .ad .RS 15n On any implementation specific failure. .RE .SH CONTEXT .sp .LP The \fBddi_intr_add_handler()\fR and \fBddi_intr_remove_handler()\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 box; c | c l | l . ATTRIBUTE TYPE ATTRIBUTE VALUE _ Interface Stability Committed .TE .SH SEE ALSO .sp .LP \fBattributes\fR(5), \fBattach\fR(9E), \fBdetach\fR(9E), \fBddi_intr_alloc\fR(9F), \fBddi_intr_block_enable\fR(9F), \fBddi_intr_disable\fR(9F), \fBddi_intr_dup_handler\fR(9F), \fBddi_intr_enable\fR(9F), \fBddi_intr_free\fR(9F), \fBddi_intr_get_supported_types\fR(9F), \fBmutex\fR(9F), \fBmutex_init\fR(9F), \fBrw_init\fR(9F), \fBrwlock\fR(9F) .sp .LP \fIWriting Device Drivers\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. .sp .LP The second argument, \fIarg2\fR, is optional. Device drivers are free to use the two arguments however they see fit. There is no officially recommended 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.