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 April 19, 2012 28.Dt SWI 9 29.Os 30.Sh NAME 31.Nm swi_add , 32.Nm swi_remove , 33.Nm swi_sched 34.Nd register and schedule software interrupt handlers 35.Sh SYNOPSIS 36.In sys/param.h 37.In sys/bus.h 38.In sys/interrupt.h 39.Vt "extern struct intr_event *tty_intr_event" ; 40.Vt "extern struct intr_event *clk_intr_event" ; 41.Vt "extern void *vm_ih" ; 42.Ft int 43.Fo swi_add 44.Fa "struct intr_event **eventp" 45.Fa "const char *name" 46.Fa "driver_intr_t handler" 47.Fa "void *arg" 48.Fa "int pri" 49.Fa "enum intr_type flags" 50.Fa "void **cookiep" 51.Fc 52.Ft int 53.Fn swi_remove "void *cookie" 54.Ft void 55.Fn swi_sched "void *cookie" "int flags" 56.Sh DESCRIPTION 57These functions are used to register and schedule software interrupt handlers. 58Software interrupt handlers are attached to a software interrupt thread, just 59as hardware interrupt handlers are attached to a hardware interrupt thread. 60Multiple handlers can be attached to the same thread. 61Software interrupt handlers can be used to queue up less critical processing 62inside of hardware interrupt handlers so that the work can be done at a later 63time. 64Software interrupt threads are different from other kernel threads in that they 65are treated as an interrupt thread. 66This means that time spent executing these threads is counted as interrupt 67time, and that they can be run via a lightweight context switch. 68.Pp 69The 70.Fn swi_add 71function is used to add a new software interrupt handler to a specified 72interrupt event. 73The 74.Fa eventp 75argument is an optional pointer to a 76.Vt struct intr_event 77pointer. 78If this argument points to an existing event that holds a list of 79interrupt handlers, then this handler will be attached to that event. 80Otherwise a new event will be created, and if 81.Fa eventp 82is not 83.Dv NULL , 84then the pointer at that address to will be modified to point to the 85newly created event. 86The 87.Fa name 88argument is used to associate a name with a specific handler. 89This name is appended to the name of the software interrupt thread that this 90handler is attached to. 91The 92.Fa handler 93argument is the function that will be executed when the handler is scheduled 94to run. 95The 96.Fa arg 97parameter will be passed in as the only parameter to 98.Fa handler 99when the function is executed. 100The 101.Fa pri 102value specifies the priority of this interrupt handler relative to other 103software interrupt handlers. 104If an interrupt event is created, then this value is used as the vector, 105and the 106.Fa flags 107argument is used to specify the attributes of a handler such as 108.Dv INTR_MPSAFE . 109The 110.Fa cookiep 111argument points to a 112.Vt void * 113cookie. 114This cookie will be set to a value that uniquely identifies this handler, 115and is used to schedule the handler for execution later on. 116.Pp 117The 118.Fn swi_remove 119function is used to teardown an interrupt handler pointed to by the 120.Fa cookie 121argument. 122It detaches the interrupt handler from the associated interrupt event 123and frees its memory. 124.Pp 125The 126.Fn swi_sched 127function is used to schedule an interrupt handler and its associated thread to 128run. 129The 130.Fa cookie 131argument specifies which software interrupt handler should be scheduled to run. 132The 133.Fa flags 134argument specifies how and when the handler should be run and is a mask of one 135or more of the following flags: 136.Bl -tag -width SWI_DELAY 137.It Dv SWI_DELAY 138Specifies that the kernel should mark the specified handler as needing to run, 139but the kernel should not schedule the software interrupt thread to run. 140Instead, 141.Fa handler 142will be executed the next time that the software interrupt thread runs after 143being scheduled by another event. 144Attaching a handler to the clock software interrupt thread and using this flag 145when scheduling a software interrupt handler can be used to implement the 146functionality performed by 147.Fn setdelayed 148in earlier versions of 149.Fx . 150.El 151.Pp 152The 153.Va tty_intr_event 154and 155.Va clk_intr_event 156variables contain pointers to the software interrupt handlers for the tty and 157clock software interrupts, respectively. 158.Va tty_intr_event 159is used to hang tty software interrupt handlers off of the same thread. 160.Va clk_intr_event 161is used to hang delayed handlers off of the clock software interrupt thread so 162that the functionality of 163.Fn setdelayed 164can be obtained in conjunction with 165.Dv SWI_DELAY . 166The 167.Va vm_ih 168handler cookie is used to schedule software interrupt threads to run for the 169VM subsystem. 170.Sh RETURN VALUES 171The 172.Fn swi_add 173and 174.Fn swi_remove 175functions return zero on success and non-zero on failure. 176.Sh ERRORS 177The 178.Fn swi_add 179function will fail if: 180.Bl -tag -width Er 181.It Bq Er EAGAIN 182The system-imposed limit on the total 183number of processes under execution would be exceeded. 184The limit is given by the 185.Xr sysctl 3 186MIB variable 187.Dv KERN_MAXPROC . 188.It Bq Er EINVAL 189The 190.Fa flags 191argument specifies 192.Dv INTR_ENTROPY . 193.It Bq Er EINVAL 194The 195.Fa eventp 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 event pointed to by 208.Fa eventp 209already has at least one handler, or the interrupt event already has an 210exclusive handler. 211.El 212.Pp 213The 214.Fn swi_remove 215function will fail if: 216.Bl -tag -width Er 217.It Bq Er EINVAL 218A software interrupt handler pointed to by 219.Fa cookie 220is 221.Dv NULL . 222.El 223.Sh SEE ALSO 224.Xr ithread 9 , 225.Xr taskqueue 9 226.Sh HISTORY 227The 228.Fn swi_add 229and 230.Fn swi_sched 231functions first appeared in 232.Fx 5.0 . 233They replaced the 234.Fn register_swi 235function which appeared in 236.Fx 3.0 237and the 238.Fn setsoft* , 239and 240.Fn schedsoft* 241functions which date back to at least 242.Bx 4.4 . 243The 244.Fn swi_remove 245function first appeared in 246.Fx 6.1 . 247.Sh BUGS 248Most of the global variables described in this manual page should not be 249global, or at the very least should not be declared in 250.In sys/interrupt.h . 251