1.\" Copyright (c) 2000 John H. Baldwin
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.\"
| 1.\" Copyright (c) 2000 John H. Baldwin
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: head/share/man/man9/swi.9 68749 2000-11-15 13:34:41Z ben $
| 25.\" $FreeBSD: head/share/man/man9/swi.9 70466 2000-12-29 09:18:45Z ru $
|
26.\"
27.Dd October 30, 2000
28.Dt SWI 9
29.Os
30.Sh NAME
31.Nm sched_swi ,
32.Nm sinthand_add
33.Nd register and schedule software interrupt handlers
34.Sh SYNOPSIS
35.Fd #include <sys/bus.h>
36.Fd #include <sys/proc.h>
37.Fd #include <sys/interrupt.h>
| 26.\"
27.Dd October 30, 2000
28.Dt SWI 9
29.Os
30.Sh NAME
31.Nm sched_swi ,
32.Nm sinthand_add
33.Nd register and schedule software interrupt handlers
34.Sh SYNOPSIS
35.Fd #include <sys/bus.h>
36.Fd #include <sys/proc.h>
37.Fd #include <sys/interrupt.h>
|
38.Vt extern struct ithd *tty_ithd;
39.Vt extern struct ithd *clk_ithd;
40.Vt extern struct intrhand *net_ih;
41.Vt extern struct intrhand *softclock_ih;
42.Vt extern struct intrhand *vm_ih;
| 38.Vt "extern struct ithd *tty_ithd;"
39.Vt "extern struct ithd *clk_ithd;"
40.Vt "extern struct intrhand *net_ih;"
41.Vt "extern struct intrhand *softclock_ih;"
42.Vt "extern struct intrhand *vm_ih;"
|
43.Ft void
44.Fn sched_swi "struct intrhand *handler" "int flags"
45.Ft struct intrhand *
46.Fo sinthand_add
47.Fa "const char *name"
48.Fa "struct ithd **thread"
49.Fa "driver_intr_t handler"
50.Fa "void *arg"
51.Fa "int pri"
52.Fa "int flags"
53.Fc
54.Sh DESCRIPTION
55These functions are used to register and schedule software interrupt handlers.
56Software interrupt handlers are attached to a software interrupt thread, just
57as hardware interrupt handlers are attached to a hardware interrupt thread.
58This means that multiple handlers can be attached to the same thread.
59Software interrupt handlers can be used to queue up less critical processing
60inside of hardware interrupt handlers so that the work can be done at a later
61time.
62Software interrupt threads are different from other kernel threads in that they
63are treated as an interrupt thread.
64This means that time spent executing these threads is counted as interrupt
65time, and that they can be run via a lightweight context switch during
66.Fn ast .
67.Pp
68The
69.Fn sinthand_add
70function is used to register a new software interrupt handler.
71The
72.Fa name
73argument is used to associate a name with a specific handler.
74This name is appended to the name of the software interrupt thread that this
75handler is attached to.
76The
77.Fa thread
78argument is an optional pointer to a
79.Li struct ithd
80pointer.
81If this argument points to an existing software interrupt thread, then this
82handler will be attached to that thread.
83Otherwise a new thread will be created, and if
84.Fa thread
85is not
86.Dv NULL ,
87then the pointer at that address to will be modified to point to the
88newly created thread.
89The
90.Fa handler
91is the function that will be called when the handler is scheduled to run.
92The
93.Fa arg
94parameter will be passed in as the only parameter to
95.Fa handler
96when the function is executed.
97The
98.Fa pri
99value specifies the priority to assign to an interrupt thread if one is created,
100and the
101.Fa flags
102argument is used to specify the attributes of a handler such as
103.Dv INTR_MPSAFE .
104.Fn sinthand_add
105returns a pointer to a
106.Li struct intrhand
107which is used later to schedule the handler to run.
108.Pp
109The
110.Fn sched_swi
111function is used to schedule an interrupt handler and its associated thread to
112run.
113The
114.Fa handler
115argument specifies which software interrupt handler should be scheduled to run.
116The
117.Fa flags
118argument specifies how and when the handler should be run and is a mask of one
119or more of the following flags:
120.Bl -tag -width SWI_NOSWITCH
121.It Dv SWI_SWITCH
122Specifies that the kernel should schedule the software interrupt thread
123associated with the specified handler to run. If lightweight context switches
124are in place, then the kernel will switch to this thread and run it
125immediately.
126.It Dv SWI_NOSWITCH
127Specifies that the kernel should schedule the software interrupt thread
128associated with the specified handler to run, but it should not attempt to
129switch to the thread immediately.
130.It Dv SWI_DELAY
131Specifies that the kernel should mark the specified handler as needing to run,
132but the kernel should not schedule the software interrupt thread to run.
133Instead,
134.Fa handler
135will be executed the next time that the software interrupt thread runs after
136being scheduled by another event.
137Attaching a handler to the clock software interrupt thread and using this flag
138when scheduling a software interrupt handler can be used to implement the
139functionality previously performed by
140.Fn setdelayed .
141.El
142.Pp
143The
144.Va tty_ithd
145and
146.Va clk_ithd
147variables contain pointers to the software interrupt threads for the tty and
148clock software interrupts, respectively.
149.Va tty_ithd
150is used to hang tty software interrupt handlers off of the same thread.
151.Va clk_ithd
152is used to hang delayed handlers off of the clock software interrupt thread so
153that the functionality of
154.Fn setdelayed
155can be obtained in conjuction with
156.Dv SWI_DELAY .
157The
158.Va net_ih ,
159.Va softclock_ih ,
160and
161.Va vm_ih
162handler cookies are used to schedule software interrupt threads to run for the
163networking stack, clock interrupt, and VM subsystem respectively.
164.Sh RETURN VALUES
165The
166.Fn sinthand_add
167function returns a pointer to the newly created
168.Li struct intrhand
169if successful or
170.Dv NULL
171on error.
172.Sh SEE ALSO
173.Xr taskqueue 9
174.Sh HISTORY
175The
176.Fn sinthand_add
177and the
178.Fn sched_swi
179functions first appeared in
180.Fx 5.0 .
181.Sh BUGS
182The
183.Fn sinthand_add
184function currently doesn't check for or allow for the
185.Dv INTR_EXCL
186flag to be used to allow a software interrupt handler to have exclusive
187access to a particular software interrupt thread.
188There is also no checking to verify that one does not add a software interrupt
189handler to a hardware interrupt thread.
190.Pp
191The
192.Fn sinthand_add
193function should really return an error code and use a
194.Fa "void **cookiep"
195argument to return a cookie that is passed in as the first argument to
196.Fn sched_swi
197instead of exposing the
198.Li struct intrhand
199type.
200.Pp
201Most of the global variables described in this manual page should not be
202global, or at the very least should not be declared in
203.Aq Pa sys/interrupt.h .
| 43.Ft void
44.Fn sched_swi "struct intrhand *handler" "int flags"
45.Ft struct intrhand *
46.Fo sinthand_add
47.Fa "const char *name"
48.Fa "struct ithd **thread"
49.Fa "driver_intr_t handler"
50.Fa "void *arg"
51.Fa "int pri"
52.Fa "int flags"
53.Fc
54.Sh DESCRIPTION
55These functions are used to register and schedule software interrupt handlers.
56Software interrupt handlers are attached to a software interrupt thread, just
57as hardware interrupt handlers are attached to a hardware interrupt thread.
58This means that multiple handlers can be attached to the same thread.
59Software interrupt handlers can be used to queue up less critical processing
60inside of hardware interrupt handlers so that the work can be done at a later
61time.
62Software interrupt threads are different from other kernel threads in that they
63are treated as an interrupt thread.
64This means that time spent executing these threads is counted as interrupt
65time, and that they can be run via a lightweight context switch during
66.Fn ast .
67.Pp
68The
69.Fn sinthand_add
70function is used to register a new software interrupt handler.
71The
72.Fa name
73argument is used to associate a name with a specific handler.
74This name is appended to the name of the software interrupt thread that this
75handler is attached to.
76The
77.Fa thread
78argument is an optional pointer to a
79.Li struct ithd
80pointer.
81If this argument points to an existing software interrupt thread, then this
82handler will be attached to that thread.
83Otherwise a new thread will be created, and if
84.Fa thread
85is not
86.Dv NULL ,
87then the pointer at that address to will be modified to point to the
88newly created thread.
89The
90.Fa handler
91is the function that will be called when the handler is scheduled to run.
92The
93.Fa arg
94parameter will be passed in as the only parameter to
95.Fa handler
96when the function is executed.
97The
98.Fa pri
99value specifies the priority to assign to an interrupt thread if one is created,
100and the
101.Fa flags
102argument is used to specify the attributes of a handler such as
103.Dv INTR_MPSAFE .
104.Fn sinthand_add
105returns a pointer to a
106.Li struct intrhand
107which is used later to schedule the handler to run.
108.Pp
109The
110.Fn sched_swi
111function is used to schedule an interrupt handler and its associated thread to
112run.
113The
114.Fa handler
115argument specifies which software interrupt handler should be scheduled to run.
116The
117.Fa flags
118argument specifies how and when the handler should be run and is a mask of one
119or more of the following flags:
120.Bl -tag -width SWI_NOSWITCH
121.It Dv SWI_SWITCH
122Specifies that the kernel should schedule the software interrupt thread
123associated with the specified handler to run. If lightweight context switches
124are in place, then the kernel will switch to this thread and run it
125immediately.
126.It Dv SWI_NOSWITCH
127Specifies that the kernel should schedule the software interrupt thread
128associated with the specified handler to run, but it should not attempt to
129switch to the thread immediately.
130.It Dv SWI_DELAY
131Specifies that the kernel should mark the specified handler as needing to run,
132but the kernel should not schedule the software interrupt thread to run.
133Instead,
134.Fa handler
135will be executed the next time that the software interrupt thread runs after
136being scheduled by another event.
137Attaching a handler to the clock software interrupt thread and using this flag
138when scheduling a software interrupt handler can be used to implement the
139functionality previously performed by
140.Fn setdelayed .
141.El
142.Pp
143The
144.Va tty_ithd
145and
146.Va clk_ithd
147variables contain pointers to the software interrupt threads for the tty and
148clock software interrupts, respectively.
149.Va tty_ithd
150is used to hang tty software interrupt handlers off of the same thread.
151.Va clk_ithd
152is used to hang delayed handlers off of the clock software interrupt thread so
153that the functionality of
154.Fn setdelayed
155can be obtained in conjuction with
156.Dv SWI_DELAY .
157The
158.Va net_ih ,
159.Va softclock_ih ,
160and
161.Va vm_ih
162handler cookies are used to schedule software interrupt threads to run for the
163networking stack, clock interrupt, and VM subsystem respectively.
164.Sh RETURN VALUES
165The
166.Fn sinthand_add
167function returns a pointer to the newly created
168.Li struct intrhand
169if successful or
170.Dv NULL
171on error.
172.Sh SEE ALSO
173.Xr taskqueue 9
174.Sh HISTORY
175The
176.Fn sinthand_add
177and the
178.Fn sched_swi
179functions first appeared in
180.Fx 5.0 .
181.Sh BUGS
182The
183.Fn sinthand_add
184function currently doesn't check for or allow for the
185.Dv INTR_EXCL
186flag to be used to allow a software interrupt handler to have exclusive
187access to a particular software interrupt thread.
188There is also no checking to verify that one does not add a software interrupt
189handler to a hardware interrupt thread.
190.Pp
191The
192.Fn sinthand_add
193function should really return an error code and use a
194.Fa "void **cookiep"
195argument to return a cookie that is passed in as the first argument to
196.Fn sched_swi
197instead of exposing the
198.Li struct intrhand
199type.
200.Pp
201Most of the global variables described in this manual page should not be
202global, or at the very least should not be declared in
203.Aq Pa sys/interrupt.h .
|