Bug 100803
| Summary: | [patch] the man page about ithread is expired. | ||||||
|---|---|---|---|---|---|---|---|
| Product: | Documentation | Reporter: | mirnshi <mirnshi> | ||||
| Component: | Manual Pages | Assignee: | Mitchell Horne <mhorne> | ||||
| Status: | Closed FIXED | ||||||
| Severity: | Affects Only Me | CC: | doc, emaste, gonzo, jhb, mhorne, trhodes, ygy | ||||
| Priority: | Normal | Keywords: | patch | ||||
| Version: | Latest | ||||||
| Hardware: | Any | ||||||
| OS: | Any | ||||||
| Attachments: |
|
||||||
|
Description
mirnshi
2006-07-25 11:00:29 UTC
Responsible Changed From-To: freebsd-bugs->freebsd-doc Over to maintainer(s). Hi,
I've sent the following patch to John Baldwin for review:
Index: ithread.9
===================================================================
RCS file: /home/ncvs/src/share/man/man9/ithread.9,v
retrieving revision 1.12
diff -u -r1.12 ithread.9
--- ithread.9 25 Aug 2006 19:04:42 -0000 1.12
+++ ithread.9 8 Oct 2006 17:47:16 -0000
@@ -28,20 +28,19 @@
.Dt ITHREAD 9
.Os
.Sh NAME
-.Nm ithread_add_handler ,
-.Nm ithread_create ,
-.Nm ithread_destroy ,
-.Nm ithread_priority ,
-.Nm ithread_remove_handler ,
-.Nm ithread_schedule
-.Nd kernel interrupt threads
+.Nm intr_event_add_handler ,
+.Nm intr_event_create ,
+.Nm intr_event_destroy ,
+.Nm intr_event_remove_handler ,
+.Nm intr_event_schedule_thread
+.Nd "kernel event interrupt threads"
.Sh SYNOPSIS
.In sys/param.h
.In sys/bus.h
.In sys/interrupt.h
.Ft int
-.Fo ithread_add_handler
-.Fa "struct ithd *ithread"
+.Fo intr_add_handler
+.Fa "struct intr_event *ie"
.Fa "const char *name"
.Fa "driver_intr_t handler"
.Fa "void *arg"
@@ -50,23 +49,19 @@
.Fa "void **cookiep"
.Fc
.Ft int
-.Fo ithread_create
-.Fa "struct ithd **ithread"
-.Fa "int vector"
+.Fo intr_event_create
+.Fa "struct intr_event **event"
+.Fa "void *source"
.Fa "int flags"
-.Fa "void (*disable)(int)"
.Fa "void (*enable)(int)"
.Fa "const char *fmt"
.Fa "..."
.Fc
.Ft int
-.Fn ithread_destroy "struct ithd *ithread"
-.Ft u_char
-.Fn ithread_priority "enum intr_type flags"
+.Fn intr_event_destroy "struct intr_event *ie"
+.Fn intr_event_remove_handler "void *cookie"
.Ft int
-.Fn ithread_remove_handler "void *cookie"
-.Ft int
-.Fn ithread_schedule "struct ithd *ithread" "int do_switch"
+.Fn intr_event_schedule_thread "struct intr_event *ie"
.Sh DESCRIPTION
Interrupt threads are kernel threads that run a list of handlers when
triggered by either a hardware or software interrupt.
@@ -83,46 +78,39 @@
represented as a vector number.
.Pp
The
-.Fn ithread_create
+.Fn intr_event_create
function creates a new interrupt thread.
The
-.Fa ithread
-argument points to an
-.Vt struct ithd
+.Fa source
+argument points to a
+.Vt struct entr_event event
pointer that will point to the newly created thread upon success.
The
-.Fa vector
-argument specifies the interrupt source to associate this thread with.
-The
.Fa flags
argument is a mask of properties of this thread.
The only valid flag currently for
-.Fn ithread_create
+.Fn intr_event_create
is
.Dv IT_SOFT
to specify that this interrupt thread is a software interrupt.
The
.Fa enable
-and
-.Fa disable
-arguments specify optional functions used to enable and disable this
+argument specify optional functions used to enable this
interrupt thread's interrupt source.
-The functions receive the vector corresponding to the thread's interrupt
-source as their only argument.
The remaining arguments form a
.Xr printf 9
-argument list that is used to build the base name of the new ithread.
+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 an interrupt thread with the names of all of its interrupt handlers.
.Pp
The
-.Fn ithread_destroy
+.Fn intr_event_destroy
function destroys a previously created interrupt thread by releasing its
resources and arranging for the backing kernel thread to terminate.
An interrupt thread can only be destroyed if it has no handlers remaining.
.Pp
The
-.Fn ithread_add_handler
+.Fn intr_event_add_handler
function adds a new handler to an existing interrupt thread specified by
.Fa ithread .
The
@@ -151,83 +139,36 @@
handler.
.Pp
The
-.Fn ithread_remove_handler
+.Fn intr_event_remove_handler
removes a handler from an interrupt thread.
The
.Fa cookie
argument specifies the handler to remove from its thread.
.Pp
The
-.Fn ithread_schedule
+.Fn intr_event_schedule_thread
function schedules an interrupt thread to run.
If the
-.Fa do_switch
+.Fa ie
argument is non-zero and the interrupt thread is idle, then a context switch
will be forced after putting the interrupt thread on the run queue.
-.Pp
-The
-.Fn ithread_priority
-function translates the
-.Dv INTR_TYPE_*
-interrupt flags into interrupt handler priorities.
-.Pp
-The interrupt flags not related to the type of a particular interrupt
-.Pq Dv INTR_TYPE_*
-can be used to specify additional properties of both hardware and software
-interrupt handlers.
-The
-.Dv INTR_EXCL
-flag specifies that this handler cannot share an interrupt thread with
-another handler.
-The
-.Dv INTR_FAST
-flag specifies that when this handler is executed, it should be run immediately
-rather than being run asynchronously when its interrupt thread is scheduled to
-run.
-The
-.Dv INTR_FAST
-flag implies
-.Dv INTR_EXCL .
-The
-.Dv INTR_MPSAFE
-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
-.Dv INTR_ENTROPY
-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
-.Dv INTR_FAST
-and
-.Dv INTR_ENTROPY
-flags are not valid for software interrupt handlers.
-.Pp
-It is not permitted to sleep in an interrupt thread; hence, any memory
-or zone allocations in an interrupt thread should be specified with the
-.Dv M_NOWAIT
-flag set.
-Any allocation errors must be handled thereafter.
.Sh RETURN VALUES
The
-.Fn ithread_add_handler ,
-.Fn ithread_create ,
-.Fn ithread_destroy ,
-.Fn ithread_remove_handler ,
+.Fn intr_event_add_handler ,
+.Fn intr_event_create ,
+.Fn intr_event_destroy ,
+.Fn intr_event_remove_handler ,
and
-.Fn ithread_schedule
+.Fn intr_event_schedule_thread
functions return zero on success and non-zero on failure.
The
-.Fn ithread_priority
-function returns a process priority corresponding to the passed in interrupt
-flags.
.Sh EXAMPLES
The
.Fn swi_add
function demonstrates the use of
-.Fn ithread_create
+.Fn intr_event_create
and
-.Fn ithread_add_handler .
+.Fn intr_event_add_handler .
.Bd -literal -offset indent
int
swi_add(struct ithd **ithdp, const char *name, driver_intr_t handler,
@@ -246,7 +187,7 @@
if ((ithd->it_flags & IT_SOFT) == 0)
return(EINVAL);
} else {
- error = ithread_create(&ithd, pri, IT_SOFT, NULL, NULL,
+ error = intr_event_create(&event, pri, IT_SOFT, NULL, NULL,
"swi%d:", pri);
if (error)
return (error);
@@ -254,18 +195,18 @@
if (ithdp != NULL)
*ithdp = ithd;
}
- return (ithread_add_handler(ithd, name, handler, arg, pri + PI_SOFT,
+ return (intr_event_add_handler(ie, name, handler, arg, pri + PI_SOFT,
flags, cookiep));
}
.Ed
.Sh ERRORS
The
-.Fn ithread_add_handler
+.Fn intr_event_add_handler
function will fail if:
.Bl -tag -width Er
.It Bq Er EINVAL
Any of the
-.Fa ithread ,
+.Fa ie ,
.Fa handler ,
or
.Fa name
@@ -275,16 +216,16 @@
The
.Dv INTR_EXCL
flag is specified and the interrupt thread
-.Fa ithread
+.Fa ie
already has at least one handler, or the interrupt thread
-.Fa ithread
+.Fa ie
already has an exclusive handler.
.It Bq Er ENOMEM
Could not allocate needed memory for this handler.
.El
.Pp
The
-.Fn ithread_create
+.Fn intr_event_create
function will fail if:
.Bl -tag -width Er
.It Bq Er EAGAIN
@@ -305,22 +246,22 @@
.El
.Pp
The
-.Fn ithread_destroy
+.Fn intr_event_destroy
function will fail if:
.Bl -tag -width Er
.It Bq Er EINVAL
The
-.Fa ithread
+.Fa ie
argument is
.Dv NULL .
.It Bq Er EINVAL
The interrupt thread pointed to by
-.Fa ithread
+.Fa ie
has at least one handler.
.El
.Pp
The
-.Fn ithread_remove_handler
+.Fn intr_event_remove_handler
function will fail if:
.Bl -tag -width Er
.It Bq Er EINVAL
@@ -331,17 +272,17 @@
.El
.Pp
The
-.Fn ithread_schedule
+.Fn intr_event_schedule_thread
function will fail if:
.Bl -tag -width Er
.It Bq Er EINVAL
The
-.Fa ithread
+.Fa ie
argument is
.Dv NULL .
.It Bq Er EINVAL
The interrupt thread pointed to by
-.Fa ithread
+.Fa ie
has no interrupt handlers.
.El
.Sh SEE ALSO
@@ -352,11 +293,3 @@
.Sh HISTORY
Interrupt threads and their corresponding API first appeared in
.Fx 5.0 .
-.Sh BUGS
-Currently
-.Vt struct ithd
-represents both an interrupt source and an interrupt thread.
-There should be a separate
-.Vt struct isrc
-that contains a vector number, enable and disable functions, etc.\& that
-an ithread holds a reference to.
Perhaps this should be renamed to intr_event.9 and ithread.9 should
go away? Not sure, I asked for his opinion. Thanks!
--
Tom Rhodes
Responsible Changed From-To: freebsd-doc->trhodes Very large patch sent to John for review. Responsible Changed From-To: trhodes->jhb Over to John who discussed this with me. Thanks! For bugs matching the following criteria: Status: In Progress Changed: (is less than) 2014-06-01 Reset to default assignee and clear in-progress tags. Mail being skipped Created attachment 192475 [details]
ithread.9 rewrite by trhodes@
This is cleaned-up patch by trhodes@ plus renaming manpages hardlinks and removal of old ones
Returning to pool. I've extended the patch slightly and posted a new review: https://reviews.freebsd.org/D33475 A commit in branch main references this bug: URL: https://cgit.FreeBSD.org/src/commit/?id=3cdbaee3548a6caa3ab7aca5788775057b1bd1fd commit 3cdbaee3548a6caa3ab7aca5788775057b1bd1fd Author: Mitchell Horne <mhorne@FreeBSD.org> AuthorDate: 2022-10-15 18:32:09 +0000 Commit: Mitchell Horne <mhorne@FreeBSD.org> CommitDate: 2022-10-15 18:49:33 +0000 ithread(9): update functions to current day The public KPI is now intr_event_**, - Convert existing documented functions to their equivalents. - Fix up the function arguments - Fix up the possible error return values for each - Remove ithread_schedule() completely - Rename man page to intr_event(9) - Update cross-references Future changes will update the descriptive text for these functions. PR: 100803 Based on work by: trhodes Reviewed by: jhb MFC after: 2 weeks Sponsored by: The FreeBSD Foundation Differential Revision: https://reviews.freebsd.org/D33475 ObsoleteFiles.inc | 9 ++ share/man/man9/Makefile | 13 +-- share/man/man9/{ithread.9 => intr_event.9} | 170 +++++++++++------------------ share/man/man9/socket.9 | 13 +-- share/man/man9/swi.9 | 2 +- 5 files changed, 87 insertions(+), 120 deletions(-) A commit in branch stable/13 references this bug: URL: https://cgit.FreeBSD.org/src/commit/?id=8f85514a2c41c62a32271afa00158310e5cc30d0 commit 8f85514a2c41c62a32271afa00158310e5cc30d0 Author: Mitchell Horne <mhorne@FreeBSD.org> AuthorDate: 2022-10-15 18:32:09 +0000 Commit: Mitchell Horne <mhorne@FreeBSD.org> CommitDate: 2022-10-30 14:13:58 +0000 ithread(9): update functions to current day The public KPI is now intr_event_**, - Convert existing documented functions to their equivalents. - Fix up the function arguments - Fix up the possible error return values for each - Remove ithread_schedule() completely - Rename man page to intr_event(9) - Update cross-references Future changes will update the descriptive text for these functions. PR: 100803 Based on work by: trhodes Reviewed by: jhb MFC after: 2 weeks Sponsored by: The FreeBSD Foundation Differential Revision: https://reviews.freebsd.org/D33475 (cherry picked from commit 3cdbaee3548a6caa3ab7aca5788775057b1bd1fd) ObsoleteFiles.inc | 9 ++ share/man/man9/Makefile | 13 +-- share/man/man9/{ithread.9 => intr_event.9} | 170 +++++++++++------------------ share/man/man9/socket.9 | 13 +-- share/man/man9/swi.9 | 2 +- 5 files changed, 87 insertions(+), 120 deletions(-) |
