mce-inject.8

.TH MCE-INJECT 8 "May 2009" "Intel OTC" "Linux's Administrator's Manual"
.SH NAME
mce-inject \- Inject machine checks into x86 kernel for testing
.SH SYNOPSIS
mce-inject mce-file1 ...
.br
mce-inject < mce-file
.SH DESCRIPTION
mce-inject allows to inject machine checks in a running x86 Linux kernel.
machine checks are internal CPU errors. This tool is intended to 
test the machine check handling code.
The injection only happens on the software level and does
not simulate full machine check handling on the platform level.
The machine checks to be injected are described in a input language similar
to the format the kernel outputs on a panic message (with a few extension).
In general you should be able to pipe in a panic message to inject
that mce.
See the IA32 SDM Vol3a chapter 14 for the details on fields. They correspond
to the machine check MSRs of the standard IA32 Machine check architecture
described there.
.SH INPUT LANGUAGE
These generally represent the similarly CPU MSRs, with some
metadata on where to inject the exception. Please see 
the IA software developers Manual for more details.

The machine check always starts with
.I MCE
or
.I CPU number|broadcast [bank-number]
Machine check is injected on CPU xx or broadcasted to all CPUs

.I BANK bank-number
Machine check bank to inject on.

.I STATUS {number|fatal|corrected|uncorrected|pcc|uc|val|en|over|ar|ucna|srao|srar|s}

The symbols generally represent hardware register bits, as documented in the Intel
software developer's manual. 
When multiple are listed they are ored together.

.I MCGSTATUS {number|mcip|ripv|eipv}

The symbols generally represent hardware register bits, as documented in the Intel
software developer's manual. 
When multiple are listed they are ored together.

.I ADDR number

.I RIP number
.I RIP number:<number>{string}
.I RIP number:number

.I MISC number

.I CPU number : machine check exception : number BANK number : number
parsed for compatibility with kernel output. Use explicit statements

.I TSC number
TSC state injected in machine check

.I NOBROADCAST
Don't broadcast exceptions to all CPUs. Default is to broadcast UC

.I IN_IRQ
MCE should be injected in interrupt context

.I IN_PROC
MCE injected in process context.

.I HOLD
Don't inject MCE immediately but hold it for later injection. This is useful 
for testing injection on multiple CPUs in parallel

.I SOCKETID number
Socketid. Ignored by kernel on injection.

.I MCGCAP number
Machine check capabilities register value. Currently ignored by kernel on injection.

.I POLL
Inject in machine check poller code.

.I EXCP
Inject as machine check exception.

.I APICID number
APIC ID of CPU. Ignored by kernel on injection.

A list of symbols ors the symbols together.

.TE

Multiple fields can be on a line.
number can be hex/octal/decimal in the usual C format.
Multiple machine checks can be in a single file, each new one
starts with "CPU" or "MCE".
For all missing fields reasonable default values are filled in
(hopefully)
Comments start with # until the end of the line
The keywords are case-insensitive.
.SH REQUIREMENTS
mce-inject to run as root. /dev/mcelog has to exist. The kernels needs
to have machine check injection (
.I CONFIG_X86_MCE_INJECT
) enabled and if modular the mce-inject module loaded. This option is 
available in Linux 2.6.31 or later.
.SH NOTES
The 
.I mce-test
package has a lot of input file examples.
.SH SEE ALSO
Intel 64 and IA32 Architectures Software Developer's manual, Volume 3, 
System programming guide
Parts 1 and 2. Machine checks are described in Chapter 14 in Part1 and in Append
ix E in Part2.

Datasheet of your CPU.