[src/trunk]: src Add nmi(9), a manual page for the x86-only

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

details:   https://anonhg.NetBSD.org/src/rev/71a6cc10982e
branches:  trunk
changeset: 752045:71a6cc10982e
user:      dyoung <dyoung%NetBSD.org@localhost>
date:      Fri Feb 12 00:45:37 2010 +0000

description:
Add nmi(9), a manual page for the x86-only
nmi_establish(9)/nmi_disestablish(9) routines.

diffstat:

 distrib/sets/lists/comp/mi        |   11 ++-
 share/man/man9/man9.i386/Makefile |    6 +-
 share/man/man9/man9.i386/nmi.9    |  144 ++++++++++++++++++++++++++++++++++++++
 3 files changed, 158 insertions(+), 3 deletions(-)

diffs (202 lines):

diff -r e4b35bbf71bb -r 71a6cc10982e distrib/sets/lists/comp/mi
--- a/distrib/sets/lists/comp/mi        Thu Feb 11 23:28:53 2010 +0000
+++ b/distrib/sets/lists/comp/mi        Fri Feb 12 00:45:37 2010 +0000
@@ -1,4 +1,4 @@
-#      $NetBSD: mi,v 1.1389 2010/02/11 23:28:53 haad Exp $
+#      $NetBSD: mi,v 1.1390 2010/02/12 00:45:37 dyoung Exp $
 #
 # Note: don't delete entries from here - mark them as "obsolete" instead.
 #
@@ -8897,6 +8897,9 @@
 ./usr/share/man/cat9/hz.0                      comp-sys-catman         .cat
 ./usr/share/man/cat9/i386/bios32_service.0     comp-sys-catman         .cat
 ./usr/share/man/cat9/i386/bioscall.0           comp-sys-catman         .cat
+./usr/share/man/cat9/i386/nmi.0                        comp-sys-catman         .cat
+./usr/share/man/cat9/i386/nmi_disestablish.0   comp-sys-catman         .cat
+./usr/share/man/cat9/i386/nmi_establish.0      comp-sys-catman         .cat
 ./usr/share/man/cat9/i386/spllower.0           comp-sys-catman         .cat
 ./usr/share/man/cat9/i386/splraise.0           comp-sys-catman         .cat
 ./usr/share/man/cat9/i386/return_address.0     comp-sys-catman         .cat
@@ -14476,6 +14479,9 @@
 ./usr/share/man/html9/hz.html                  comp-sys-htmlman        html
 ./usr/share/man/html9/i386/bios32_service.html comp-sys-htmlman        html
 ./usr/share/man/html9/i386/bioscall.html       comp-sys-htmlman        html
+./usr/share/man/html9/i386/nmi.html            comp-sys-htmlman        html
+./usr/share/man/html9/i386/nmi_disestablish.html       comp-sys-htmlman        html
+./usr/share/man/html9/i386/nmi_establish.html          comp-sys-htmlman        html
 ./usr/share/man/html9/i386/return_address.html comp-sys-htmlman        html
 ./usr/share/man/html9/i386/spllower.html       comp-sys-htmlman        html
 ./usr/share/man/html9/i386/splraise.html       comp-sys-htmlman        html
@@ -20210,6 +20216,9 @@
 ./usr/share/man/man9/hz.9                      comp-sys-man            .man
 ./usr/share/man/man9/i386/bios32_service.9     comp-sys-man            .man
 ./usr/share/man/man9/i386/bioscall.9           comp-sys-man            .man
+./usr/share/man/man9/i386/nmi.9                        comp-sys-man            .man
+./usr/share/man/man9/i386/nmi_disestablish.9   comp-sys-man            .man
+./usr/share/man/man9/i386/nmi_establish.9      comp-sys-man            .man
 ./usr/share/man/man9/i386/return_address.9     comp-sys-man            .man
 ./usr/share/man/man9/i386/spllower.9           comp-sys-man            .man
 ./usr/share/man/man9/i386/splraise.9           comp-sys-man            .man
diff -r e4b35bbf71bb -r 71a6cc10982e share/man/man9/man9.i386/Makefile
--- a/share/man/man9/man9.i386/Makefile Thu Feb 11 23:28:53 2010 +0000
+++ b/share/man/man9/man9.i386/Makefile Fri Feb 12 00:45:37 2010 +0000
@@ -1,7 +1,9 @@
-#      $NetBSD: Makefile,v 1.4 2010/02/06 22:32:08 dyoung Exp $
+#      $NetBSD: Makefile,v 1.5 2010/02/12 00:45:37 dyoung Exp $
 
