[src/trunk]: src/share/man/man9 documentation of the NetBSD machine-independe...

[cgd <cgd%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/778add829f22
branches:  trunk
changeset: 486925:778add829f22
user:      cgd <cgd%NetBSD.org@localhost>
date:      Wed May 31 00:40:51 2000 +0000

description:
documentation of the NetBSD machine-independent software interrupt
framework, dredged out of the January, 1997 tech-kern e-mail archives.

diffstat:

 share/man/man9/Makefile   |    6 +-
 share/man/man9/softintr.9 |  133 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 137 insertions(+), 2 deletions(-)

diffs (164 lines):

diff -r a1d1e48c828f -r 778add829f22 share/man/man9/Makefile
--- a/share/man/man9/Makefile   Wed May 31 00:16:16 2000 +0000
+++ b/share/man/man9/Makefile   Wed May 31 00:40:51 2000 +0000
@@ -1,4 +1,4 @@
-#       $NetBSD: Makefile,v 1.60 2000/04/15 17:20:26 augustss Exp $
+#       $NetBSD: Makefile,v 1.61 2000/05/31 00:40:51 cgd Exp $
 
 #      Makefile for section 9 (kernel function and variable) manual pages.
 
@@ -9,7 +9,7 @@
        log.9 malloc.9 mbuf.9 microtime.9 panic.9 pfil.9 physio.9 pool.9 \
        powerhook_establish.9 psignal.9 ratecheck.9 resettodr.9 rnd.9 \
        rt_timer.9 shutdownhook_establish.9 \
-       sleep.9 spl.9 store.9 time.9 uiomove.9 ucom.9 usbdi.9 uvm.9 \
+       sleep.9 softintr.9 spl.9 store.9 time.9 uiomove.9 ucom.9 usbdi.9 uvm.9 \
        wdc.9
 MLINKS+=arp.9 arp_ifinit.9 arp.9 arpresolve.9 arp.9 arpintr.9
 MLINKS+=access.9 kernacc.9 access.9 useracc.9
@@ -101,6 +101,8 @@
 MLINKS+=psignal.9 pgsignal.9 psignal.9 gsignal.9
 MLINKS+=shutdownhook_establish.9 shutdownhook_disestablish.9
 MLINKS+=sleep.9 wakeup.9 sleep.9 tsleep.9
+MLINKS+=softintr.9 softintr_establish.9 softintr.9 softintr_disestablish.9 \
+       softintr.9 softintr_schedule.9
 MLINKS+=spl.9 spl0.9 spl.9 splbio.9 spl.9 splclock.9 spl.9 splhigh.9 \
        spl.9 splimp.9 spl.9 spllowersoftclock.9 spl.9 splnet.9 \
        spl.9 splsched.9 spl.9 splserial.9 \
diff -r a1d1e48c828f -r 778add829f22 share/man/man9/softintr.9
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/softintr.9 Wed May 31 00:40:51 2000 +0000
@@ -0,0 +1,133 @@
+.\" $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@localhost>.
+.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 .