1'\" 2.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. 3.\" Copyright 2024 Oxide Computer Company 4.\" 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. 5.\" 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. 6.\" 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] 7.Dd September 15, 2024 8.Dt DDI_INTR_ADD_HANDLER 9F 9.Os 10.Sh NAME 11.Nm ddi_intr_add_handler , 12.Nm ddi_intr_remove_handler 13.Nd add or remove interrupt handler 14.Sh SYNOPSIS 15.In sys/types.h 16.In sys/conf.h 17.In sys/ddi.h 18.In sys/sunddi.h 19.Ft typedef uint_t 20.Fo (ddi_intr_handler_t) 21.Fa "caddr_t arg1" 22.Fa "caddr_t arg2" 23.Fc 24.Ft int 25.Fo ddi_intr_add_handler 26.Fa "ddi_intr_handle_t *h" 27.Fa "ddi_intr_handler_t inthandler" 28.Fa "void *arg1" 29.Fa "void *arg2" 30.Fc 31.Ft int 32.Fo ddi_intr_remove_handler 33.Fa "ddi_intr_handle_t h" 34.Fc 35.Sh INTERFACE LEVEL 36illumos DDI specific 37.Pq illumos DDI . 38.Sh PARAMETERS 39.Bl -tag -width Fa 40.It Fa h 41Pointer to the DDI interrupt handle 42.It Fa inthandler 43Pointer to interrupt handler function 44.It Fa arg1 45First argument for the interrupt handler 46.It Fa arg2 47Second, optional, argument for the interrupt handler 48.El 49.Sh DESCRIPTION 50The 51.Fn ddi_intr_add_handler 52function adds an interrupt handler given by the 53.Fa inthandler 54argument to the system with the handler arguments 55.Fa arg1 56and 57.Fa arg2 58for the previously allocated interrupt handle specified by the 59.Fa h 60pointer. 61The arguments 62.Fa arg1 63and 64.Fa arg2 65are passed as the first and second arguments, respectively, to the interrupt 66handler 67.Fa inthandler . 68The definition of the interrupt handler, 69.Vt ddi_intr_handler_t 70is provided in the manual synposis and can also be found in 71.In sys/ddi_intr.h . 72.Pp 73The routine 74.Fa inthandler 75with the arguments 76.Fa arg1 77and 78.Fa arg2 79is called upon receipt of the appropriate interrupt. 80The interrupt handler should return 81.Dv DDI_INTR_CLAIMED 82if the interrupt is claimed and 83.Dv DDI_INTR_UNCLAIMED 84otherwise. 85.Pp 86The 87.Fn ddi_intr_add_handler 88function must be called after 89.Fn ddi_intr_alloc , 90but before 91.Fn ddi_intr_enable 92is called. 93The interrupt must be enabled through 94.Fn ddi_intr_enable 95or 96.Fn ddi_intr_block_enable 97before it can be used. 98.Pp 99The 100.Fn ddi_intr_remove_handler 101function removes the handler association, added previously with 102.Fn ddi_intr_add_handler , 103for the interrupt identified by the interrupt handle 104.Fa h 105argument. 106Unloadable drivers should call this routine during their 107.Xr detach 9E 108routine to remove the interrupt handler from the system. 109.Pp 110The 111.Fn ddi_intr_remove_handler 112function is used to disassociate the handler after the interrupt is disabled to 113remove duplicated interrupt handles. 114See 115.Xr ddi_intr_dup_handler 9F 116for duplicated interrupt handles. 117If a handler is duplicated with the 118.Fn ddi_intr_dup_handler 119function, all added and duplicated instances of the handler must be removed with 120.Fn ddi_intr_remove_handler 121in order for the handler to be completely removed. 122.Sh CONTEXT 123The 124.Fn ddi_intr_add_handler 125and 126.Fn ddi_intr_remove_handler 127functions can be called from kernel non-interrupt context. 128.Sh RETURN VALUES 129The 130.Fn ddi_intr_add_handler 131and 132.Fn ddi_intr_remove_handler 133functions return: 134.Bl -tag -width Ds 135.It Dv DDI_SUCCESS 136On success. 137.It Dv DDI_EINVAL 138On encountering invalid input parameters. 139.It Dv DDI_FAILURE 140On any implementation specific failure. 141.El 142.Sy Interface Stability 143.Sy Committed 144.Sh SEE ALSO 145.Xr attributes 7 , 146.Xr attach 9E , 147.Xr detach 9E , 148.Xr ddi_intr_alloc 9F , 149.Xr ddi_intr_block_enable 9F , 150.Xr ddi_intr_disable 9F , 151.Xr ddi_intr_dup_handler 9F , 152.Xr ddi_intr_enable 9F , 153.Xr ddi_intr_free 9F , 154.Xr ddi_intr_get_supported_types 9F , 155.Xr mutex 9F , 156.Xr mutex_init 9F , 157.Xr rw_init 9F , 158.Xr rwlock 9F 159.Pp 160.Rs 161.%T Writing Device Drivers 162.Re 163.Sh NOTES 164When checking the return value of the 165.Fn ddi_intr_add_handler 166and 167.Fn ddi_intr_rem_handler 168functions 169.Pq and more generally other DDI functions 170callers should always write the check by comparing to 171.Dv DDI_SUCCESS . 172Put differently checks should look like: 173.Bd -literal -offset indent 174int ret; 175uintptr_t msi_index = \&.\&.\&.; 176 177\&.\&.\&. 178 179ret = ddi_intr_add_handler(h, intr_func, state, (void *)msi_index); 180if (ret != DDI_SUCCESS) { 181 /* Perform clean up activities */ 182} 183.Ed 184.Pp 185Additional error codes may be added over time and checking only for 186.Dv DDI_FAILURE 187could lead to missing that such an error had occurred. 188.Pp 189If a device driver that uses 190.Sy MSI 191and 192.Sy MSI-X 193interrupts resets the device, the device might reset its configuration space 194modifications. 195Such a reset could cause a device driver to lose any 196.Sy MSI 197and 198.Sy MSI-X 199interrupt usage settings that have been applied. 200.Pp 201The second argument, 202.Fa arg2 , 203is optional. 204Device drivers are free to use the two arguments however they see fit. 205There is no officially recommended model or restrictions. 206For example, an interrupt handler may wish to use the first argument as the 207pointer to its softstate and the second argument as the value of the MSI vector. 208