1 .\" Copyright (c) 2001 John H. Baldwin <jhb@FreeBSD.org>
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
31 .Nm ithread_add_handler ,
34 .Nm ithread_priority ,
35 .Nm ithread_remove_handler ,
37 .Nd kernel interrupt threads
43 .Fo ithread_add_handler
44 .Fa "struct ithd *ithread"
45 .Fa "const char *name"
46 .Fa "driver_intr_t handler"
49 .Fa "enum intr_type flags"
54 .Fa "struct ithd **ithread"
57 .Fa "void (*disable)(int)"
58 .Fa "void (*enable)(int)"
63 .Fn ithread_destroy "struct ithd *ithread"
65 .Fn ithread_priority "enum intr_type flags"
67 .Fn ithread_remove_handler "void *cookie"
69 .Fn ithread_schedule "struct ithd *ithread" "int do_switch"
71 Interrupt threads are kernel threads that run a list of handlers when
72 triggered by either a hardware or software interrupt.
73 Each interrupt handler has a name, handler function, handler argument,
74 priority, and various flags.
75 Each interrupt thread maintains a list of handlers sorted by priority.
76 This results in higher priority handlers being executed prior to lower
78 Each thread assumes the priority of its highest priority handler for its
81 if it has no handlers.
82 Interrupt threads are also associated with a single interrupt source,
83 represented as a vector number.
87 function creates a new interrupt thread.
92 pointer that will point to the newly created thread upon success.
95 argument specifies the interrupt source to associate this thread with.
98 argument is a mask of properties of this thread.
99 The only valid flag currently for
103 to specify that this interrupt thread is a software interrupt.
108 arguments specify optional functions used to enable and disable this
109 interrupt thread's interrupt source.
110 The functions receive the vector corresponding to the thread's interrupt
111 source as their only argument.
112 The remaining arguments form a
114 argument list that is used to build the base name of the new ithread.
115 The full name of an interrupt thread is formed by concatenating the base
116 name of an interrupt thread with the names of all of its interrupt handlers.
120 function destroys a previously created interrupt thread by releasing its
121 resources and arranging for the backing kernel thread to terminate.
122 An interrupt thread can only be destroyed if it has no handlers remaining.
125 .Fn ithread_add_handler
126 function adds a new handler to an existing interrupt thread specified by
130 argument specifies a name for this handler.
135 arguments provide the function to execute for this handler and an argument
139 argument specifies the priority of this handler and is used both in sorting
140 it in relation to the other handlers for this thread and to specify the
141 priority of the backing kernel thread.
144 argument can be used to specify properties of this handler as defined in
150 then it will be assigned a cookie that can be used later to remove this
154 .Fn ithread_remove_handler
155 removes a handler from an interrupt thread.
158 argument specifies the handler to remove from its thread.
162 function schedules an interrupt thread to run.
165 argument is non-zero and the interrupt thread is idle, then a context switch
166 will be forced after putting the interrupt thread on the run queue.
170 function translates the
172 interrupt flags into interrupt handler priorities.
174 The interrupt flags not related to the type of a particular interrupt
176 can be used to specify additional properties of both hardware and software
180 flag specifies that this handler cannot share an interrupt thread with
184 flag specifies that this handler is MP safe in that it does not need the
185 Giant mutex to be held while it is executed.
188 flag specifies that the interrupt source this handler is tied to is a good
189 source of entropy, and thus that entropy should be gathered when an interrupt
190 from the handler's source triggers.
193 flag is not valid for software interrupt handlers.
195 It is not permitted to sleep in an interrupt thread; hence, any memory
196 or zone allocations in an interrupt thread should be specified with the
199 Any allocation errors must be handled thereafter.
202 .Fn ithread_add_handler ,
204 .Fn ithread_destroy ,
205 .Fn ithread_remove_handler ,
208 functions return zero on success and non-zero on failure.
211 function returns a process priority corresponding to the passed in interrupt
216 function demonstrates the use of
219 .Fn ithread_add_handler .
220 .Bd -literal -offset indent
222 swi_add(struct ithd **ithdp, const char *name, driver_intr_t handler,
223 void *arg, int pri, enum intr_type flags, void **cookiep)
229 if (flags & INTR_ENTROPY)
232 ithd = (ithdp != NULL) ? *ithdp : NULL;
235 if ((ithd->it_flags & IT_SOFT) == 0)
238 error = ithread_create(&ithd, pri, IT_SOFT, NULL, NULL,
246 return (ithread_add_handler(ithd, name, handler, arg, pri + PI_SOFT,
252 .Fn ithread_add_handler
253 function will fail if:
266 flag is specified and the interrupt thread
268 already has at least one handler, or the interrupt thread
270 already has an exclusive handler.
272 Could not allocate needed memory for this handler.
277 function will fail if:
280 The system-imposed limit on the total
281 number of processes under execution would be exceeded.
282 The limit is given by the
293 Could not allocate needed memory for this interrupt thread.
298 function will fail if:
306 The interrupt thread pointed to by
308 has at least one handler.
312 .Fn ithread_remove_handler
313 function will fail if:
324 function will fail if:
332 The interrupt thread pointed to by
334 has no interrupt handlers.
342 Interrupt threads and their corresponding API first appeared in
347 represents both an interrupt source and an interrupt thread.
348 There should be a separate
350 that contains a vector number, enable and disable functions, etc.\& that
351 an ithread holds a reference to.