diff options
Diffstat (limited to 'static/freebsd/man9/intr_event.9 3.html')
| -rw-r--r-- | static/freebsd/man9/intr_event.9 3.html | 341 |
1 files changed, 0 insertions, 341 deletions
diff --git a/static/freebsd/man9/intr_event.9 3.html b/static/freebsd/man9/intr_event.9 3.html deleted file mode 100644 index 07f157eb..00000000 --- a/static/freebsd/man9/intr_event.9 3.html +++ /dev/null @@ -1,341 +0,0 @@ -<table class="head"> - <tr> - <td class="head-ltitle">INTR_EVENT(9)</td> - <td class="head-vol">Kernel Developer's Manual</td> - <td class="head-rtitle">INTR_EVENT(9)</td> - </tr> -</table> -<div class="manual-text"> -<section class="Sh"> -<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> -<p class="Pp"><code class="Nm">intr_event_add_handler</code>, - <code class="Nm">intr_event_create</code>, - <code class="Nm">intr_event_destroy</code>, - <code class="Nm">intr_event_handle</code>, - <code class="Nm">intr_event_remove_handler</code>, - <code class="Nm">intr_priority</code> — <span class="Nd">kernel - interrupt handler and thread API</span></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> -<p class="Pp"><code class="In">#include - <<a class="In">sys/param.h</a>></code> - <br/> - <code class="In">#include <<a class="In">sys/bus.h</a>></code> - <br/> - <code class="In">#include <<a class="In">sys/interrupt.h</a>></code></p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">intr_event_add_handler</code>(<var class="Fa">struct - intr_event *ie</var>, <var class="Fa">const char *name</var>, - <var class="Fa">driver_filter_t filter</var>, <var class="Fa">driver_intr_t - handler</var>, <var class="Fa">void *arg</var>, <var class="Fa">u_char - pri</var>, <var class="Fa">enum intr_type flags</var>, <var class="Fa">void - **cookiep</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">intr_event_create</code>(<var class="Fa">struct intr_event - **event</var>, <var class="Fa">void *source</var>, <var class="Fa">int - flags</var>, <var class="Fa">int irq</var>, <var class="Fa">void - (*pre_ithread)(void *)</var>, <var class="Fa">void (*post_ithread)(void - *)</var>, <var class="Fa">void (*post_filter)(void *)</var>, - <var class="Fa">int (*assign_cpu)(void *, int)</var>, <var class="Fa">const - char *fmt</var>, <var class="Fa">...</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">intr_event_destroy</code>(<var class="Fa" style="white-space: nowrap;">struct - intr_event *ie</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">intr_event_handle</code>(<var class="Fa" style="white-space: nowrap;">struct - intr_event *ie</var>, <var class="Fa" style="white-space: nowrap;">struct - trapframe *frame</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">intr_event_remove_handler</code>(<var class="Fa" style="white-space: nowrap;">void - *cookie</var>);</p> -<p class="Pp"><var class="Ft">u_char</var> - <br/> - <code class="Fn">intr_priority</code>(<var class="Fa" style="white-space: nowrap;">enum - intr_type flags</var>);</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> -<p class="Pp">The interrupt event API provides methods to manage the - registration and execution of interrupt handlers and their associated thread - contexts.</p> -<p class="Pp">Each interrupt event in the system corresponds to a single - hardware or software interrupt source. Each interrupt event maintains a list - of interrupt handlers, sorted by priority, which will be invoked when - handling the event. An interrupt event will typically, but not always, have - an associated <a class="Xr">kthread(9)</a>, known as the interrupt thread. - Finally, each event contains optional callback functions which will be - invoked before and after the handler functions themselves.</p> -<p class="Pp">An interrupt handler contains two distinct handler functions: the - <i class="Em">filter</i> and the thread <i class="Em">handler</i>. The - <i class="Em">filter</i> function is run from interrupt context and is - intended to perform quick handling such as acknowledging or masking a - hardware interrupt, and queueing work for the ensuing thread - <i class="Em">handler</i>. Both functions are optional; each interrupt - handler may choose to register a filter, a thread handler, or both. Each - interrupt handler also consists of a name, a set of flags, and an opaque - argument which will be passed to both the <i class="Em">filter</i> and - <i class="Em">handler</i> functions.</p> -<section class="Ss"> -<h2 class="Ss" id="Handler_Constraints"><a class="permalink" href="#Handler_Constraints">Handler - Constraints</a></h2> -<p class="Pp">The <i class="Em">filter</i> function is executed inside a - <a class="Xr">critical(9)</a> section. Therefore, filters may not yield the - CPU for any reason, and may only use spin locks to access shared data. - Allocating memory within a filter is not permitted.</p> -<p class="Pp">The <i class="Em">handler</i> function executes from the context - of the associated interrupt kernel thread. Sleeping is not permitted, but - the interrupt thread may be preempted by higher priority threads. Thus, - threaded handler functions may obtain non-sleepable locks, as described in - <a class="Xr">locking(9)</a>. Any memory or zone allocations in an interrupt - thread must specify the <code class="Dv">M_NOWAIT</code> flag, and any - allocation errors must be handled.</p> -<p class="Pp">The exception to these constraints is software interrupt threads, - which are allowed to sleep but should be allocated and scheduled using the - <a class="Xr">swi(9)</a> interface.</p> -</section> -<section class="Ss"> -<h2 class="Ss" id="Function_Descriptions"><a class="permalink" href="#Function_Descriptions">Function - Descriptions</a></h2> -<p class="Pp">The - <a class="permalink" href="#intr_event_create"><code class="Fn" id="intr_event_create">intr_event_create</code></a>() - function creates a new interrupt event. The <var class="Fa">event</var> - argument points to a <var class="Vt">struct intr_event</var> pointer that - will reference the newly created event upon success. The - <var class="Fa">source</var> argument is an opaque pointer which will be - passed to the <var class="Fa">pre_ithread</var>, - <var class="Fa">post_ithread</var>, and <var class="Fa">post_filter</var> - callbacks. The <var class="Fa">flags</var> argument is a mask of properties - of this thread. The only valid flag currently for - <code class="Fn">intr_event_create</code>() is - <code class="Dv">IE_SOFT</code> to specify that this interrupt thread is a - software interrupt. The <var class="Fa">enable</var> and - <var class="Fa">disable</var> arguments specify optional functions used to - enable and disable this interrupt thread's interrupt source. The - <var class="Fa">irq</var> argument is the unique interrupt vector number - corresponding to the event. The <var class="Fa">pre_ithread</var>, - <var class="Fa">post_ithread</var>, and <var class="Fa">post_filter</var> - arguments are callback functions that are invoked at different points while - handling an interrupt. This is described in more detail in the - <a class="Sx" href="#Handler_Callbacks">Handler Callbacks</a> section, - below. They may be <var class="Va">NULL</var> to specify no callback. The - <var class="Fa">assign_cpu</var> argument points to a callback function that - will be invoked when binding an interrupt to a particular CPU. It may be - <var class="Va">NULL</var> if binding is unsupported. The remaining - arguments form a <a class="Xr">printf(9)</a> argument list that is used to - build the base name of the new interrupt thread. The full name of an - interrupt thread is formed by concatenating the base name of the interrupt - thread with the names of all of its interrupt handlers.</p> -<p class="Pp" id="intr_event_destroy">The - <a class="permalink" href="#intr_event_destroy"><code class="Fn">intr_event_destroy</code></a>() - function destroys a previously created interrupt event by releasing its - resources. An interrupt event can only be destroyed if it has no handlers - remaining.</p> -<p class="Pp" id="intr_event_add_handler">The - <a class="permalink" href="#intr_event_add_handler"><code class="Fn">intr_event_add_handler</code></a>() - function adds a new handler to an existing interrupt event specified by - <var class="Fa">ie</var>. The <var class="Fa">name</var> argument specifies - a name for this handler. The <var class="Fa">filter</var> argument provide - the filter function to execute. The <var class="Fa">handler</var> argument - provides the handler function to be executed from the event's interrupt - thread. The <var class="Fa">arg</var> argument will be passed to the - <var class="Fa">filter</var> and <var class="Fa">handler</var> functions - when they are invoked. The <var class="Fa">pri</var> argument specifies the - priority of this handler, corresponding to the values defined in - <code class="In"><<a class="In">sys/priority.h</a>></code>. It - determines the order this handler is called relative to the other handlers - for this event, as well as the scheduling priority of the backing kernel - thread. <var class="Fa">flags</var> argument can be used to specify - properties of this handler as defined in - <code class="In"><<a class="In">sys/bus.h</a>></code>. If - <var class="Fa">cookiep</var> is not <code class="Dv">NULL</code>, then it - will be assigned a cookie that can be used later to remove this handler.</p> -<p class="Pp" id="intr_event_handle">The - <a class="permalink" href="#intr_event_handle"><code class="Fn">intr_event_handle</code></a>() - function is the main entry point into the interrupt handling code. It must - be called from an interrupt context. The function will execute all filter - handlers associated with the interrupt event <var class="Fa">ie</var>, and - schedule the associated interrupt thread to run, if applicable. The - <var class="Fa">frame</var> argument is used to pass a pointer to the - <var class="Vt">struct trapframe</var> containing the machine state at the - time of the interrupt. The main body of this function runs within a - <a class="Xr">critical(9)</a> section.</p> -<p class="Pp" id="intr_event_remove_handler">The - <a class="permalink" href="#intr_event_remove_handler"><code class="Fn">intr_event_remove_handler</code></a>() - function removes an interrupt handler from the interrupt event specified by - <var class="Fa">ie</var>. The <var class="Fa">cookie</var> argument, - obtained from <code class="Fn">intr_event_add_handler</code>(), identifies - the handler to remove.</p> -<p class="Pp" id="intr_priority">The - <a class="permalink" href="#intr_priority"><code class="Fn">intr_priority</code></a>() - function translates the <code class="Dv">INTR_TYPE_*</code> interrupt flags - into interrupt thread scheduling priorities.</p> -<p class="Pp">The interrupt flags not related to the type of a particular - interrupt (<code class="Dv">INTR_TYPE_*</code>) can be used to specify - additional properties of both hardware and software interrupt handlers. The - <code class="Dv">INTR_EXCL</code> flag specifies that this handler cannot - share an interrupt thread with another handler. The - <code class="Dv">INTR_MPSAFE</code> flag specifies that this handler is MP - safe in that it does not need the Giant mutex to be held while it is - executed. The <code class="Dv">INTR_ENTROPY</code> flag specifies that the - interrupt source this handler is tied to is a good source of entropy, and - thus that entropy should be gathered when an interrupt from the handler's - source triggers. Presently, the <code class="Dv">INTR_ENTROPY</code> flag is - not valid for software interrupt handlers. The - <code class="Dv">INTR_SLEEPABLE</code> flag specifies that the interrupt - ithread may sleep. Presently, the <code class="Dv">INTR_SLEEPABLE</code> - flag requires the <code class="Dv">INTR_EXCL</code> flag to be set.</p> -</section> -<section class="Ss"> -<h2 class="Ss" id="Handler_Callbacks"><a class="permalink" href="#Handler_Callbacks">Handler - Callbacks</a></h2> -<p class="Pp">Each <var class="Vt">struct intr_event</var> is assigned three - optional callback functions when it is created: - <var class="Fa">pre_ithread</var>, <var class="Fa">post_ithread</var>, and - <var class="Fa">post_filter</var>. These callbacks are intended to be - defined by the interrupt controller driver, to allow for actions such as - masking and unmasking hardware interrupt signals.</p> -<p class="Pp">When an interrupt is triggered, all filters are run to determine - if any threaded interrupt handlers should be scheduled for execution by the - associated interrupt thread. If no threaded handlers are scheduled, the - <var class="Fa">post_filter</var> callback is invoked which should - acknowledge the interrupt and permit it to trigger in the future. If any - threaded handlers are scheduled, the <var class="Fa">pre_ithread</var> - callback is invoked instead. This handler should acknowledge the interrupt, - but it should also ensure that the interrupt will not fire continuously - until after the threaded handlers have executed. Typically this callback - masks level-triggered interrupts in an interrupt controller while leaving - edge-triggered interrupts alone. Once all threaded handlers have executed, - the <var class="Fa">post_ithread</var> callback is invoked from the - interrupt thread to enable future interrupts. Typically this callback - unmasks level-triggered interrupts in an interrupt controller.</p> -</section> -</section> -<section class="Sh"> -<h1 class="Sh" id="RETURN_VALUES"><a class="permalink" href="#RETURN_VALUES">RETURN - VALUES</a></h1> -<p class="Pp">The <code class="Fn">intr_event_add_handler</code>(), - <code class="Fn">intr_event_create</code>(), - <code class="Fn">intr_event_destroy</code>(), - <code class="Fn">intr_event_handle</code>(), and - <code class="Fn">intr_event_remove_handler</code>() functions return zero on - success and non-zero on failure. The <code class="Fn">intr_priority</code>() - function returns a process priority corresponding to the passed in interrupt - flags.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1> -<p class="Pp">The <a class="Xr">swi_add(9)</a> function demonstrates the use of - <code class="Fn">intr_event_create</code>() and - <code class="Fn">intr_event_add_handler</code>().</p> -<div class="Bd Pp Bd-indent Li"> -<pre>int -swi_add(struct intr_event **eventp, const char *name, driver_intr_t handler, - void *arg, int pri, enum intr_type flags, void **cookiep) -{ - struct intr_event *ie; - int error = 0; - - if (flags & INTR_ENTROPY) - return (EINVAL); - - ie = (eventp != NULL) ? *eventp : NULL; - - if (ie != NULL) { - if (!(ie->ie_flags & IE_SOFT)) - return (EINVAL); - } else { - error = intr_event_create(&ie, NULL, IE_SOFT, 0, - NULL, NULL, NULL, swi_assign_cpu, "swi%d:", pri); - if (error) - return (error); - if (eventp != NULL) - *eventp = ie; - } - if (handler != NULL) { - error = intr_event_add_handler(ie, name, NULL, handler, arg, - PI_SWI(pri), flags, cookiep); - } - return (error); -}</pre> -</div> -</section> -<section class="Sh"> -<h1 class="Sh" id="ERRORS"><a class="permalink" href="#ERRORS">ERRORS</a></h1> -<p class="Pp">The <code class="Fn">intr_event_add_handler</code>() function will - fail if:</p> -<dl class="Bl-tag"> - <dt id="EINVAL">[<a class="permalink" href="#EINVAL"><code class="Er">EINVAL</code></a>]</dt> - <dd>The <var class="Fa">ie</var> or <var class="Fa">name</var> arguments are - <code class="Dv">NULL</code>.</dd> - <dt id="EINVAL~2">[<a class="permalink" href="#EINVAL~2"><code class="Er">EINVAL</code></a>]</dt> - <dd>The <var class="Fa">handler</var> and <var class="Fa">filter</var> - arguments are both <code class="Dv">NULL</code>.</dd> - <dt id="EINVAL~3">[<a class="permalink" href="#EINVAL~3"><code class="Er">EINVAL</code></a>]</dt> - <dd>The <code class="Dv">IH_EXCLUSIVE</code> flag is specified and the - interrupt thread <var class="Fa">ie</var> already has at least one - handler, or the interrupt thread <var class="Fa">ie</var> already has an - exclusive handler.</dd> -</dl> -<p class="Pp">The <code class="Fn">intr_event_create</code>() function will fail - if:</p> -<dl class="Bl-tag"> - <dt id="EINVAL~4">[<a class="permalink" href="#EINVAL~4"><code class="Er">EINVAL</code></a>]</dt> - <dd>A flag other than <code class="Dv">IE_SOFT</code> was specified in the - <var class="Fa">flags</var> parameter.</dd> -</dl> -<p class="Pp">The <code class="Fn">intr_event_destroy</code>() function will - fail if:</p> -<dl class="Bl-tag"> - <dt id="EINVAL~5">[<a class="permalink" href="#EINVAL~5"><code class="Er">EINVAL</code></a>]</dt> - <dd>The <var class="Fa">ie</var> argument is - <code class="Dv">NULL</code>.</dd> - <dt id="EBUSY">[<a class="permalink" href="#EBUSY"><code class="Er">EBUSY</code></a>]</dt> - <dd>The interrupt event pointed to by <var class="Fa">ie</var> has at least - one handler which has not been removed with - <code class="Fn">intr_event_remove_handler</code>().</dd> -</dl> -<p class="Pp">The <code class="Fn">intr_event_handle</code>() function will fail - if:</p> -<dl class="Bl-tag"> - <dt id="EINVAL~6">[<a class="permalink" href="#EINVAL~6"><code class="Er">EINVAL</code></a>]</dt> - <dd>The <var class="Fa">ie</var> argument is - <code class="Dv">NULL</code>.</dd> - <dt id="EINVAL~7">[<a class="permalink" href="#EINVAL~7"><code class="Er">EINVAL</code></a>]</dt> - <dd>There are no interrupt handlers assigned to <var class="Fa">ie</var>.</dd> - <dt id="EINVAL~8">[<a class="permalink" href="#EINVAL~8"><code class="Er">EINVAL</code></a>]</dt> - <dd>The interrupt was not acknowledged by any filter and has no associated - thread handler.</dd> -</dl> -<p class="Pp">The <code class="Fn">intr_event_remove_handler</code>() function - will fail if:</p> -<dl class="Bl-tag"> - <dt id="EINVAL~9">[<a class="permalink" href="#EINVAL~9"><code class="Er">EINVAL</code></a>]</dt> - <dd>The <var class="Fa">cookie</var> argument is - <code class="Dv">NULL</code>.</dd> -</dl> -</section> -<section class="Sh"> -<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE - ALSO</a></h1> -<p class="Pp"><a class="Xr">critical(9)</a>, <a class="Xr">kthread(9)</a>, - <a class="Xr">locking(9)</a>, <a class="Xr">malloc(9)</a>, - <a class="Xr">swi(9)</a>, <a class="Xr">uma(9)</a></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> -<p class="Pp">Interrupt threads and their corresponding API first appeared in - <span class="Ux">FreeBSD 5.0</span>.</p> -</section> -</div> -<table class="foot"> - <tr> - <td class="foot-date">January 24, 2025</td> - <td class="foot-os">FreeBSD 15.0</td> - </tr> -</table> |