path: root/share/man/man9/swi.9

.\" 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 .