intr_event(9): update existing function descriptions
Document new arguments and behaviours for these functions as compared to the old ithread_* versions. Reviewed by: pauamma Input from: jhb MFC after: 2 weeks Sponsored by: The FreeBSD Foundation Differential Revision: https://reviews.freebsd.org/D33478
This commit is contained in:
parent
dfc91493ab
commit
cb9425e21c
@ -130,12 +130,20 @@ interface.
|
|||||||
.Ss Function Descriptions
|
.Ss Function Descriptions
|
||||||
The
|
The
|
||||||
.Fn intr_event_create
|
.Fn intr_event_create
|
||||||
function creates a new interrupt thread.
|
function creates a new interrupt event.
|
||||||
|
The
|
||||||
|
.Fa event
|
||||||
|
argument points to a
|
||||||
|
.Vt struct intr_event
|
||||||
|
pointer that will reference the newly created event upon success.
|
||||||
The
|
The
|
||||||
.Fa source
|
.Fa source
|
||||||
argument points to a
|
argument is an opaque pointer which will be passed to the
|
||||||
.Vt struct intr_event event
|
.Fa pre_ithread ,
|
||||||
pointer that will point to the newly created thread upon success.
|
.Fa post_ithread ,
|
||||||
|
and
|
||||||
|
.Fa post_filter
|
||||||
|
callbacks.
|
||||||
The
|
The
|
||||||
.Fa flags
|
.Fa flags
|
||||||
argument is a mask of properties of this thread.
|
argument is a mask of properties of this thread.
|
||||||
@ -150,9 +158,31 @@ and
|
|||||||
.Fa disable
|
.Fa disable
|
||||||
arguments specify optional functions used to enable and disable this
|
arguments specify optional functions used to enable and disable this
|
||||||
interrupt thread's interrupt source.
|
interrupt thread's interrupt source.
|
||||||
The functions receive the vector corresponding to the thread's interrupt
|
The
|
||||||
source as their only argument.
|
.Fa irq
|
||||||
The remaining arguments form a
|
argument is the unique interrupt vector number corresponding to the event.
|
||||||
|
The
|
||||||
|
.Fa pre_ithread ,
|
||||||
|
.Fa post_ithread ,
|
||||||
|
and
|
||||||
|
.Fa post_filter
|
||||||
|
arguments are callback functions that are invoked at different
|
||||||
|
points while handling an interrupt.
|
||||||
|
This is described in more detail in the
|
||||||
|
.Sx Handler Callbacks
|
||||||
|
section, below.
|
||||||
|
They may be
|
||||||
|
.Va NULL
|
||||||
|
to specify no callback.
|
||||||
|
The
|
||||||
|
.Fa assign_cpu
|
||||||
|
argument points to a callback function that will be invoked when binding
|
||||||
|
an interrupt to a particular CPU.
|
||||||
|
It may be
|
||||||
|
.Va NULL
|
||||||
|
if binding is unsupported.
|
||||||
|
The
|
||||||
|
remaining arguments form a
|
||||||
.Xr printf 9
|
.Xr printf 9
|
||||||
argument list that is used to build the base name of the new interrupt thread.
|
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
|
The full name of an interrupt thread is formed by concatenating the base
|
||||||
@ -160,29 +190,41 @@ name of the interrupt thread with the names of all of its interrupt handlers.
|
|||||||
.Pp
|
.Pp
|
||||||
The
|
The
|
||||||
.Fn intr_event_destroy
|
.Fn intr_event_destroy
|
||||||
function destroys a previously created interrupt thread by releasing its
|
function destroys a previously created interrupt event by releasing its
|
||||||
resources and arranging for the backing kernel thread to terminate.
|
resources.
|
||||||
An interrupt thread can only be destroyed if it has no handlers remaining.
|
.\" The following is not true (yet):
|
||||||
|
.\"and arranging for the backing kernel thread to terminate.
|
||||||
|
An interrupt event can only be destroyed if it has no handlers remaining.
|
||||||
.Pp
|
.Pp
|
||||||
The
|
The
|
||||||
.Fn intr_event_add_handler
|
.Fn intr_event_add_handler
|
||||||
function adds a new handler to an existing interrupt thread specified by
|
function adds a new handler to an existing interrupt event specified by
|
||||||
.Fa ithread .
|
.Fa ie .
|
||||||
The
|
The
|
||||||
.Fa name
|
.Fa name
|
||||||
argument specifies a name for this handler.
|
argument specifies a name for this handler.
|
||||||
The
|
The
|
||||||
|
.Fa filter
|
||||||
|
argument provide the filter function to execute.
|
||||||
|
The
|
||||||
.Fa handler
|
.Fa handler
|
||||||
and
|
argument provides the handler function to be executed from the
|
||||||
|
event's interrupt thread.
|
||||||
|
The
|
||||||
.Fa arg
|
.Fa arg
|
||||||
arguments provide the function to execute for this handler and an argument
|
argument will be passed to the
|
||||||
to pass to it.
|
.Fa filter
|
||||||
|
and
|
||||||
|
.Fa handler
|
||||||
|
functions when they are invoked.
|
||||||
The
|
The
|
||||||
.Fa pri
|
.Fa pri
|
||||||
argument specifies the priority of this handler and is used both in sorting
|
argument specifies the priority of this handler,
|
||||||
it in relation to the other handlers for this thread and to specify the
|
corresponding to the values defined in
|
||||||
priority of the backing kernel thread.
|
.In sys/priority.h .
|
||||||
The
|
It determines the order this handler is called relative to the other handlers
|
||||||
|
for this event, as well as the scheduling priority of of the backing kernel
|
||||||
|
thread.
|
||||||
.Fa flags
|
.Fa flags
|
||||||
argument can be used to specify properties of this handler as defined in
|
argument can be used to specify properties of this handler as defined in
|
||||||
.In sys/bus.h .
|
.In sys/bus.h .
|
||||||
@ -195,10 +237,13 @@ handler.
|
|||||||
.Pp
|
.Pp
|
||||||
The
|
The
|
||||||
.Fn intr_event_remove_handler
|
.Fn intr_event_remove_handler
|
||||||
removes a handler from an interrupt thread.
|
function removes an interrupt handler from the interrupt event specified by
|
||||||
|
.Fa ie .
|
||||||
The
|
The
|
||||||
.Fa cookie
|
.Fa cookie
|
||||||
argument specifies the handler to remove from its thread.
|
argument, obtained from
|
||||||
|
.Fn intr_event_add_handler ,
|
||||||
|
identifies the handler to remove.
|
||||||
.Pp
|
.Pp
|
||||||
The
|
The
|
||||||
.Fn intr_priority
|
.Fn intr_priority
|
||||||
@ -226,6 +271,37 @@ from the handler's source triggers.
|
|||||||
Presently, the
|
Presently, the
|
||||||
.Dv INTR_ENTROPY
|
.Dv INTR_ENTROPY
|
||||||
flag is not valid for software interrupt handlers.
|
flag is not valid for software interrupt handlers.
|
||||||
|
.Ss Handler Callbacks
|
||||||
|
Each
|
||||||
|
.Vt struct intr_event
|
||||||
|
is assigned three optional callback functions when it is created:
|
||||||
|
.Fa pre_ithread ,
|
||||||
|
.Fa post_ithread ,
|
||||||
|
and
|
||||||
|
.Fa post_filter .
|
||||||
|
These callbacks are intended to be defined by the interrupt controller driver,
|
||||||
|
to allow for actions such as masking and unmasking hardware interrupt signals.
|
||||||
|
.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
|
||||||
|
.Fa post_filter
|
||||||
|
callback is invoked which should acknowledge the interrupt and permit it to
|
||||||
|
trigger in the future.
|
||||||
|
If any threaded handlers are scheduled, the
|
||||||
|
.Fa pre_ithread
|
||||||
|
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
|
||||||
|
.Fa post_ithread
|
||||||
|
callback is invoked from the interrupt thread to enable future interrupts.
|
||||||
|
Typically this callback unmasks level-triggered interrupts in an interrupt
|
||||||
|
controller.
|
||||||
.Sh RETURN VALUES
|
.Sh RETURN VALUES
|
||||||
The
|
The
|
||||||
.Fn intr_event_add_handler ,
|
.Fn intr_event_add_handler ,
|
||||||
|
Loading…
Reference in New Issue
Block a user