1.\" $NetBSD: nmi.9,v 1.5 2014/03/18 18:20:40 riastradh Exp $ 2.\" 3.\" Copyright (c) 2010 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by David Young. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd March 17, 2011 31.Dt NMI 9 x86 32.Os 33.Sh NAME 34.Nm nmi , 35.Nm nmi_establish , 36.Nm nmi_disestablish , 37.Nd NMI 38.Sh SYNOPSIS 39.In x86/nmi.h 40.Ft nmi_handler_t * 41.Fn nmi_establish "int (*func)(const struct trapframe *, void *)" "void *arg" 42.Ft void 43.Fn nmi_disestablish "nmi_handler_t *handle" 44.Sh DESCRIPTION 45The 46.Nm 47interface lets the kernel establish handlers for x86 Non-Maskable 48Interrupts (NMIs). 49An NMI signals to the processor an exception on a processor, memory 50controller, or I/O bus that is irrecoverable or else needs attention 51at a high priority. 52A 53.Dq "debug switch" 54or a performance/watchdog timer may also trigger an NMI. 55.Pp 56An NMI handler will run to completion on the same processor where 57it began without being preempted by any thread or interrupt except 58for another NMI. 59An NMI handler must prepare for re-entry. 60An NMI handler may run simultaneously on more than one CPU. 61.Pp 62Synchronizing access to a shared data structure from 63an NMI handler is a different challenge than synchronizing access 64from hardware/software interrupt routines or from kernel threads. 65An NMI handler may not perform any operation that may sleep, acquire 66a mutex, or schedule a software interrupt. 67An NMI handler may use 68.Xr atomic_ops 3 . 69An NMI handler may reference per-CPU storage 70.Po 71.Xr percpu 9 72.Pc . 73.Pp 74An NMI handler may not write to the kernel message buffer. 75.Sh FUNCTIONS 76.Bl -tag -width compact 77.It Fn nmi_establish "func" "arg" 78Call this in thread context to establish a handler for non-maskable 79interrupts. 80Establish 81.Fa func 82as one of the handler functions to call when an NMI occurs. 83Where 84.Fa tf 85is a 86.Vt struct trapframe 87representation of the processor context where the NMI was received, 88and 89.Fa arg 90is the argument to 91.Fn nmi_establish , 92the kernel will call 93.Fo (*func) 94.Fa tf 95.Fa arg 96.Fc 97every time an NMI occurs until the handler is removed with 98.Fn nmi_disestablish . 99.Fa func 100should return non-zero if it handled a condition that causes 101NMI, or zero if it did not. 102If, for a given NMI, all handlers return zero, the system will 103panic or enter the kernel debugger, 104.Xr ddb 4 . 105.Fn nmi_establish 106returns 107.Dv NULL 108on failure, and a handle for the NMI handler on success. 109.It Fn nmi_disestablish "handle" 110Call this in thread context to stop the kernel from calling an NMI 111handler. 112Indicate the handler to disestablish with the 113.Fa handle 114returned by 115.Fn nmi_establish . 116.El 117.Sh CODE REFERENCES 118The 119.Nm 120interface is implemented within the file 121.Pa sys/arch/x86/x86/nmi.c . 122.\" .Sh EXAMPLES 123.Sh SEE ALSO 124.Xr atomic_ops 3 , 125.Xr ddb 4 126.Sh HISTORY 127The 128.Nm 129interface first appeared in 130.Nx 6.0 . 131.Sh AUTHORS 132.An YAMAMOTO Takashi Aq Mt yamt@NetBSD.org 133.\" .Sh CAVEATS 134.\" .Sh BUGS 135.\" .Sh SECURITY CONSIDERATIONS 136