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