git: bf2d110fe387 - stable/13 - intr_event(9): document intr_event_handle()

The branch stable/13 has been updated by mhorne:

URL: https://cgit.FreeBSD.org/src/commit/?id=bf2d110fe387d68b6325564e140fa8b4d2ae922a

commit bf2d110fe387d68b6325564e140fa8b4d2ae922a
Author:     Mitchell Horne <mhorne@FreeBSD.org>
AuthorDate: 2022-10-30 14:02:20 +0000
Commit:     Mitchell Horne <mhorne@FreeBSD.org>
CommitDate: 2022-11-06 14:55:04 +0000

    intr_event(9): document intr_event_handle()
    
    Reviewed by:    pauamma
    MFC after:      1 week
    Sponsored by:   The FreeBSD Foundation
    Differential Revision:  https://reviews.freebsd.org/D36934
    
    (cherry picked from commit 334fc46f05b4e149b8e23dbce0147a86caf3a8b0)
---
 share/man/man9/Makefile     |  1 +
 share/man/man9/intr_event.9 | 41 ++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 41 insertions(+), 1 deletion(-)

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 1aa72acc97b9..658038d15f2e 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1326,6 +1326,7 @@ MLINKS+=insmntque.9 insmntque1.9
 MLINKS+=intr_event.9 intr_event_add_handler.9 \
 	intr_event.9 intr_event_create.9 \
 	intr_event.9 intr_event_destroy.9 \
+	intr_event.9 intr_event_handle.9 \
 	intr_event.9 intr_event_remove_handler.9 \
 	intr_event.9 intr_priority.9
 MLINKS+=kernacc.9 useracc.9
diff --git a/share/man/man9/intr_event.9 b/share/man/man9/intr_event.9
index 3ae2d051074c..70ea1e1bfc43 100644
--- a/share/man/man9/intr_event.9
+++ b/share/man/man9/intr_event.9
@@ -29,13 +29,14 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd October 15, 2022
+.Dd October 30, 2022
 .Dt INTR_EVENT 9
 .Os
 .Sh NAME
 .Nm intr_event_add_handler ,
 .Nm intr_event_create ,
 .Nm intr_event_destroy ,
+.Nm intr_event handle ,
 .Nm intr_event_remove_handler ,
 .Nm intr_priority
 .Nd "kernel interrupt handler and thread API"
@@ -70,6 +71,8 @@
 .Ft int
 .Fn intr_event_destroy "struct intr_event *ie"
 .Ft int
+.Fn intr_event_handle "struct intr_event *ie" "struct trapframe *frame"
+.Ft int
 .Fn intr_event_remove_handler "void *cookie"
 .Ft u_char
 .Fn intr_priority "enum intr_type flags"
@@ -242,6 +245,23 @@ then it will be assigned a cookie that can be used later to remove this
 handler.
 .Pp
 The
+.Fn intr_event_handle
+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
+.Fa ie ,
+and schedule the associated interrupt thread to run, if applicable.
+The
+.Fa frame
+argument is used to pass a pointer to the
+.Vt struct trapframe
+containing the machine state at the time of the interrupt.
+The main body of this function runs within a
+.Xr critical 9
+section.
+.Pp
+The
 .Fn intr_event_remove_handler
 function removes an interrupt handler from the interrupt event specified by
 .Fa ie .
@@ -313,6 +333,7 @@ The
 .Fn intr_event_add_handler ,
 .Fn intr_event_create ,
 .Fn intr_event_destroy ,
+.Fn intr_event_handle ,
 and
 .Fn intr_event_remove_handler
 functions return zero on success and non-zero on failure.
@@ -416,6 +437,23 @@ has at least one handler which has not been removed with
 .El
 .Pp
 The
+.Fn intr_event_handle
+function will fail if:
+.Bl -tag -width Er
+.It Bq Er EINVAL
+The
+.Fa ie
+argument is
+.Dv NULL .
+.It Bq Er EINVAL
+There are no interrupt handlers assigned to
+.Fa ie .
+.It Bq Er EINVAL
+The interrupt was not acknowledged by any filter and has no associated thread
+handler.
+.El
+.Pp
+The
 .Fn intr_event_remove_handler
 function will fail if:
 .Bl -tag -width Er
@@ -426,6 +464,7 @@ argument is
 .Dv NULL .
 .El
 .Sh SEE ALSO
+.Xr critical 9 ,
 .Xr kthread 9 ,
 .Xr locking 9 ,
 .Xr malloc 9 ,