Document the ithread_* API used to manage interrupt threads and their
list of handlers.
This commit is contained in:
John Baldwin
parent
d265f30080
commit
ebadd4f5b1
@ -18,7 +18,7 @@ MAN9= CONDSPLASSERT.9 DELAY.9 KASSERT.9 MD5.9 SPLASSERT.9 \
|
||||
devtoname.9 \
|
||||
fetch.9 \
|
||||
get_cyclecounter.9 \
|
||||
ifnet.9 inittodr.9 intro.9 \
|
||||
ifnet.9 inittodr.9 intro.9 ithread.9 \
|
||||
kernacc.9 kthread.9 \
|
||||
malloc.9 make_dev.9 mbuf.9 microseq.9 microtime.9 microuptime.9 \
|
||||
mi_switch.9 mutex.9 \
|
||||
@ -98,6 +98,9 @@ MLINKS+=devstat.9 devstat_remove_entry.9 devstat.9 devstat_start_transaction.9
|
||||
MLINKS+=devstat.9 devstat_end_transaction.9
|
||||
MLINKS+=fetch.9 fubyte.9 fetch.9 fuswintr.9 fetch.9 fusword.9 fetch.9 fuword.9
|
||||
MLINKS+=ifnet.9 if_data.9 ifnet.9 ifaddr.9 ifnet.9 ifqueue.9
|
||||
MLINKS+=ithread.9 ithread_add_handler.9 ithread.9 ithread_create.9
|
||||
MLINKS+=ithread.9 ithread_destroy.9 ithread.9 ithread_priority.9
|
||||
MLINKS+=ithread.9 ithread_remove_handler.9 ithread.9 ithread_schedule.9
|
||||
MLINKS+=kernacc.9 useracc.9
|
||||
MLINKS+=kthread.9 kproc_start.9 kthread.9 kproc_shutdown.9
|
||||
MLINKS+=kthread.9 kthread_create.9 kthread.9 kthread_exit.9
|
||||
|
||||
355
share/man/man9/ithread.9
Normal file
355
share/man/man9/ithread.9
Normal file
@ -0,0 +1,355 @@
|
||||
.\" Copyright (c) 2001 John H. Baldwin <jhb@FreeBSD.org>
|
||||
.\" All rights reserved.
|
||||
.\"
|
||||
.\" Redistribution and use in source and binary forms, with or without
|
||||
.\" modification, are permitted provided that the following conditions
|
||||
.\" are met:
|
||||
.\" 1. Redistributions of source code must retain the above copyright
|
||||
.\" notice, this list of conditions and the following disclaimer.
|
||||
.\" 2. Redistributions in binary form must reproduce the above copyright
|
||||
.\" notice, this list of conditions and the following disclaimer in the
|
||||
.\" documentation and/or other materials provided with the distribution.
|
||||
.\"
|
||||
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
||||
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
||||
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
||||
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
||||
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
||||
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
||||
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
||||
.\" SUCH DAMAGE.
|
||||
.\"
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd February 10, 2001
|
||||
.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
|
||||
.Sh SYNOPSIS
|
||||
.Fd #include <sys/bus.h>
|
||||
.Fd #include <sys/interrupt.h>
|
||||
.Ft int
|
||||
.Fo ithread_add_handler
|
||||
.Fa "struct ithd *ithread"
|
||||
.Fa "const char *name"
|
||||
.Fa "driver_intr_t handler"
|
||||
.Fa "void *arg"
|
||||
.Fa "u_char pri"
|
||||
.Fa "enum intr_type flags"
|
||||
.Fa "void **cookiep"
|
||||
.Fc
|
||||
.Ft int
|
||||
.Fo ithread_create
|
||||
.Fa "struct ithd **ithread"
|
||||
.Fa "int vector"
|
||||
.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"
|
||||
.Ft int
|
||||
.Fn ithread_remove_handler "void *cookie"
|
||||
.Ft int
|
||||
.Fn ithread_schedule "struct ithd *ithread" "int do_switch"
|
||||
.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.
|
||||
.Pp
|
||||
The
|
||||
.Fn ithread_create
|
||||
function creates a new interrupt thread.
|
||||
The
|
||||
.Fa ithread
|
||||
argument points to an
|
||||
.Li struct ithd
|
||||
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 an or mask of properties of this thread.
|
||||
The only valid flag currently for
|
||||
.Fn ithread_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
|
||||
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
|
||||
agument list that is used to build the base name of the new ithread.
|
||||
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
|
||||
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
|
||||
function adds a new handler to an existing interrupt thread specified by
|
||||
.Fa ithread .
|
||||
The
|
||||
.Fa name
|
||||
argument specifies a name for this handler.
|
||||
The
|
||||
.Fa handler
|
||||
and
|
||||
.Fa arg
|
||||
arguments provide the function to execute for this handler and an argument
|
||||
to pass to it.
|
||||
The
|
||||
.Fa pri
|
||||
argument specifies the priority of this handler and is used both in sorting
|
||||
it in relation to the other handlers for this thread and to specify the
|
||||
priority of the backing kernel thread.
|
||||
The
|
||||
.Fa flags
|
||||
argument can be used to specify properties of this handler as defined in
|
||||
.Aq Pa sys/bus.h .
|
||||
If
|
||||
.Fa cookiep
|
||||
is not
|
||||
.Dv NULL ,
|
||||
then it will be assigned a cookie that can be used later to remove this
|
||||
handler.
|
||||
.Pp
|
||||
The
|
||||
.Fn ithread_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
|
||||
function schedules an interrupt thread to run.
|
||||
If the
|
||||
.Fa do_switch
|
||||
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
|
||||
.Po
|
||||
.Dv INTR_TYPE_*
|
||||
.Pc
|
||||
can be used to specify additional properties of both hardware and software
|
||||
interrupt handlers.
|
||||
The
|
||||
.Dv INTR_EXCL
|
||||
flag specifies that this handler can not 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.
|
||||
.Sh RETURN VALUES
|
||||
The
|
||||
.Fn ithread_add_handler ,
|
||||
.Fn ithread_create ,
|
||||
.Fn ithread_destroy ,
|
||||
.Fn ithread_remove_handler ,
|
||||
and
|
||||
.Fn ithread_schedule
|
||||
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
|
||||
and
|
||||
.Fn ithread_add_handler .
|
||||
.Bd -literal -offset indent
|
||||
int
|
||||
swi_add(struct ithd **ithdp, const char *name, driver_intr_t handler,
|
||||
void *arg, int pri, enum intr_type flags, void **cookiep)
|
||||
{
|
||||
struct proc *p;
|
||||
struct ithd *ithd;
|
||||
int error;
|
||||
|
||||
if (flags & (INTR_FAST | INTR_ENTROPY))
|
||||
return (EINVAL);
|
||||
|
||||
ithd = (ithdp != NULL) ? *ithdp : NULL;
|
||||
|
||||
if (ithd != NULL) {
|
||||
if ((ithd->it_flags & IT_SOFT) == 0)
|
||||
return(EINVAL);
|
||||
} else {
|
||||
error = ithread_create(&ithd, pri, IT_SOFT, NULL, NULL,
|
||||
"swi%d:", pri);
|
||||
if (error)
|
||||
return (error);
|
||||
|
||||
if (ithdp != NULL)
|
||||
*ithdp = ithd;
|
||||
}
|
||||
return (ithread_add_handler(ithd, name, handler, arg, pri + PI_SOFT,
|
||||
flags, cookiep));
|
||||
}
|
||||
.Ed
|
||||
.Sh ERRORS
|
||||
The
|
||||
.Fn ithread_add_handler
|
||||
function will fail if:
|
||||
.Bl -tag -width Er
|
||||
.It Bq Er EINVAL
|
||||
Any of the
|
||||
.Fa ithread ,
|
||||
.Fa handler ,
|
||||
or
|
||||
.Fa name
|
||||
arguments are
|
||||
.Dv NULL .
|
||||
.It Bq Er EINVAL
|
||||
The
|
||||
.Dv INTR_EXCL
|
||||
flag is specified and the interrupt thread
|
||||
.Fa ithread
|
||||
already has at least one handler, or the interrupt thread
|
||||
.Fa ithread
|
||||
already has an exclusive handler.
|
||||
.It Bq Er ENOMEM
|
||||
Could not allocate needed memory for this handler.
|
||||
.El
|
||||
.Pp
|
||||
The
|
||||
.Fn ithread_create
|
||||
function will fail if:
|
||||
.Bl -tag -width Er
|
||||
.It Bq Er EAGAIN
|
||||
The system-imposed limit on the total
|
||||
number of processes under execution would be exceeded.
|
||||
The limit is given by the
|
||||
.Xr sysctl 3
|
||||
MIB variable
|
||||
.Dv KERN_MAXPROC .
|
||||
.It Bq Er EINVAL
|
||||
A flag other than
|
||||
.Dv IT_SOFT
|
||||
was specified in the
|
||||
.Fa flags
|
||||
parameter.
|
||||
.It Bq Er ENOMEM
|
||||
Could not allocate needed memory for this interrupt thread.
|
||||
.El
|
||||
.Pp
|
||||
The
|
||||
.Fn ithread_destroy
|
||||
function will fail if:
|
||||
.Bl -tag -width Er
|
||||
.It Bq Er EINVAL
|
||||
The
|
||||
.Fa ithread
|
||||
argument is
|
||||
.Dv NULL .
|
||||
.It Bq Er EINVAL
|
||||
The interrupt thread pointed to by
|
||||
.Fa ithread
|
||||
has at least one handler.
|
||||
.El
|
||||
.Pp
|
||||
The
|
||||
.Fn ithread_remove_handler
|
||||
function will fail if:
|
||||
.Bl -tag -width Er
|
||||
.It Bq Er EINVAL
|
||||
The
|
||||
.Fa cookie
|
||||
argument is
|
||||
.Dv NULL .
|
||||
.El
|
||||
.Pp
|
||||
The
|
||||
.Fn ithread_schedule
|
||||
function will fail if:
|
||||
.Bl -tag -width Er
|
||||
.It Bq Er EINVAL
|
||||
The
|
||||
.Fa ithread
|
||||
argument is
|
||||
.Dv NULL .
|
||||
.It Bq Er EINVAL
|
||||
The interrupt thread pointed to by
|
||||
.Fa ithread
|
||||
has no interrupt handlers.
|
||||
.El
|
||||
.Sh SEE ALSO
|
||||
.Xr kthread 9 ,
|
||||
.Xr swi 9
|
||||
.Sh HISTORY
|
||||
Interrupt threads and their corresponding API first appeared in
|
||||
.Fx 5.0 .
|
||||
.Sh BUGS
|
||||
Currently
|
||||
.Li struct ithd
|
||||
represents both an interrupt source and an interrupt thread.
|
||||
There should be a separate
|
||||
.Li struct isrc
|
||||
that contains a vector number, enable and disable functions, etc. that
|
||||
an ithread holds a reference to.
|
||||
Loading…
x
Reference in New Issue
Block a user