'\" 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
.nf
#include <sys/types.h>
#include <sys/conf.h>
#include <sys/ddi.h>
#include <sys/sunddi.h>



\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
illumos DDI specific (illumos DDI).
.SH PARAMETERS
\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
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<sys/ddi_intr.h>\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
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
The \fBddi_intr_add_handler()\fR and \fBddi_intr_remove_handler()\fR functions
can be called from kernel non-interrupt context.
.SH ATTRIBUTES
See \fBattributes\fR(7) 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
.BR attributes (7),
.BR attach (9E),
.BR detach (9E),
.BR ddi_intr_alloc (9F),
.BR ddi_intr_block_enable (9F),
.BR ddi_intr_disable (9F),
.BR ddi_intr_dup_handler (9F),
.BR ddi_intr_enable (9F),
.BR ddi_intr_free (9F),
.BR ddi_intr_get_supported_types (9F),
.BR mutex (9F),
.BR mutex_init (9F),
.BR rw_init (9F),
.BR rwlock (9F)
.sp
.LP
\fIWriting Device Drivers\fR
.SH NOTES
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.