'\"
.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved.
.\" Copyright 2024 Oxide Computer Company
.\" 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]
.Dd September 15, 2024
.Dt DDI_INTR_ADD_HANDLER 9F
.Os
.Sh NAME
.Nm ddi_intr_add_handler ,
.Nm ddi_intr_remove_handler
.Nd add or remove interrupt handler
.Sh SYNOPSIS
.In sys/types.h
.In sys/conf.h
.In sys/ddi.h
.In sys/sunddi.h
.Ft typedef uint_t
.Fo (ddi_intr_handler_t)
.Fa "caddr_t arg1"
.Fa "caddr_t arg2"
.Fc
.Ft int
.Fo ddi_intr_add_handler
.Fa "ddi_intr_handle_t *h"
.Fa "ddi_intr_handler_t inthandler"
.Fa "void *arg1"
.Fa "void *arg2"
.Fc
.Ft int
.Fo ddi_intr_remove_handler
.Fa "ddi_intr_handle_t h"
.Fc
.Sh INTERFACE LEVEL
illumos DDI specific
.Pq illumos DDI .
.Sh PARAMETERS
.Bl -tag -width Fa
.It Fa h
Pointer to the DDI interrupt handle
.It Fa inthandler
Pointer to interrupt handler function
.It Fa arg1
First argument for the interrupt handler
.It Fa arg2
Second, optional, argument for the interrupt handler
.El
.Sh DESCRIPTION
The
.Fn ddi_intr_add_handler
function adds an interrupt handler given by the
.Fa inthandler
argument to the system with the handler arguments
.Fa arg1
and
.Fa arg2
for the previously allocated interrupt handle specified by the
.Fa h
pointer.
The arguments
.Fa arg1
and
.Fa arg2
are passed as the first and second arguments, respectively, to the interrupt
handler
.Fa inthandler .
The definition of the interrupt handler,
.Vt ddi_intr_handler_t
is provided in the manual synposis and can also be found in
.In sys/ddi_intr.h .
.Pp
The routine
.Fa inthandler
with the arguments
.Fa arg1
and
.Fa arg2
is called upon receipt of the appropriate interrupt.
The interrupt handler should return
.Dv DDI_INTR_CLAIMED
if the interrupt is claimed and
.Dv DDI_INTR_UNCLAIMED
otherwise.
.Pp
The
.Fn ddi_intr_add_handler
function must be called after
.Fn ddi_intr_alloc ,
but before
.Fn ddi_intr_enable
is called.
The interrupt must be enabled through
.Fn ddi_intr_enable
or
.Fn ddi_intr_block_enable
before it can be used.
.Pp
The
.Fn ddi_intr_remove_handler
function removes the handler association, added previously with
.Fn ddi_intr_add_handler ,
for the interrupt identified by the interrupt handle
.Fa h
argument.
Unloadable drivers should call this routine during their
.Xr detach 9E
routine to remove the interrupt handler from the system.
.Pp
The
.Fn ddi_intr_remove_handler
function is used to disassociate the handler after the interrupt is disabled to
remove duplicated interrupt handles.
See
.Xr ddi_intr_dup_handler 9F
for duplicated interrupt handles.
If a handler is duplicated with the
.Fn ddi_intr_dup_handler
function, all added and duplicated instances of the handler must be removed with
.Fn ddi_intr_remove_handler
in order for the handler to be completely removed.
.Sh CONTEXT
The
.Fn ddi_intr_add_handler
and
.Fn ddi_intr_remove_handler
functions can be called from kernel non-interrupt context.
.Sh RETURN VALUES
The
.Fn ddi_intr_add_handler
and
.Fn ddi_intr_remove_handler
functions return:
.Bl -tag -width Ds
.It Dv DDI_SUCCESS
On success.
.It Dv DDI_EINVAL
On encountering invalid input parameters.
.It Dv DDI_FAILURE
On any implementation specific failure.
.El
.Sy Interface Stability
.Sy Committed
.Sh SEE ALSO
.Xr attributes 7 ,
.Xr attach 9E ,
.Xr detach 9E ,
.Xr ddi_intr_alloc 9F ,
.Xr ddi_intr_block_enable 9F ,
.Xr ddi_intr_disable 9F ,
.Xr ddi_intr_dup_handler 9F ,
.Xr ddi_intr_enable 9F ,
.Xr ddi_intr_free 9F ,
.Xr ddi_intr_get_supported_types 9F ,
.Xr mutex 9F ,
.Xr mutex_init 9F ,
.Xr rw_init 9F ,
.Xr rwlock 9F
.Pp
.Rs
.%T Writing Device Drivers
.Re
.Sh NOTES
When checking the return value of the
.Fn ddi_intr_add_handler
and
.Fn ddi_intr_rem_handler
functions
.Pq and more generally other DDI functions
callers should always write the check by comparing to
.Dv DDI_SUCCESS .
Put differently checks should look like:
.Bd -literal -offset indent
int ret;
uintptr_t msi_index = \&.\&.\&.;

\&.\&.\&.

ret = ddi_intr_add_handler(h, intr_func, state, (void *)msi_index);
if (ret != DDI_SUCCESS) {
	/* Perform clean up activities */
}
.Ed
.Pp
Additional error codes may be added over time and checking only for
.Dv DDI_FAILURE
could lead to missing that such an error had occurred.
.Pp
If a device driver that uses
.Sy MSI
and
.Sy MSI-X
interrupts resets the device, the device might reset its configuration space
modifications.
Such a reset could cause a device driver to lose any
.Sy MSI
and
.Sy MSI-X
interrupt usage settings that have been applied.
.Pp
The second argument,
.Fa arg2 ,
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.