Index: share/man/man9/ithread.9
===================================================================
--- share/man/man9/ithread.9
+++ share/man/man9/ithread.9
@@ -68,19 +68,57 @@
 .Ft u_char
 .Fn intr_priority "enum intr_type flags"
 .Sh DESCRIPTION
-Interrupt threads are kernel threads that run a list of handlers when
-triggered by either a hardware or software interrupt.
-Each interrupt handler has a name, handler function, handler argument,
-priority, and various flags.
-Each interrupt thread maintains a list of handlers sorted by priority.
-This results in higher priority handlers being executed prior to lower
-priority handlers.
-Each thread assumes the priority of its highest priority handler for its
-process priority, or
-.Dv PRIO_MAX
-if it has no handlers.
-Interrupt threads are also associated with a single interrupt source,
-represented as a vector number.
+The interrupt event API provides methods to manage the registration and
+execution of interrupt handlers and their associated thread contexts.
+.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,
+all of which will be invoked when handling the event.
+An interrupt event will typically,
+but not always,
+have an associated
+.Xr kthread 9 ,
+known as the interrupt thread.
+Finally, each event contains a set of optional callback functions which will be
+invoked before and after the interrupt handler functions themselves.
+Typically these are set by the driver for the interrupt controller.
+.Pp
+An interrupt handler contains two distinct callback functions:
+the
+.Em filter
+and the
+.Em handler .
+The
+.Em filter
+function is run from the interrupt context and is intended to perform quick
+handling such as acknowledging or masking a hardware interrupt,
+and queueing work for the ensuing
+.Em handler.
+The
+.Em filter
+function must not perform any action that yields the CPU,
+and may only use spin locks to access shared data.
+The
+.Em handler
+function executes from the context of the associated interrupt kernel thread,
+and therefore has looser contraints than the
+.Em filter .
+The
+.Em handler
+function may perform bounded sleep and obtain additional types of locks,
+as described in
+.Xr locking 9 .
+It may also be preempted by higher priority threads.
+.Pp
+Each interrupt handler also consists of a name,
+a set of flags,
+and an opaque argument which will be passed to both the
+.Em filter
+and
+.Em handler
+functions.
 .Pp
 The
 .Fn intr_event_create