.\" 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: src/share/man/man9/ithread.9,v 1.12.10.1.6.1 2010/12/21 17:09:25 kensmith Exp $
.\"
.Dd August 25, 2006
.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
.In sys/param.h
.In sys/bus.h
.In 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
.Vt 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 a 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
argument 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
.In 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
.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 ,
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 malloc 9 ,
.Xr swi 9 ,
.Xr uma 9
.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.