1.\" Copyright (c) 2000 John H. Baldwin 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 sched_swi , 32.Nm sinthand_add 33.Nd register and schedule software interrupt handlers 34.Sh SYNOPSIS 35.Fd #include <sys/bus.h> 36.Fd #include <sys/proc.h> 37.Fd #include <sys/interrupt.h> 38.Vt extern struct ithd *tty_ithd; 39.Vt extern struct ithd *clk_ithd; 40.Vt extern struct intrhand *net_ih; 41.Vt extern struct intrhand *softclock_ih; 42.Vt extern struct intrhand *vm_ih; 43.Ft void 44.Fn sched_swi "struct intrhand *handler" "int flags" 45.Ft struct intrhand * 46.Fo sinthand_add 47.Fa "const char *name" 48.Fa "struct ithd **thread" 49.Fa "driver_intr_t handler" 50.Fa "void *arg" 51.Fa "int pri" 52.Fa "int flags" 53.Fc 54.Sh DESCRIPTION 55These functions are used to register and schedule software interrupt handlers. 56Software interrupt handlers are attached to a software interrupt thread, just 57as hardware interrupt handlers are attached to a hardware interrupt thread. 58This means that multiple handlers can be attached to the same thread. 59Software interrupt handlers can be used to queue up less critical processing 60inside of hardware interrupt handlers so that the work can be done at a later 61time. 62Software interrupt threads are different from other kernel threads in that they 63are treated as an interrupt thread. 64This means that time spent executing these threads is counted as interrupt 65time, and that they can be run via a lightweight context switch during 66.Fn ast . 67.Pp 68The 69.Fn sinthand_add 70function is used to register a new software interrupt handler. 71The 72.Fa name 73argument is used to associate a name with a specific handler. 74This name is appended to the name of the software interrupt thread that this 75handler is attached to. 76The 77.Fa thread 78argument is an optional pointer to a 79.Li struct ithd 80pointer. 81If this argument points to an existing software interrupt thread, then this 82handler will be attached to that thread. 83Otherwise a new thread will be created, and if 84.Fa thread 85is not 86.Dv NULL , 87then the pointer at that address to will be modified to point to the 88newly created thread. 89The 90.Fa handler 91is the function that will be called when the handler is scheduled to 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 to assign to an interrupt thread if one is created, 100and the 101.Fa flags 102argument is used to specify the attributes of a handler such as 103.Dv INTR_MPSAFE . 104.Fn sinthand_add 105returns a pointer to a 106.Li struct intrhand 107which is used later to schedule the handler to run. 108.Pp 109The 110.Fn sched_swi 111function is used to schedule an interrupt handler and its associated thread to 112run. 113The 114.Fa handler 115argument specifies which software interrupt handler should be scheduled to run. 116The 117.Fa flags 118argument specifies how and when the handler should be run and is a mask of one 119or more of the following flags: 120.Bl -tag -width SWI_NOSWITCH 121.It Dv SWI_SWITCH 122Specifies that the kernel should schedule the software interrupt thread 123associated with the specified handler to run. If lightweight context switches 124are in place, then the kernel will switch to this thread and run it 125immediately. 126.It Dv SWI_NOSWITCH 127Specifies that the kernel should schedule the software interrupt thread 128associated with the specified handler to run, but it should not attempt to 129switch to the thread immediately. 130.It Dv SWI_DELAY 131Specifies that the kernel should mark the specified handler as needing to run, 132but the kernel should not schedule the software interrupt thread to run. 133Instead, 134.Fa handler 135will be executed the next time that the software interrupt thread runs after 136being scheduled by another event. 137Attaching a handler to the clock software interrupt thread and using this flag 138when scheduling a software interrupt handler can be used to implement the 139functionality previously performed by 140.Fn setdelayed . 141.El 142.Pp 143The 144.Va tty_ithd 145and 146.Va clk_ithd 147variables contain pointers to the software interrupt threads for the tty and 148clock software interrupts, respectively. 149.Va tty_ithd 150is used to hang tty software interrupt handlers off of the same thread. 151.Va clk_ithd 152is used to hang delayed handlers off of the clock software interrupt thread so 153that the functionality of 154.Fn setdelayed 155can be obtained in conjuction with 156.Dv SWI_DELAY . 157The 158.Va net_ih , 159.Va softclock_ih , 160and 161.Va vm_ih 162handler cookies are used to schedule software interrupt threads to run for the 163networking stack, clock interrupt, and VM subsystem respectively. 164.Sh RETURN VALUES 165The 166.Fn sinthand_add 167function returns a pointer to the newly created 168.Li struct intrhand 169if successful or 170.Dv NULL 171on error. 172.Sh SEE ALSO 173.Xr taskqueue 9 174.Sh HISTORY 175The 176.Fn sinthand_add 177and the 178.Fn sched_swi 179functions first appeared in 180.Fx 5.0 . 181.Sh BUGS 182The 183.Fn sinthand_add 184function currently doesn't check for or allow for the 185.Dv INTR_EXCL 186flag to be used to allow a software interrupt handler to have exclusive 187access to a particular software interrupt thread. 188There is also no checking to verify that one does not add a software interrupt 189handler to a hardware interrupt thread. 190.Pp 191The 192.Fn sinthand_add 193function should really return an error code and use a 194.Fa "void **cookiep" 195argument to return a cookie that is passed in as the first argument to 196.Fn sched_swi 197instead of exposing the 198.Li struct intrhand 199type. 200.Pp 201Most of the global variables described in this manual page should not be 202global, or at the very least should not be declared in 203.Aq Pa sys/interrupt.h . 204