xref: /freebsd/share/man/man9/swi.9 (revision 61e21613) 
1.\" Copyright (c) 2000-2001 John H. Baldwin <jhb@FreeBSD.org>
2.\"
3.\" Redistribution and use in source and binary forms, with or without
4.\" modification, are permitted provided that the following conditions
5.\" are met:
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.
11.\"
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
22.\" SUCH DAMAGE.
23.\"
24.Dd October 12, 2022
25.Dt SWI 9
26.Os
27.Sh NAME
28.Nm swi_add ,
29.Nm swi_remove ,
30.Nm swi_sched
31.Nd register and schedule software interrupt handlers
32.Sh SYNOPSIS
33.In sys/param.h
34.In sys/bus.h
35.In sys/interrupt.h
36.Vt "extern struct intr_event *clk_intr_event" ;
37.Ft int
38.Fo swi_add
39.Fa "struct intr_event **eventp"
40.Fa "const char *name"
41.Fa "driver_intr_t handler"
42.Fa "void *arg"
43.Fa "int pri"
44.Fa "enum intr_type flags"
45.Fa "void **cookiep"
46.Fc
47.Ft int
48.Fn swi_remove "void *cookie"
49.Ft void
50.Fn swi_sched "void *cookie" "int flags"
51.Sh DESCRIPTION
52These functions are used to register and schedule software interrupt handlers.
53Software interrupt handlers are attached to a software interrupt thread, just
54as hardware interrupt handlers are attached to a hardware interrupt thread.
55Multiple handlers can be attached to the same thread.
56Software interrupt handlers can be used to queue up less critical processing
57inside of hardware interrupt handlers so that the work can be done at a later
58time.
59Software interrupt threads are different from other kernel threads in that they
60are treated as an interrupt thread.
61This means that time spent executing these threads is counted as interrupt
62time, and that they can be run via a lightweight context switch.
63.Pp
64The
65.Fn swi_add
66function is used to add a new software interrupt handler to a specified
67interrupt event.
68The
69.Fa eventp
70argument is an optional pointer to a
71.Vt struct intr_event
72pointer.
73If this argument points to an existing event that holds a list of
74interrupt handlers, then this handler will be attached to that event.
75Otherwise a new event will be created, and if
76.Fa eventp
77is not
78.Dv NULL ,
79then the pointer at that address to will be modified to point to the
80newly created event.
81The
82.Fa name
83argument is used to associate a name with a specific handler.
84This name is appended to the name of the software interrupt thread that this
85handler is attached to.
86The
87.Fa handler
88argument is the function that will be executed when the handler is scheduled
89to run.
90The
91.Fa arg
92parameter will be passed in as the only parameter to
93.Fa handler
94when the function is executed.
95The
96.Fa pri
97value specifies the priority of this interrupt handler relative to other
98software interrupt handlers.
99If an interrupt event is created, then this value is used as the vector,
100and the
101.Fa flags
102argument is used to specify the attributes of a handler such as
103.Dv INTR_MPSAFE .
104The
105.Fa cookiep
106argument points to a
107.Vt void *
108cookie.
109This cookie will be set to a value that uniquely identifies this handler,
110and is used to schedule the handler for execution later on.
111.Pp
112The
113.Fn swi_remove
114function is used to teardown an interrupt handler pointed to by the
115.Fa cookie
116argument.
117It detaches the interrupt handler from the associated interrupt event
118and frees its memory.
119.Pp
120The
121.Fn swi_sched
122function is used to schedule an interrupt handler and its associated thread to
123run.
124The
125.Fa cookie
126argument specifies which software interrupt handler should be scheduled to run.
127The
128.Fa flags
129argument specifies how and when the handler should be run and is a mask of one
130or more of the following flags:
131.Bl -tag -width SWI_FROMNMI
132.It Dv SWI_DELAY
133Specifies that the kernel should mark the specified handler as needing to run,
134but the kernel should not schedule the software interrupt thread to run.
135Instead,
136.Fa handler
137will be executed the next time that the software interrupt thread runs after
138being scheduled by another event.
139.It Dv SWI_FROMNMI
140Specifies that
141.Fn swi_sched
142is called from NMI context and should be careful about used KPIs.
143On platforms allowing IPI sending from NMI context it immediately wakes
144.Va clk_intr_event
145via the IPI, otherwise it works just like SWI_DELAY.
146.El
147.Pp
148.Va clk_intr_event
149is a pointer to the
150.Vt struct intr_event
151used to hang delayed handlers off of the clock interrupt, and is invoked
152directly by
153.Xr hardclock 9 .
154.Sh RETURN VALUES
155The
156.Fn swi_add
157and
158.Fn swi_remove
159functions return zero on success and non-zero on failure.
160.Sh ERRORS
161The
162.Fn swi_add
163function will fail if:
164.Bl -tag -width Er
165.It Bq Er EAGAIN
166The system-imposed limit on the total
167number of processes under execution would be exceeded.
168The limit is given by the
169.Xr sysctl 3
170MIB variable
171.Dv KERN_MAXPROC .
172.It Bq Er EINVAL
173The
174.Fa flags
175argument specifies
176.Dv INTR_ENTROPY .
177.It Bq Er EINVAL
178The
179.Fa eventp
180argument points to a hardware interrupt thread.
181.It Bq Er EINVAL
182Either of the
183.Fa name
184or
185.Fa handler
186arguments are
187.Dv NULL .
188.It Bq Er EINVAL
189The
190.Dv INTR_EXCL
191flag is specified and the interrupt event pointed to by
192.Fa eventp
193already has at least one handler, or the interrupt event already has an
194exclusive handler.
195.El
196.Pp
197The
198.Fn swi_remove
199function will fail if:
200.Bl -tag -width Er
201.It Bq Er EINVAL
202A software interrupt handler pointed to by
203.Fa cookie
204is
205.Dv NULL .
206.El
207.Sh SEE ALSO
208.Xr hardclock 9 ,
209.Xr intr_event 9 ,
210.Xr taskqueue 9
211.Sh HISTORY
212The
213.Fn swi_add
214and
215.Fn swi_sched
216functions first appeared in
217.Fx 5.0 .
218They replaced the
219.Fn register_swi
220function which appeared in
221.Fx 3.0
222and the
223.Fn setsoft* ,
224and
225.Fn schedsoft*
226functions which date back to at least
227.Bx 4.4 .
228The
229.Fn swi_remove
230function first appeared in
231.Fx 6.1 .
232