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.In sys/param.h 36.In sys/bus.h 37.In 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 *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 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.Fa 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_DELAY 127.It Dv SWI_DELAY 128Specifies that the kernel should mark the specified handler as needing to run, 129but the kernel should not schedule the software interrupt thread to run. 130Instead, 131.Fa handler 132will be executed the next time that the software interrupt thread runs after 133being scheduled by another event. 134Attaching a handler to the clock software interrupt thread and using this flag 135when scheduling a software interrupt handler can be used to implement the 136functionality performed by 137.Fn setdelayed 138in earlier versions of 139.Fx . 140.El 141.Pp 142The 143.Va tty_ithd 144and 145.Va clk_ithd 146variables contain pointers to the software interrupt threads for the tty and 147clock software interrupts, respectively. 148.Va tty_ithd 149is used to hang tty software interrupt handlers off of the same thread. 150.Va clk_ithd 151is used to hang delayed handlers off of the clock software interrupt thread so 152that the functionality of 153.Fn setdelayed 154can be obtained in conjunction with 155.Dv SWI_DELAY . 156The 157.Va net_ih , 158.Va softclock_ih , 159and 160.Va vm_ih 161handler cookies are used to schedule software interrupt threads to run for the 162networking stack, clock interrupt, and VM subsystem respectively. 163.Sh RETURN VALUES 164The 165.Fn swi_add 166function returns zero on success and non-zero on failure. 167.Sh ERRORS 168The 169.Fn swi_add 170function will fail if: 171.Bl -tag -width Er 172.It Bq Er EAGAIN 173The system-imposed limit on the total 174number of processes under execution would be exceeded. 175The limit is given by the 176.Xr sysctl 3 177MIB variable 178.Dv KERN_MAXPROC . 179.It Bq Er EINVAL 180The 181.Fa flags 182argument specifies either 183.Dv INTR_ENTROPY 184or 185.Dv INTR_FAST . 186.It Bq Er EINVAL 187The 188.Fa ithdp 189argument points to a hardware interrupt thread. 190.It Bq Er EINVAL 191Either of the 192.Fa name 193or 194.Fa handler 195arguments are 196.Dv NULL . 197.It Bq Er EINVAL 198The 199.Dv INTR_EXCL 200flag is specified and the interrupt thread pointed to by 201.Fa ithdp 202already has at least one handler, or the interrupt thread already has an 203exclusive handler. 204.El 205.Sh SEE ALSO 206.Xr ithread 9 , 207.Xr taskqueue 9 208.Sh HISTORY 209The 210.Fn swi_add 211and 212.Fn swi_sched 213functions first appeared in 214.Fx 5.0 . 215They replaced the 216.Fn register_swi 217function which appeared in 218.Fx 3.0 219and the 220.Fn setsoft* , 221and 222.Fn schedsoft* 223functions which date back to at least 224.Bx 4.4 . 225.Sh BUGS 226Most of the global variables described in this manual page should not be 227global, or at the very least should not be declared in 228.In sys/interrupt.h . 229