1.\" Copyright (c) 2000-2001 John H. Baldwin <jhb@FreeBSD.org> 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd October 30, 2000 28.Dt SWI 9 29.Os 30.Sh NAME 31.Nm swi_add , 32.Nm swi_sched 33.Nd register and schedule software interrupt handlers 34.Sh SYNOPSIS 35.Fd #include <sys/param.h> 36.Fd #include <sys/bus.h> 37.Fd #include <sys/interrupt.h> 38.Vt "extern struct ithd *tty_ithd" ; 39.Vt "extern struct ithd *clk_ithd" ; 40.Vt "extern void *net_ih" ; 41.Vt "extern void *softclock_ih" ; 42.Vt "extern void *vm_ih" ; 43.Ft int 44.Fo swi_add 45.Fa "struct ithd **ithdp" 46.Fa "const char *name" 47.Fa "driver_intr_t handler" 48.Fa "void *arg" 49.Fa "int pri" 50.Fa "enum intr_type flags" 51.Fa "void **cookiep" 52.Fc 53.Ft void 54.Fn swi_sched "void *handler" "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 register a new software interrupt handler. 71The 72.Fa ithdp 73argument is an optional pointer to a 74.Vt struct ithd 75pointer. 76If this argument points to an existing software interrupt thread, then this 77handler will be attached to that thread. 78Otherwise a new thread will be created, and if 79.Fa ithdp 80is not 81.Dv NULL , 82then the pointer at that address to will be modified to point to the 83newly created thread. 84The 85.Fa name 86argument is used to associate a name with a specific handler. 87This name is appended to the name of the software interrupt thread that this 88handler is attached to. 89The 90.Fa handler 91argument is the function that will be executed when the handler is scheduled 92to run. 93The 94.Fa arg 95parameter will be passed in as the only parameter to 96.Fa handler 97when the function is executed. 98The 99.Fa pri 100value specifies the priority of this interrupt handler relative to other 101software interrupt handlers. 102If an interrupt thread is created, then this value is used as the vector, 103and the 104.Fa flags 105argument is used to specify the attributes of a handler such as 106.Dv INTR_MPSAFE . 107The 108.Fn cookiep 109argument points to a 110.Vt void * 111cookie. 112This cookie will be set to a value that uniquely identifies this handler, 113and is used to schedule the handler for execution later on. 114.Pp 115The 116.Fn swi_sched 117function is used to schedule an interrupt handler and its associated thread to 118run. 119The 120.Fa cookie 121argument specifies which software interrupt handler should be scheduled to run. 122The 123.Fa flags 124argument specifies how and when the handler should be run and is a mask of one 125or more of the following flags: 126.Bl -tag -width SWI_NOSWITCH 127.It Dv SWI_SWITCH 128Specifies that the kernel should schedule the software interrupt thread 129associated with the specified handler to run. If lightweight context switches 130are in place, then the kernel will switch to this thread and run it 131immediately. 132.It Dv SWI_NOSWITCH 133Specifies that the kernel should schedule the software interrupt thread 134associated with the specified handler to run, but it should not attempt to 135switch to the thread immediately. 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 previously performed by 146.Fn setdelayed . 147.El 148.Pp 149The 150.Va tty_ithd 151and 152.Va clk_ithd 153variables contain pointers to the software interrupt threads for the tty and 154clock software interrupts, respectively. 155.Va tty_ithd 156is used to hang tty software interrupt handlers off of the same thread. 157.Va clk_ithd 158is used to hang delayed handlers off of the clock software interrupt thread so 159that the functionality of 160.Fn setdelayed 161can be obtained in conjuction with 162.Dv SWI_DELAY . 163The 164.Va net_ih , 165.Va softclock_ih , 166and 167.Va vm_ih 168handler cookies are used to schedule software interrupt threads to run for the 169networking stack, clock interrupt, and VM subsystem respectively. 170.Sh RETURN VALUES 171The 172.Fn swi_add 173function returns zero on success and non-zero on failure. 174.Sh ERRORS 175The 176.Fn swi_add 177function will fail if: 178.Bl -tag -width Er 179.It Bq Er EAGAIN 180The system-imposed limit on the total 181number of processes under execution would be exceeded. 182The limit is given by the 183.Xr sysctl 3 184MIB variable 185.Dv KERN_MAXPROC . 186.It Bq Er EINVAL 187The 188.Fa flags 189argument specifies either 190.Dv INTR_ENTROPY 191or 192.Dv INTR_FAST . 193.It Bq Er EINVAL 194The 195.Fa ithdp 196argument points to a hardware interrupt thread. 197.It Bq Er EINVAL 198Either of the 199.Fa name 200or 201.Fa handler 202arguments are 203.Dv NULL . 204.It Bq Er EINVAL 205The 206.Dv INTR_EXCL 207flag is specified and the interrupt thread pointed to by 208.Fa ithdp 209already has at least one handler, or the interrupt thread already has an 210exclusive handler. 211.El 212.Sh SEE ALSO 213.Xr ithread 9 , 214.Xr taskqueue 9 215.Sh HISTORY 216The 217.Fn swi_add 218and 219.Fn swi_sched 220functions first appeared in 221.Fx 5.0 . 222They replaced the 223.Fn register_swi 224function which appeared in 225.Fx 3.0 226and the 227.Fn setsoft* , 228and 229.Fn schedsoft* 230functions which date back to at least 231.Bx 4.4 . 232.Sh BUGS 233Most of the global variables described in this manual page should not be 234global, or at the very least should not be declared in 235.Aq Pa sys/interrupt.h . 236