Attachment 192475 Details for Bug 100803 – ithread.9 rewrite by trhodes@

[patch] ithread.9 rewrite by trhodes@

intread.9.patch (text/plain), 9.45 KB, created by Oleksandr Tymoshenko on 2018-04-13 01:58:15 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Oleksandr Tymoshenko

Created: 2018-04-13 01:58:15 UTC

Size: 9.45 KB

patch

obsolete

>Index: ObsoleteFiles.inc
>===================================================================
>--- ObsoleteFiles.inc	(revision 332461)
>+++ ObsoleteFiles.inc	(working copy)
>@@ -38,6 +38,14 @@
> #   xargs -n1 | sort | uniq -d;
> # done
> 
>+# 20180412: rewrite ithread man page
>+OLD_FILES+=usr/share/man/man9/ithread_create.9.gz
>+OLD_FILES+=usr/share/man/man9/ithread_add_handler.9.gz
>+OLD_FILES+=usr/share/man/man9/ithread_create.9.gz
>+OLD_FILES+=usr/share/man/man9/ithread_destroy.9.gz
>+OLD_FILES+=usr/share/man/man9/ithread_priority.9.gz
>+OLD_FILES+=usr/share/man/man9/ithread_remove_handler.9.gz
>+OLD_FILES+=usr/share/man/man9/ithread_schedule.9.gz
> # 20180409: remove FDDI support
> OLD_FILES+=usr/include/net/fddi.h
> OLD_FILES+=usr/share/man/man4/fpa.4.gz
>Index: share/man/man9/Makefile
>===================================================================
>--- share/man/man9/Makefile	(revision 332461)
>+++ share/man/man9/Makefile	(working copy)
>@@ -1188,12 +1188,11 @@
> 	ifnet.9 ifunit.9 \
> 	ifnet.9 ifunit_ref.9
> MLINKS+=insmntque.9 insmntque1.9
>-MLINKS+=ithread.9 ithread_add_handler.9 \
>-	ithread.9 ithread_create.9 \
>-	ithread.9 ithread_destroy.9 \
>-	ithread.9 ithread_priority.9 \
>-	ithread.9 ithread_remove_handler.9 \
>-	ithread.9 ithread_schedule.9
>+MLINKS+= ithread.9 intr_event.9 \
>+	ithread.9 intr_event_add_handler.9 \
>+	ithread.9 intr_event_create.9 \
>+	ithread.9 intr_event_destroy.9 \
>+	ithread.9 intr_event_remove_handler.9
> MLINKS+=kernacc.9 useracc.9
> MLINKS+=kernel_mount.9 free_mntarg.9 \
> 	kernel_mount.9 kernel_vmount.9 \
>Index: share/man/man9/ithread.9
>===================================================================
>--- share/man/man9/ithread.9	(revision 332461)
>+++ share/man/man9/ithread.9	(working copy)
>@@ -24,24 +24,23 @@
> .\"
> .\" $FreeBSD$
> .\"
>-.Dd August 25, 2006
>+.Dd April 12, 2018
> .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_event_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,7 +139,7 @@
> handler.
> .Pp
> The
>-.Fn ithread_remove_handler
>+.Fn intr_event_remove_handler
> removes a handler from an interrupt thread.
> The
> .Fa cookie
>@@ -158,65 +146,29 @@
> 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_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_ENTROPY
>-flag is 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,
>@@ -235,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);
>@@ -243,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
>@@ -264,9 +216,9 @@
> 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.
>@@ -273,7 +225,7 @@
> .El
> .Pp
> The
>-.Fn ithread_create
>+.Fn intr_event_create
> function will fail if:
> .Bl -tag -width Er
> .It Bq Er EAGAIN
>@@ -294,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
>@@ -320,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
>@@ -341,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.

Actions: View | Diff

Attachments on bug 100803: 192475