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 April 19, 2012 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_DELAY 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.El 150.Pp 151The 152.Va tty_intr_event 153and 154.Va clk_intr_event 155variables contain pointers to the software interrupt handlers for the tty and 156clock software interrupts, respectively. 157.Va tty_intr_event 158is used to hang tty software interrupt handlers off of the same thread. 159.Va clk_intr_event 160is used to hang delayed handlers off of the clock software interrupt thread so 161that the functionality of 162.Fn setdelayed 163can be obtained in conjunction with 164.Dv SWI_DELAY . 165The 166.Va vm_ih 167handler cookie is used to schedule software interrupt threads to run for the 168VM subsystem. 169.Sh RETURN VALUES 170The 171.Fn swi_add 172and 173.Fn swi_remove 174functions return zero on success and non-zero on failure. 175.Sh ERRORS 176The 177.Fn swi_add 178function will fail if: 179.Bl -tag -width Er 180.It Bq Er EAGAIN 181The system-imposed limit on the total 182number of processes under execution would be exceeded. 183The limit is given by the 184.Xr sysctl 3 185MIB variable 186.Dv KERN_MAXPROC . 187.It Bq Er EINVAL 188The 189.Fa flags 190argument specifies 191.Dv INTR_ENTROPY . 192.It Bq Er EINVAL 193The 194.Fa eventp 195argument points to a hardware interrupt thread. 196.It Bq Er EINVAL 197Either of the 198.Fa name 199or 200.Fa handler 201arguments are 202.Dv NULL . 203.It Bq Er EINVAL 204The 205.Dv INTR_EXCL 206flag is specified and the interrupt event pointed to by 207.Fa eventp 208already has at least one handler, or the interrupt event already has an 209exclusive handler. 210.El 211.Pp 212The 213.Fn swi_remove 214function will fail if: 215.Bl -tag -width Er 216.It Bq Er EINVAL 217A software interrupt handler pointed to by 218.Fa cookie 219is 220.Dv NULL . 221.El 222.Sh SEE ALSO 223.Xr ithread 9 , 224.Xr taskqueue 9 225.Sh HISTORY 226The 227.Fn swi_add 228and 229.Fn swi_sched 230functions first appeared in 231.Fx 5.0 . 232They replaced the 233.Fn register_swi 234function which appeared in 235.Fx 3.0 236and the 237.Fn setsoft* , 238and 239.Fn schedsoft* 240functions which date back to at least 241.Bx 4.4 . 242The 243.Fn swi_remove 244function first appeared in 245.Fx 6.1 . 246.Sh BUGS 247Most of the global variables described in this manual page should not be 248global, or at the very least should not be declared in 249.In sys/interrupt.h . 250