mirror of
https://github.com/freebsd/freebsd-src
synced 2024-09-29 05:04:50 +00:00
Describe the new software interrupt thread functionality.
Reviewed by: sheldonh, jasone
This commit is contained in:
parent
eaca618337
commit
dc4e9f1a03
Notes:
svn2git
2020-12-20 02:59:44 +00:00
svn path=/head/; revision=68686
|
@ -16,7 +16,7 @@ MAN9= CONDSPLASSERT.9 KASSERT.9 MD5.9 SPLASSERT.9 \
|
|||
devtoname.9 fetch.9 ifnet.9 inittodr.9 intro.9 kernacc.9 malloc.9 \
|
||||
make_dev.9 microseq.9 mi_switch.9 mutex.9 namei.9 panic.9 pfil.9 physio.9 \
|
||||
posix4.9 psignal.9 random.9 resettodr.9 rtalloc.9 rtentry.9 sleep.9 spl.9 \
|
||||
store.9 style.9 suser.9 time.9 timeout.9 uio.9 \
|
||||
store.9 style.9 suser.9 swi.9 time.9 timeout.9 uio.9 \
|
||||
vget.9 vnode.9 vput.9 vref.9 vrele.9 vslock.9 \
|
||||
mbuf.9 microtime.9 microuptime.9 tvtohz.9
|
||||
|
||||
|
@ -92,6 +92,7 @@ MLINKS+=spl.9 splbio.9 spl.9 splclock.9 spl.9 splhigh.9 spl.9 splimp.9
|
|||
MLINKS+=spl.9 splnet.9 spl.9 splsoftclock.9 spl.9 splsofttty.9
|
||||
MLINKS+=spl.9 splstatclock.9 spl.9 spltty.9 spl.9 splvm.9 spl.9 splx.9
|
||||
MLINKS+=store.9 subyte.9 store.9 suswintr.9 store.9 susword.9 store.9 suword.9
|
||||
MLINKS+=swi.9 sched_swi.9 swi.9 sinthand_add.9
|
||||
MLINKS+=time.9 boottime.9 time.9 mono_time.9 time.9 runtime.9
|
||||
MLINKS+=timeout.9 untimeout.9
|
||||
MLINKS+=timeout.9 callout_handle_init.9 timeout.9 callout_init.9
|
||||
|
|
203
share/man/man9/swi.9
Normal file
203
share/man/man9/swi.9
Normal file
|
@ -0,0 +1,203 @@
|
|||
.\" Copyright (c) 2000 John H. Baldwin
|
||||
.\" 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 October 30, 2000
|
||||
.Dt SWI 9
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm sched_swi ,
|
||||
.Nm sinthand_add
|
||||
.Nd register and schedule software interrupt handlers
|
||||
.Sh SYNOPSIS
|
||||
.Fd #include <sys/bus.h>
|
||||
.Fd #include <sys/proc.h>
|
||||
.Fd #include <sys/interrupt.h>
|
||||
.Vt extern struct ithd *tty_ithd;
|
||||
.Vt extern struct ithd *clk_ithd;
|
||||
.Vt extern struct intrhand *net_ih;
|
||||
.Vt extern struct intrhand *softclock_ih;
|
||||
.Vt extern struct intrhand *vm_ih;
|
||||
.Ft void
|
||||
.Fn sched_swi "struct intrhand *handler" "int flags"
|
||||
.Ft struct intrhand *
|
||||
.Fo sinthand_add
|
||||
.Fa "const char *name"
|
||||
.Fa "struct ithd **thread"
|
||||
.Fa "driver_intr_t handler"
|
||||
.Fa "void *arg"
|
||||
.Fa "int pri"
|
||||
.Fa "int flags"
|
||||
.Fc
|
||||
.Sh DESCRIPTION
|
||||
These functions are used to register and schedule software interrupt handlers.
|
||||
Software interrupt handlers are attached to a software interrupt thread, just
|
||||
as hardware interrupt handlers are attached to a hardware interrupt thread.
|
||||
This means that multiple handlers can be attached to the same thread.
|
||||
Software interrupt handlers can be used to queue up less critical processing
|
||||
inside of hardware interrupt handlers so that the work can be done at a later
|
||||
time.
|
||||
Software interrupt threads are different from other kernel threads in that they
|
||||
are treated as an interrupt thread.
|
||||
This means that time spent executing these threads is counted as interrupt
|
||||
time, and that they can be run via a lightweight context switch during
|
||||
.Fn ast .
|
||||
.Pp
|
||||
The
|
||||
.Fn sinthand_add
|
||||
function is used to register a new software interrupt handler.
|
||||
The
|
||||
.Fa name
|
||||
argument is used to associate a name with a specific handler.
|
||||
This name is appended to the name of the software interrupt thread that this
|
||||
handler is attached to.
|
||||
The
|
||||
.Fa thread
|
||||
argument is an optional pointer to a
|
||||
.Li struct ithd
|
||||
pointer.
|
||||
If this argument points to an existing software interrupt thread, then this
|
||||
handler will be attached to that thread.
|
||||
Otherwise a new thread will be created, and if
|
||||
.Fa thread
|
||||
is not
|
||||
.Dv NULL ,
|
||||
then the pointer at that address to will be modified to point to the
|
||||
newly created thread.
|
||||
The
|
||||
.Fa handler
|
||||
is the function that will be called when the handler is scheduled to run.
|
||||
The
|
||||
.Fa arg
|
||||
parameter will be passed in as the only parameter to
|
||||
.Fa handler
|
||||
when the function is executed.
|
||||
The
|
||||
.Fa pri
|
||||
value specifies the priority to assign to an interrupt thread if one is created,
|
||||
and the
|
||||
.Fa flags
|
||||
argument is used to specify the attributes of a handler such as
|
||||
.Dv INTR_MPSAFE .
|
||||
.Fn sinthand_add
|
||||
returns a pointer to a
|
||||
.Li struct intrhand
|
||||
which is used later to schedule the handler to run.
|
||||
.Pp
|
||||
The
|
||||
.Fn sched_swi
|
||||
function is used to schedule an interrupt handler and its associated thread to
|
||||
run.
|
||||
The
|
||||
.Fa handler
|
||||
argument specifies which software interrupt handler should be scheduled to run.
|
||||
The
|
||||
.Fa flags
|
||||
argument specifies how and when the handler should be run and is a mask of one
|
||||
or more of the following flags:
|
||||
.Bl -tag -width SWI_NOSWITCH
|
||||
.It Dv SWI_SWITCH
|
||||
Specifies that the kernel should schedule the software interrupt thread
|
||||
associated with the specified handler to run. If lightweight context switches
|
||||
are in place, then the kernel will switch to this thread and run it
|
||||
immediately.
|
||||
.It Dv SWI_NOSWITCH
|
||||
Specifies that the kernel should schedule the software interrupt thread
|
||||
associated with the specified handler to run, but it should not attempt to
|
||||
switch to the thread immediately.
|
||||
.It Dv SWI_DELAY
|
||||
Specifies that the kernel should mark the specified handler as needing to run,
|
||||
but the kernel should not schedule the software interrupt thread to run.
|
||||
Instead,
|
||||
.Fa handler
|
||||
will be executed the next time that the software interrupt thread runs after
|
||||
being scheduled by another event.
|
||||
Attaching a handler to the clock software interrupt thread and using this flag
|
||||
when scheduling a software interrupt handler can be used to implement the
|
||||
functionality previously performed by
|
||||
.Fn setdelayed .
|
||||
.El
|
||||
.Pp
|
||||
The
|
||||
.Va tty_ithd
|
||||
and
|
||||
.Va clk_ithd
|
||||
variables contain pointers to the software interrupt threads for the tty and
|
||||
clock software interrupts, respectively.
|
||||
.Va tty_ithd
|
||||
is used to hang tty software interrupt handlers off of the same thread.
|
||||
.Va clk_ithd
|
||||
is used to hang delayed handlers off of the clock software interrupt thread so
|
||||
that the functionality of
|
||||
.Fn setdelayed
|
||||
can be obtained in conjuction with
|
||||
.Dv SWI_DELAY .
|
||||
The
|
||||
.Va net_ih ,
|
||||
.Va softclock_ih ,
|
||||
and
|
||||
.Va vm_ih
|
||||
handler cookies are used to schedule software interrupt threads to run for the
|
||||
networking stack, clock interrupt, and VM subsystem respectively.
|
||||
.Sh RETURN VALUES
|
||||
The
|
||||
.Fn sinthand_add
|
||||
function returns a pointer to the newly created
|
||||
.Li struct intrhand
|
||||
if successful or
|
||||
.Dv NULL
|
||||
on error.
|
||||
.Sh SEE ALSO
|
||||
.Xr taskqueue 9
|
||||
.Sh HISTORY
|
||||
The
|
||||
.Fn sinthand_add
|
||||
and the
|
||||
.Fn sched_swi
|
||||
functions first appeared in
|
||||
.Fx 5.0 .
|
||||
.Sh BUGS
|
||||
The
|
||||
.Fn sinthand_add
|
||||
function currently doesn't check for or allow for the
|
||||
.Dv INTR_EXCL
|
||||
flag to be used to allow a software interrupt handler to have exclusive
|
||||
access to a particular software interrupt thread.
|
||||
There is also no checking to verify that one does not add a software interrupt
|
||||
handler to a hardware interrupt thread.
|
||||
.Pp
|
||||
The
|
||||
.Fn sinthand_add
|
||||
function should really return an error code and use a
|
||||
.Fa "void **cookiep"
|
||||
argument to return a cookie that is passed in as the first argument to
|
||||
.Fn sched_swi
|
||||
instead of exposing the
|
||||
.Li struct intrhand
|
||||
type.
|
||||
.Pp
|
||||
Most of the global variables described in this manual page should not be
|
||||
global, or at the very least should not be declared in
|
||||
.Aq Pa sys/interrupt.h .
|
Loading…
Reference in a new issue