-MAN=   bioscall.9 bios32_service.9 return_address.9 splraise.9
+MAN=   bioscall.9 bios32_service.9 nmi.9 return_address.9 splraise.9
 MANSUBDIR=/i386
 MLINKS+=splraise.9 spllower.9
+MLINKS+=nmi.9 nmi_establish.9
+MLINKS+=nmi.9 nmi_disestablish.9
 
 .include <bsd.man.mk>
diff -r e4b35bbf71bb -r 71a6cc10982e share/man/man9/man9.i386/nmi.9
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/man9.i386/nmi.9    Fri Feb 12 00:45:37 2010 +0000
@@ -0,0 +1,144 @@
+.\"     $NetBSD: nmi.9,v 1.1 2010/02/12 00:45:38 dyoung Exp $
+.\"
+.\" Copyright (c) 2010 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by David Young.
+.\"
+.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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.
+.\"
+.Dd February 9, 2010
+.Dt NMI 9
+.Os
+.Sh NAME
+.Nm nmi ,
+.Nm nmi_establish ,
+.Nm nmi_disestablish ,
+.Nd NMI 
+.Sh SYNOPSIS
+.In x86/nmi.h
+.Ft nmi_handler_t *
+.Fn nmi_establish "int (*func)(const struct trapframe *, void *)" "void *arg"
+.Ft void
+.Fn nmi_disestablish "nmi_handler_t *handle"
+.Sh DESCRIPTION
+The
+.Nm
+interface lets the kernel establish handlers for x86 Non-Maskable
+Interrupts (NMIs).
+An NMI signals to the processor an exception on a processor, memory
+controller, or I/O bus that is irrecoverable or else needs attention
+at a high priority.
+A
+.Dq "debug switch"
+or a performance/watchdog timer may also trigger an NMI.
+.Pp
+An NMI handler will run to completion on the same processor where
+it began without being preempted by any thread or interrupt except
+for another NMI.
+An NMI handler must prepare for re-entry.
+An NMI handler may run simultaneously on more than one CPU.
+.Pp
+Synchronizing access to a shared data structure from
+an NMI handler is a different challenge than synchronizing access
+from hardware/software interrupt routines or from kernel threads.
+An NMI handler may not perform any operation that may sleep, acquire
+a mutex, or schedule a software interrupt.
+An NMI handler may use
+.Xr atomic_ops 3 .
+An NMI handler may reference per-CPU storage
+.Po
+.Xr percpu 9
+.Pc .
+.Pp
+An NMI handler may not write to the kernel message buffer.
+.Sh FUNCTIONS
+.Bl -tag -width compact
+.It Fn nmi_establish "func" "arg"
+Call this in thread context to establish a handler for non-maskable
+interrupts.
+Establish
+.Fa func
+as one of the handler functions to call when an NMI occurs.
+Where
+.Fa tf
+is a
+.Vt struct trapframe
+representation of the processor context where the NMI was received,
+and
+.Fa arg
+is the argument to
+.Fn nmi_establish ,
+the kernel will call
+.Fo (*func)
+.Fa tf
+.Fa arg
+.Fc
+every time an NMI occurs until the handler is removed with
+.Fn nmi_disestablish .
+.Fa func
+should return non-zero if it handled a condition that causes
+NMI, or zero if it did not.
+If, for a given NMI, all handlers return zero, the system will
+panic or enter the kernel debugger,
+.Xr ddb 4 .
+.Fn nmi_establish
+returns
+.Dv NULL
+on failure, and a handle for the NMI handler on success.
+.It Fn nmi_disestablish "handle"
+Call this in thread context to stop the kernel from calling an NMI
+handler.
+Indicate the handler to disestablish with the
+.Fa handle
+returned by
+.Fn nmi_establish .
+.El
+.Sh CODE REFERENCES
+This section describes places within the
+.Nx
+source tree where actual code implementing the
+.Nm
+interface
+can be found.
+All pathnames are relative to
+.Pa /usr/src .
+.Pp
+The
+.Nm
+interface is implemented within the file
+.Pa sys/arch/x86/x86/nmi.c .
+.\" .Sh EXAMPLES
+.Sh SEE ALSO
+.Xr atomic_ops 3 ,
+.Xr ddb 4
+.Sh HISTORY
+The
+.Nm
+interface first appeared in
+.Nx 6.0 .
+.Sh AUTHORS
+.An YAMAMOTO Takashi Aq yamt%NetBSD.org@localhost
+.\" .Sh CAVEATS
+.\" .Sh BUGS
+.\" .Sh SECURITY CONSIDERATIONS