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