.\"     $NetBSD: nmi.9,v 1.5 2014/03/18 18:20:40 riastradh 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 March 17, 2011
.Dt NMI 9 x86
.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
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 Mt yamt@NetBSD.org
.\" .Sh CAVEATS
.\" .Sh BUGS
.\" .Sh SECURITY CONSIDERATIONS