| swi.9 (72512) | swi.9 (73797) |
|---|---|
| 1.\" Copyright (c) 2000 John H. Baldwin | 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 --- 7 unchanged lines hidden (view full) --- 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.\" | 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 --- 7 unchanged lines hidden (view full) --- 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: head/share/man/man9/swi.9 72512 2001-02-15 11:47:31Z bde $ | 25.\" $FreeBSD: head/share/man/man9/swi.9 73797 2001-03-05 23:47:34Z jhb $ |
| 26.\" 27.Dd October 30, 2000 28.Dt SWI 9 29.Os 30.Sh NAME | 26.\" 27.Dd October 30, 2000 28.Dt SWI 9 29.Os 30.Sh NAME |
| 31.Nm sched_swi , 32.Nm sinthand_add | 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> | 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" ; | 37.Fd #include <sys/interrupt.h> 38.Vt "extern struct ithd *tty_ithd" ; 39.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 | 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" |
| 48.Fa "const char *name" | 46.Fa "const char *name" |
| 49.Fa "struct ithd **thread" | |
| 50.Fa "driver_intr_t handler" 51.Fa "void *arg" 52.Fa "int pri" | 47.Fa "driver_intr_t handler" 48.Fa "void *arg" 49.Fa "int pri" |
| 53.Fa "int flags" | 50.Fa "enum intr_type flags" 51.Fa "void **cookiep" |
| 54.Fc | 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. | 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. | 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 | 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 . | 66time, and that they can be run via a lightweight context switch. |
| 68.Pp 69The | 67.Pp 68The |
| 70.Fn sinthand_add | 69.Fn swi_add |
| 71function is used to register a new software interrupt handler. 72The | 70function is used to register a new software interrupt handler. 71The |
| 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 | 72.Fa ithdp |
| 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 | 73argument is an optional pointer to a 74.Li 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 |
| 85.Fa thread | 79.Fa ithdp |
| 86is not 87.Dv NULL , 88then the pointer at that address to will be modified to point to the 89newly created thread. 90The | 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 |
|
| 91.Fa handler | 90.Fa handler |
| 92is the function that will be called when the handler is scheduled to run. | 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 | 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, | 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, |
| 101and the 102.Fa flags 103argument is used to specify the attributes of a handler such as 104.Dv INTR_MPSAFE . | 103and the 104.Fa flags 105argument is used to specify the attributes of a handler such as 106.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. | 107The 108.Fn cookiep 109argument points to a 110.Li 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. |
| 109.Pp 110The | 114.Pp 115The |
| 111.Fn sched_swi | 116.Fn swi_sched |
| 112function is used to schedule an interrupt handler and its associated thread to 113run. 114The | 117function is used to schedule an interrupt handler and its associated thread to 118run. 119The |
| 115.Fa handler | 120.Fa cookie |
| 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 --- 35 unchanged lines hidden (view full) --- 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 | 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 --- 35 unchanged lines hidden (view full) --- 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 |
| 167.Fn sinthand_add 168function returns a pointer to the newly created 169.Li struct intrhand 170if successful or 171.Dv NULL 172on error. | 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 |
| 173.Sh SEE ALSO | 212.Sh SEE ALSO |
| 213.Xr ithread 9 , |
|
| 174.Xr taskqueue 9 175.Sh HISTORY 176The | 214.Xr taskqueue 9 215.Sh HISTORY 216The |
| 177.Fn sinthand_add 178and the 179.Fn sched_swi | 217.Fn swi_add 218and 219.Fn swi_sched |
| 180functions first appeared in 181.Fx 5.0 . | 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 . |
|
| 182.Sh BUGS | 232.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 | 233.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 . | 234Most of the global variables described in this manual page should not be 235global, or at the very least should not be declared in 236.Aq Pa sys/interrupt.h . |