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