143 lines
4.9 KiB
Groff
143 lines
4.9 KiB
Groff
.\" $NetBSD: softintr.9,v 1.12 2003/04/16 13:35:33 wiz Exp $
|
|
.\"
|
|
.\" Copyright (c) 2000 Christopher G. Demetriou.
|
|
.\" 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.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed for the
|
|
.\" NetBSD Project. See http://www.NetBSD.org/ for
|
|
.\" information about NetBSD.
|
|
.\" 4. The name of the author may not be used to endorse or promote products
|
|
.\" derived from this software without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 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.
|
|
.\"
|
|
.\" --(license Id: LICENSE.proto,v 1.1 2000/06/13 21:40:26 cgd Exp )--
|
|
.\"
|
|
.Dd May 30, 2000
|
|
.Dt SOFTINTR 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm softintr ,
|
|
.Nm softintr_establish ,
|
|
.Nm softintr_disestablish ,
|
|
.Nm softintr_schedule
|
|
.Nd machine-independent software interrupt framework
|
|
.Sh SYNOPSIS
|
|
.In machine/intr.h
|
|
.Ft void *
|
|
.Fn softintr_establish "int level" "void (*fun)(void *)" "void *arg"
|
|
.Ft void
|
|
.Fn softintr_disestablish "void *cookie"
|
|
.Ft void
|
|
.Fn softintr_schedule "void *cookie"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nx
|
|
machine-independent software interrupt framework is designed to provide
|
|
a generic software interrupt mechanism which can be used any time a
|
|
low-priority callback is needed.
|
|
It allows dynamic registration of software interrupts for loadable
|
|
drivers and protocol stacks, prioritization and fair queueing of software
|
|
interrupts, and allows machine-dependent optimizations to reduce cost
|
|
and code complexity.
|
|
.Pp
|
|
In order to provide this framework, the machine-dependent
|
|
.Aq Pa machine/types.h
|
|
must define the
|
|
.Dv __HAVE_GENERIC_SOFT_INTERRUPTS
|
|
symbol (without a value),
|
|
furthermore, the machine-dependent
|
|
.Aq Pa machine/intr.h
|
|
include file must provide prototypes for the
|
|
.Nm
|
|
functions and must provide definitions of
|
|
several constants which define software interrupt priority levels
|
|
(IPLs):
|
|
.Bl -tag -width "IPL_SOFTSERIAL"
|
|
.It Dv IPL_SOFTCLOCK
|
|
The software IPL for software clock interrupts
|
|
.Pq i.e., Fn softclock .
|
|
.It Dv IPL_SOFTNET
|
|
The software IPL for network callbacks.
|
|
.It Dv IPL_SOFTSERIAL
|
|
The software IPL for serial driver callbacks.
|
|
.El
|
|
.Pp
|
|
Other constants of the form
|
|
.Dv IPL_SOFT*
|
|
are reserved for future use by this framework.
|
|
.Pp
|
|
The following is a brief description of each function in the framework:
|
|
.Bl -tag -width "softintr_disestablish()"
|
|
.It Fn softintr_establish
|
|
Register a software interrupt at level
|
|
.Fa level ,
|
|
which will call the function
|
|
.Fa fun
|
|
with one
|
|
argument,
|
|
.Fa arg .
|
|
It may allocate a machine-specific data structure.
|
|
If successful,
|
|
.Fn softintr_establish
|
|
returns a
|
|
.Pf non- Dv NULL
|
|
opaque cookie which can be used as an argument to
|
|
.Fn softintr_schedule
|
|
or
|
|
.Fn softintr_disestablish .
|
|
If for some reason it does not succeed, it returns
|
|
.Dv NULL .
|
|
.It Fn softintr_disestablish
|
|
Deallocate a software interrupt previously allocated
|
|
by a call to
|
|
.Fn softintr_establish .
|
|
.\" XXX What happens to pending scheduled calls?
|
|
.It Fn softintr_schedule
|
|
Schedule a software interrupt previously allocated
|
|
by a call to
|
|
.Fn softintr_establish
|
|
to be executed as soon as that software interrupt is unblocked.
|
|
This function may assume that the interrupt is currently blocked,
|
|
so it need not check to see if the interrupt needs to be executed
|
|
immediately.
|
|
.Fn softintr_schedule
|
|
can safely be called multiple times before the
|
|
callback routine is invoked.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr spl 9
|
|
.Sh HISTORY
|
|
The
|
|
.Nx
|
|
machine-independent software interrupt framework was designed in 1997
|
|
and was implemented by one port in
|
|
.Nx 1.3 .
|
|
However, it did not gain wider implementation until
|
|
.Nx 1.5 .
|
|
.Sh AUTHORS
|
|
The
|
|
.Nx
|
|
machine-independent software interrupt framework was designed by
|
|
.An Charles Hannum
|
|
.Aq mycroft@NetBSD.org .
|