1.\" Copyright (c) 2000-2001 John H. Baldwin <jhb@FreeBSD.org> 2.\" 3.\" Redistribution and use in source and binary forms, with or without 4.\" modification, are permitted provided that the following conditions 5.\" are met: 6.\" 1. Redistributions of source code must retain the above copyright 7.\" notice, this list of conditions and the following disclaimer. 8.\" 2. Redistributions in binary form must reproduce the above copyright 9.\" notice, this list of conditions and the following disclaimer in the 10.\" documentation and/or other materials provided with the distribution. 11.\" 12.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 13.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 14.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 15.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 16.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 17.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 18.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 19.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 20.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 21.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 22.\" SUCH DAMAGE. 23.\" 24.Dd October 12, 2022 25.Dt SWI 9 26.Os 27.Sh NAME 28.Nm swi_add , 29.Nm swi_remove , 30.Nm swi_sched 31.Nd register and schedule software interrupt handlers 32.Sh SYNOPSIS 33.In sys/param.h 34.In sys/bus.h 35.In sys/interrupt.h 36.Vt "extern struct intr_event *clk_intr_event" ; 37.Ft int 38.Fo swi_add 39.Fa "struct intr_event **eventp" 40.Fa "const char *name" 41.Fa "driver_intr_t handler" 42.Fa "void *arg" 43.Fa "int pri" 44.Fa "enum intr_type flags" 45.Fa "void **cookiep" 46.Fc 47.Ft int 48.Fn swi_remove "void *cookie" 49.Ft void 50.Fn swi_sched "void *cookie" "int flags" 51.Sh DESCRIPTION 52These functions are used to register and schedule software interrupt handlers. 53Software interrupt handlers are attached to a software interrupt thread, just 54as hardware interrupt handlers are attached to a hardware interrupt thread. 55Multiple handlers can be attached to the same thread. 56Software interrupt handlers can be used to queue up less critical processing 57inside of hardware interrupt handlers so that the work can be done at a later 58time. 59Software interrupt threads are different from other kernel threads in that they 60are treated as an interrupt thread. 61This means that time spent executing these threads is counted as interrupt 62time, and that they can be run via a lightweight context switch. 63.Pp 64The 65.Fn swi_add 66function is used to add a new software interrupt handler to a specified 67interrupt event. 68The 69.Fa eventp 70argument is an optional pointer to a 71.Vt struct intr_event 72pointer. 73If this argument points to an existing event that holds a list of 74interrupt handlers, then this handler will be attached to that event. 75Otherwise a new event will be created, and if 76.Fa eventp 77is not 78.Dv NULL , 79then the pointer at that address to will be modified to point to the 80newly created event. 81The 82.Fa name 83argument is used to associate a name with a specific handler. 84This name is appended to the name of the software interrupt thread that this 85handler is attached to. 86The 87.Fa handler 88argument is the function that will be executed when the handler is scheduled 89to run. 90The 91.Fa arg 92parameter will be passed in as the only parameter to 93.Fa handler 94when the function is executed. 95The 96.Fa pri 97value specifies the priority of this interrupt handler relative to other 98software interrupt handlers. 99If an interrupt event is created, then this value is used as the vector, 100and the 101.Fa flags 102argument is used to specify the attributes of a handler such as 103.Dv INTR_MPSAFE . 104The 105.Fa cookiep 106argument points to a 107.Vt void * 108cookie. 109This cookie will be set to a value that uniquely identifies this handler, 110and is used to schedule the handler for execution later on. 111.Pp 112The 113.Fn swi_remove 114function is used to teardown an interrupt handler pointed to by the 115.Fa cookie 116argument. 117It detaches the interrupt handler from the associated interrupt event 118and frees its memory. 119.Pp 120The 121.Fn swi_sched 122function is used to schedule an interrupt handler and its associated thread to 123run. 124The 125.Fa cookie 126argument specifies which software interrupt handler should be scheduled to run. 127The 128.Fa flags 129argument specifies how and when the handler should be run and is a mask of one 130or more of the following flags: 131.Bl -tag -width SWI_FROMNMI 132.It Dv SWI_DELAY 133Specifies that the kernel should mark the specified handler as needing to run, 134but the kernel should not schedule the software interrupt thread to run. 135Instead, 136.Fa handler 137will be executed the next time that the software interrupt thread runs after 138being scheduled by another event. 139.It Dv SWI_FROMNMI 140Specifies that 141.Fn swi_sched 142is called from NMI context and should be careful about used KPIs. 143On platforms allowing IPI sending from NMI context it immediately wakes 144.Va clk_intr_event 145via the IPI, otherwise it works just like SWI_DELAY. 146.El 147.Pp 148.Va clk_intr_event 149is a pointer to the 150.Vt struct intr_event 151used to hang delayed handlers off of the clock interrupt, and is invoked 152directly by 153.Xr hardclock 9 . 154.Sh RETURN VALUES 155The 156.Fn swi_add 157and 158.Fn swi_remove 159functions return zero on success and non-zero on failure. 160.Sh ERRORS 161The 162.Fn swi_add 163function will fail if: 164.Bl -tag -width Er 165.It Bq Er EAGAIN 166The system-imposed limit on the total 167number of processes under execution would be exceeded. 168The limit is given by the 169.Xr sysctl 3 170MIB variable 171.Dv KERN_MAXPROC . 172.It Bq Er EINVAL 173The 174.Fa flags 175argument specifies 176.Dv INTR_ENTROPY . 177.It Bq Er EINVAL 178The 179.Fa eventp 180argument points to a hardware interrupt thread. 181.It Bq Er EINVAL 182Either of the 183.Fa name 184or 185.Fa handler 186arguments are 187.Dv NULL . 188.It Bq Er EINVAL 189The 190.Dv INTR_EXCL 191flag is specified and the interrupt event pointed to by 192.Fa eventp 193already has at least one handler, or the interrupt event already has an 194exclusive handler. 195.El 196.Pp 197The 198.Fn swi_remove 199function will fail if: 200.Bl -tag -width Er 201.It Bq Er EINVAL 202A software interrupt handler pointed to by 203.Fa cookie 204is 205.Dv NULL . 206.El 207.Sh SEE ALSO 208.Xr hardclock 9 , 209.Xr intr_event 9 , 210.Xr taskqueue 9 211.Sh HISTORY 212The 213.Fn swi_add 214and 215.Fn swi_sched 216functions first appeared in 217.Fx 5.0 . 218They replaced the 219.Fn register_swi 220function which appeared in 221.Fx 3.0 222and the 223.Fn setsoft* , 224and 225.Fn schedsoft* 226functions which date back to at least 227.Bx 4.4 . 228The 229.Fn swi_remove 230function first appeared in 231.Fx 6.1 . 232