134 lines
4.6 KiB
Groff
134 lines
4.6 KiB
Groff
|
.\" $NetBSD: softintr.9,v 1.1 2000/05/31 00:40:52 cgd 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
|
||
|
|
.\" by Christopher G. Demetriou.
|
||
|
|
.\" 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.
|
||
|
|
.\"
|
||
|
|
.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
|
||
|
|
.Fd #include <machine/intr.h>
|
||
|
|
.Ft void *
|
||
|
|
.Fn softintr_establish "int level" "int (*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/intr.h
|
||
|
|
include file must provide prototypes for the
|
||
|
|
.Nm
|
||
|
|
functions, must define the
|
||
|
|
.Dv __GENERIC_SOFT_INTERRUPTS
|
||
|
|
symbol (without a value), 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.
|
||
|
|
.El
|
||
|
|
.Sh AUTHOR
|
||
|
|
The
|
||
|
|
.Nx
|
||
|
|
machine-independent software interrupt framework was designed by
|
||
|
|
Charles Hannum <mycroft@NetBSD.ORG>.
|
||
|
|
.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 .
|