1 .\" Copyright (c) 2000-2001 John H. Baldwin <jhb@FreeBSD.org>
3 .\" Redistribution and use in source and binary forms, with or without
4 .\" modification, are permitted provided that the following conditions
6 .\" 1. Redistributions of source code must retain the above copyright
7 .\" notice, this list of conditions and the following disclaimer.
8 .\" 2. Redistributions in binary form must reproduce the above copyright
9 .\" notice, this list of conditions and the following disclaimer in the
10 .\" documentation and/or other materials provided with the distribution.
12 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
13 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
14 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
15 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
16 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
17 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
18 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
19 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
20 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
21 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33 .Nd register and schedule software interrupt handlers
38 .Vt "extern struct intr_event *tty_intr_event" ;
39 .Vt "extern struct intr_event *clk_intr_event" ;
40 .Vt "extern void *vm_ih" ;
43 .Fa "struct intr_event **eventp"
44 .Fa "const char *name"
45 .Fa "driver_intr_t handler"
48 .Fa "enum intr_type flags"
52 .Fn swi_remove "void *cookie"
54 .Fn swi_sched "void *cookie" "int flags"
56 These functions are used to register and schedule software interrupt handlers.
57 Software interrupt handlers are attached to a software interrupt thread, just
58 as hardware interrupt handlers are attached to a hardware interrupt thread.
59 Multiple handlers can be attached to the same thread.
60 Software interrupt handlers can be used to queue up less critical processing
61 inside of hardware interrupt handlers so that the work can be done at a later
63 Software interrupt threads are different from other kernel threads in that they
64 are treated as an interrupt thread.
65 This means that time spent executing these threads is counted as interrupt
66 time, and that they can be run via a lightweight context switch.
70 function is used to add a new software interrupt handler to a specified
74 argument is an optional pointer to a
77 If this argument points to an existing event that holds a list of
78 interrupt handlers, then this handler will be attached to that event.
79 Otherwise a new event will be created, and if
83 then the pointer at that address to will be modified to point to the
87 argument is used to associate a name with a specific handler.
88 This name is appended to the name of the software interrupt thread that this
89 handler is attached to.
92 argument is the function that will be executed when the handler is scheduled
96 parameter will be passed in as the only parameter to
98 when the function is executed.
101 value specifies the priority of this interrupt handler relative to other
102 software interrupt handlers.
103 If an interrupt event is created, then this value is used as the vector,
106 argument is used to specify the attributes of a handler such as
113 This cookie will be set to a value that uniquely identifies this handler,
114 and is used to schedule the handler for execution later on.
118 function is used to teardown an interrupt handler pointed to by the
121 It detaches the interrupt handler from the associated interrupt event
122 and frees its memory.
126 function is used to schedule an interrupt handler and its associated thread to
130 argument specifies which software interrupt handler should be scheduled to run.
133 argument specifies how and when the handler should be run and is a mask of one
134 or more of the following flags:
135 .Bl -tag -width SWI_FROMNMI
137 Specifies that the kernel should mark the specified handler as needing to run,
138 but the kernel should not schedule the software interrupt thread to run.
141 will be executed the next time that the software interrupt thread runs after
142 being scheduled by another event.
143 Attaching a handler to the clock software interrupt thread and using this flag
144 when scheduling a software interrupt handler can be used to implement the
145 functionality performed by
147 in earlier versions of
152 is called from NMI context and should be careful about used KPIs.
153 On platforms allowing IPI sending from NMI context it immediately wakes
155 via the IPI, otherwise it works just like SWI_DELAY.
162 variables contain pointers to the software interrupt handlers for the tty and
163 clock software interrupts, respectively.
165 is used to hang tty software interrupt handlers off of the same thread.
167 is used to hang delayed handlers off of the clock software interrupt thread so
168 that the functionality of
170 can be obtained in conjunction with
174 handler cookie is used to schedule software interrupt threads to run for the
181 functions return zero on success and non-zero on failure.
185 function will fail if:
188 The system-imposed limit on the total
189 number of processes under execution would be exceeded.
190 The limit is given by the
202 argument points to a hardware interrupt thread.
213 flag is specified and the interrupt event pointed to by
215 already has at least one handler, or the interrupt event already has an
221 function will fail if:
224 A software interrupt handler pointed to by
237 functions first appeared in
241 function which appeared in
247 functions which date back to at least
251 function first appeared in
254 Most of the global variables described in this manual page should not be
255 global, or at the very least should not be declared in
256 .In sys/interrupt.h .