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.\" $FreeBSD$ 25.\" 26.Dd July 25, 2020 27.Dt SWI 9 28.Os 29.Sh NAME 30.Nm swi_add , 31.Nm swi_remove , 32.Nm swi_sched 33.Nd register and schedule software interrupt handlers 34.Sh SYNOPSIS 35.In sys/param.h 36.In sys/bus.h 37.In sys/interrupt.h 38.Vt "extern struct intr_event *tty_intr_event" ; 39.Vt "extern struct intr_event *clk_intr_event" ; 40.Vt "extern void *vm_ih" ; 41.Ft int 42.Fo swi_add 43.Fa "struct intr_event **eventp" 44.Fa "const char *name" 45.Fa "driver_intr_t handler" 46.Fa "void *arg" 47.Fa "int pri" 48.Fa "enum intr_type flags" 49.Fa "void **cookiep" 50.Fc 51.Ft int 52.Fn swi_remove "void *cookie" 53.Ft void 54.Fn swi_sched "void *cookie" "int flags" 55.Sh DESCRIPTION 56These functions are used to register and schedule software interrupt handlers. 57Software interrupt handlers are attached to a software interrupt thread, just 58as hardware interrupt handlers are attached to a hardware interrupt thread. 59Multiple handlers can be attached to the same thread. 60Software interrupt handlers can be used to queue up less critical processing 61inside of hardware interrupt handlers so that the work can be done at a later 62time. 63Software interrupt threads are different from other kernel threads in that they 64are treated as an interrupt thread. 65This means that time spent executing these threads is counted as interrupt 66time, and that they can be run via a lightweight context switch. 67.Pp 68The 69.Fn swi_add 70function is used to add a new software interrupt handler to a specified 71interrupt event. 72The 73.Fa eventp 74argument is an optional pointer to a 75.Vt struct intr_event 76pointer. 77If this argument points to an existing event that holds a list of 78interrupt handlers, then this handler will be attached to that event. 79Otherwise a new event will be created, and if 80.Fa eventp 81is not 82.Dv NULL , 83then the pointer at that address to will be modified to point to the 84newly created event. 85The 86.Fa name 87argument is used to associate a name with a specific handler. 88This name is appended to the name of the software interrupt thread that this 89handler is attached to. 90The 91.Fa handler 92argument is the function that will be executed when the handler is scheduled 93to run. 94The 95.Fa arg 96parameter will be passed in as the only parameter to 97.Fa handler 98when the function is executed. 99The 100.Fa pri 101value specifies the priority of this interrupt handler relative to other 102software interrupt handlers. 103If an interrupt event is created, then this value is used as the vector, 104and the 105.Fa flags 106argument is used to specify the attributes of a handler such as 107.Dv INTR_MPSAFE . 108The 109.Fa cookiep 110argument points to a 111.Vt void * 112cookie. 113This cookie will be set to a value that uniquely identifies this handler, 114and is used to schedule the handler for execution later on. 115.Pp 116The 117.Fn swi_remove 118function is used to teardown an interrupt handler pointed to by the 119.Fa cookie 120argument. 121It detaches the interrupt handler from the associated interrupt event 122and frees its memory. 123.Pp 124The 125.Fn swi_sched 126function is used to schedule an interrupt handler and its associated thread to 127run. 128The 129.Fa cookie 130argument specifies which software interrupt handler should be scheduled to run. 131The 132.Fa flags 133argument specifies how and when the handler should be run and is a mask of one 134or more of the following flags: 135.Bl -tag -width SWI_FROMNMI 136.It Dv SWI_DELAY 137Specifies that the kernel should mark the specified handler as needing to run, 138but the kernel should not schedule the software interrupt thread to run. 139Instead, 140.Fa handler 141will be executed the next time that the software interrupt thread runs after 142being scheduled by another event. 143Attaching a handler to the clock software interrupt thread and using this flag 144when scheduling a software interrupt handler can be used to implement the 145functionality performed by 146.Fn setdelayed 147in earlier versions of 148.Fx . 149.It Dv SWI_FROMNMI 150Specifies that 151.Fn swi_sched 152is called from NMI context and should be careful about used KPIs. 153On platforms allowing IPI sending from NMI context it immediately wakes 154.Va clk_intr_event 155via the IPI, otherwise it works just like SWI_DELAY. 156.El 157.Pp 158The 159.Va tty_intr_event 160and 161.Va clk_intr_event 162variables contain pointers to the software interrupt handlers for the tty and 163clock software interrupts, respectively. 164.Va tty_intr_event 165is used to hang tty software interrupt handlers off of the same thread. 166.Va clk_intr_event 167is used to hang delayed handlers off of the clock software interrupt thread so 168that the functionality of 169.Fn setdelayed 170can be obtained in conjunction with 171.Dv SWI_DELAY . 172The 173.Va vm_ih 174handler cookie is used to schedule software interrupt threads to run for the 175VM subsystem. 176.Sh RETURN VALUES 177The 178.Fn swi_add 179and 180.Fn swi_remove 181functions return zero on success and non-zero on failure. 182.Sh ERRORS 183The 184.Fn swi_add 185function will fail if: 186.Bl -tag -width Er 187.It Bq Er EAGAIN 188The system-imposed limit on the total 189number of processes under execution would be exceeded. 190The limit is given by the 191.Xr sysctl 3 192MIB variable 193.Dv KERN_MAXPROC . 194.It Bq Er EINVAL 195The 196.Fa flags 197argument specifies 198.Dv INTR_ENTROPY . 199.It Bq Er EINVAL 200The 201.Fa eventp 202argument points to a hardware interrupt thread. 203.It Bq Er EINVAL 204Either of the 205.Fa name 206or 207.Fa handler 208arguments are 209.Dv NULL . 210.It Bq Er EINVAL 211The 212.Dv INTR_EXCL 213flag is specified and the interrupt event pointed to by 214.Fa eventp 215already has at least one handler, or the interrupt event already has an 216exclusive handler. 217.El 218.Pp 219The 220.Fn swi_remove 221function will fail if: 222.Bl -tag -width Er 223.It Bq Er EINVAL 224A software interrupt handler pointed to by 225.Fa cookie 226is 227.Dv NULL . 228.El 229.Sh SEE ALSO 230.Xr ithread 9 , 231.Xr taskqueue 9 232.Sh HISTORY 233The 234.Fn swi_add 235and 236.Fn swi_sched 237functions first appeared in 238.Fx 5.0 . 239They replaced the 240.Fn register_swi 241function which appeared in 242.Fx 3.0 243and the 244.Fn setsoft* , 245and 246.Fn schedsoft* 247functions which date back to at least 248.Bx 4.4 . 249The 250.Fn swi_remove 251function first appeared in 252.Fx 6.1 . 253.Sh BUGS 254Most of the global variables described in this manual page should not be 255global, or at the very least should not be declared in 256.In sys/interrupt.h . 257