1 .\" Copyright (c) 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
30 .Nm ithread_add_handler ,
33 .Nm ithread_priority ,
34 .Nm ithread_remove_handler ,
36 .Nd kernel interrupt threads
42 .Fo ithread_add_handler
43 .Fa "struct ithd *ithread"
44 .Fa "const char *name"
45 .Fa "driver_intr_t handler"
48 .Fa "enum intr_type flags"
53 .Fa "struct ithd **ithread"
56 .Fa "void (*disable)(int)"
57 .Fa "void (*enable)(int)"
62 .Fn ithread_destroy "struct ithd *ithread"
64 .Fn ithread_priority "enum intr_type flags"
66 .Fn ithread_remove_handler "void *cookie"
68 .Fn ithread_schedule "struct ithd *ithread" "int do_switch"
70 Interrupt threads are kernel threads that run a list of handlers when
71 triggered by either a hardware or software interrupt.
72 Each interrupt handler has a name, handler function, handler argument,
73 priority, and various flags.
74 Each interrupt thread maintains a list of handlers sorted by priority.
75 This results in higher priority handlers being executed prior to lower
77 Each thread assumes the priority of its highest priority handler for its
80 if it has no handlers.
81 Interrupt threads are also associated with a single interrupt source,
82 represented as a vector number.
86 function creates a new interrupt thread.
91 pointer that will point to the newly created thread upon success.
94 argument specifies the interrupt source to associate this thread with.
97 argument is a mask of properties of this thread.
98 The only valid flag currently for
102 to specify that this interrupt thread is a software interrupt.
107 arguments specify optional functions used to enable and disable this
108 interrupt thread's interrupt source.
109 The functions receive the vector corresponding to the thread's interrupt
110 source as their only argument.
111 The remaining arguments form a
113 argument list that is used to build the base name of the new ithread.
114 The full name of an interrupt thread is formed by concatenating the base
115 name of an interrupt thread with the names of all of its interrupt handlers.
119 function destroys a previously created interrupt thread by releasing its
120 resources and arranging for the backing kernel thread to terminate.
121 An interrupt thread can only be destroyed if it has no handlers remaining.
124 .Fn ithread_add_handler
125 function adds a new handler to an existing interrupt thread specified by
129 argument specifies a name for this handler.
134 arguments provide the function to execute for this handler and an argument
138 argument specifies the priority of this handler and is used both in sorting
139 it in relation to the other handlers for this thread and to specify the
140 priority of the backing kernel thread.
143 argument can be used to specify properties of this handler as defined in
149 then it will be assigned a cookie that can be used later to remove this
153 .Fn ithread_remove_handler
154 removes a handler from an interrupt thread.
157 argument specifies the handler to remove from its thread.
161 function schedules an interrupt thread to run.
164 argument is non-zero and the interrupt thread is idle, then a context switch
165 will be forced after putting the interrupt thread on the run queue.
169 function translates the
171 interrupt flags into interrupt handler priorities.
173 The interrupt flags not related to the type of a particular interrupt
175 can be used to specify additional properties of both hardware and software
179 flag specifies that this handler cannot share an interrupt thread with
183 flag specifies that this handler is MP safe in that it does not need the
184 Giant mutex to be held while it is executed.
187 flag specifies that the interrupt source this handler is tied to is a good
188 source of entropy, and thus that entropy should be gathered when an interrupt
189 from the handler's source triggers.
192 flag is not valid for software interrupt handlers.
194 It is not permitted to sleep in an interrupt thread; hence, any memory
195 or zone allocations in an interrupt thread should be specified with the
198 Any allocation errors must be handled thereafter.
201 .Fn ithread_add_handler ,
203 .Fn ithread_destroy ,
204 .Fn ithread_remove_handler ,
207 functions return zero on success and non-zero on failure.
210 function returns a process priority corresponding to the passed in interrupt
215 function demonstrates the use of
218 .Fn ithread_add_handler .
219 .Bd -literal -offset indent
221 swi_add(struct ithd **ithdp, const char *name, driver_intr_t handler,
222 void *arg, int pri, enum intr_type flags, void **cookiep)
228 if (flags & INTR_ENTROPY)
231 ithd = (ithdp != NULL) ? *ithdp : NULL;
234 if ((ithd->it_flags & IT_SOFT) == 0)
237 error = ithread_create(&ithd, pri, IT_SOFT, NULL, NULL,
245 return (ithread_add_handler(ithd, name, handler, arg, pri + PI_SOFT,
251 .Fn ithread_add_handler
252 function will fail if:
265 flag is specified and the interrupt thread
267 already has at least one handler, or the interrupt thread
269 already has an exclusive handler.
271 Could not allocate needed memory for this handler.
276 function will fail if:
279 The system-imposed limit on the total
280 number of processes under execution would be exceeded.
281 The limit is given by the
292 Could not allocate needed memory for this interrupt thread.
297 function will fail if:
305 The interrupt thread pointed to by
307 has at least one handler.
311 .Fn ithread_remove_handler
312 function will fail if:
323 function will fail if:
331 The interrupt thread pointed to by
333 has no interrupt handlers.
341 Interrupt threads and their corresponding API first appeared in
346 represents both an interrupt source and an interrupt thread.
347 There should be a separate
349 that contains a vector number, enable and disable functions, etc.\& that
350 an ithread holds a reference to.