MCE-INJECT(8)

💖 MCE-INJECT 💖

okay bestie, so the manual name is mce-inject, it lives in section 8 of Linux's Administrator's Manual, and it is genuinely one of the most niche little gremlins in the whole toolbox. sit down, hydrate, let's go 🫶

✨ NAME ✨

mce-inject — inject machine checks into x86 kernel for testing 💅

🌸 SYNOPSIS 🌸

mce-inject mce-file1 ...
mce-inject < mce-file

🦋 DESCRIPTION 🦋

so mce-inject lets you inject machine checks into a running x86 Linux kernel. and what even is a machine check? it's an internal CPU error, bestie — the CPU basically raising its hand like "something went wrong in here 😭". this tool exists to test the machine check handling code. that's the whole job. testing.

here's the tea though: the injection only happens on the software level, and it does not simulate full machine check handling on the platform level. so don't come for it expecting the whole hardware drama, it's not giving that.

the machine checks you're injecting are described in an input language that's similar to the format the kernel outputs on a panic message (with a few extension). and generally? you should be able to just pipe in a panic message to inject that mce. iconic, honestly. 💅

for the details on fields, go read the IA32 SDM Vol3a chapter 14 — they correspond to the machine check MSRs of the standard IA32 Machine check architecture described there. iykyk 📚

👑 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. no cap.

• the machine check always starts with MCE or CPU number|broadcast [bank-number] — Machine check is injected on CPU xx or broadcasted to all CPUs
• BANK bank-number — Machine check bank to inject on.
• 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.
• 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.
• ADDR number
• RIP number / RIP number:<number>{string} / RIP number:number
• MISC number
• CPU number : machine check exception : number BANK number : number — parsed for compatibility with kernel output. Use explicit statements
• TSC number — TSC state injected in machine check
• NOBROADCAST — Don't broadcast exceptions to all CPUs. Default is to broadcast UC
• IRQBROADCAST — Broadcast IRQ to all CPUs that not getting error injection.
• NMIBROADCAST — Broadcast NMI to all CPUs that not getting error injection.
• IN_IRQ — MCE should be injected in interrupt context
• IN_PROC — MCE injected in process context.
• HOLD — Don't inject MCE immediately but hold it for later injection. This is useful for testing injection on multiple CPUs in parallel
• SOCKETID number — Socketid. Ignored by kernel on injection.
• MCGCAP number — Machine check capabilities register value. Currently ignored by kernel on injection.
• POLL — Inject in machine check poller code.
• EXCP — Inject as machine check exception.
• APICID number — APIC ID of CPU. Ignored by kernel on injection.

a list of symbols ors the symbols together. ✨

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. 💖

🔥 REQUIREMENTS 🔥

• mce-inject needs to run as root. no exceptions, bestie, it's giving privilege.
• /dev/mcelog has to exist.
• the kernel needs to have machine check injection ( CONFIG_X86_MCE_INJECT ) enabled, and if modular, the mce-inject module loaded.
• this option is available in Linux 2.6.31 or later.

🎀 NOTES 🎀

the mce-test package has a lot of input file examples. go raid it. 🍓

🌈 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 Appendix E in Part2.
• Datasheet of your CPU.

fr fr though, read the SDM chapter before you start poking at MSRs. it's giving "main character energy" but make it informed. 💀

and that's the whole page, bestie!! 🥳 this absolute banger of a manual was brought to you by Intel OTC, dated May 2009 — yes, 2009, ancient, historic, a relic, and yet here we are still reading it in the group chat. periodt. 👑💜