IPMCTL-INJECT-ERROR(1)

📦
version 03.00.00.0485 · 6 versions
, in ubuntu noble, ubuntu questing

💖 ipmctl-inject-error — the manual page, but make it make sense 💖

okay bestie, you found your way into the ipmctl manual, and specifically the ipmctl-inject-error(1) page. welcome. pull up a chair, grab a strawberry 🍓, and let's get into it.

✨ NAME ✨

ipmctl-inject-error — injects an error, or clears an error you already injected. yes, on purpose. for testing. icon behaviour honestly.

✨ SYNOPSIS ✨

ipmctl set [OPTIONS] -dimm [TARGETS] [PROPERTIES]

✨ DESCRIPTION ✨

so basically: this command injects an error onto one or more PMem modules, or clears one you injected earlier. it's a testing thing, not a "let's actually break production" thing, but like… be normal about it, okay? 🫶

✨ OPTIONS ✨

  • -h, -help — shows you the help for this command. your little safety net, use it.
  • -ddrt — says "hey, use DDRT as the transport protocol for this particular run of ipmctl."
  • -smbus — same energy, but it asks for SMBUS as the transport protocol for this run.
⚠️ note bestie: -ddrt and -smbus are mutually exclusive — you literally cannot use them together. pick one, it's not a both situation 💅
  • -o (text|nvmxml), -output (text|nvmxml) — swaps up the output format. one of: "text" (that's the default, no cap) or "nvmxml".

✨ TARGETS ✨

  • -dimm [DimmIDs] — injects or clears an error on specific PMem modules, by handing over one or more comma separated PMem module identifiers. if you don't specify anything, the default is to inject the error on all manageable PMem modules. all of them. every last one. 😭

✨ PROPERTIES ✨

heads up: this command only supports setting or clearing one type of error at a time. one at a time. don't be greedy. 🎀

Clear

  • "1" — clears a previously injected error. you must pair this with one of the other properties that says which previously injected error you're clearing. it can't read your mind, bestie.

Temperature

injects an artificial media temperature, in degrees Celsius, into the PMem module. the firmware that's out here monitoring the module's temperature will get alerted and take whatever precautions it deems necessary to preserve the PMem module. the value goes in immediately and overrides the firmware reading the actual media temperature — it'll use your value instead, which may cause adverse reactions from the firmware and result in an alert or a log entry. it's giving chaos. 🔥

⚠️ note: the injected temperature value sticks around until the next reboot, or until it's cleared. the media temperature here is artificial and won't harm the part itself. that said, firmware actions triggered by improper temperature injections may still cause adverse effects on the PMem module. if you pass in the Critical Shutdown Temperature or higher, this may make the PMem module firmware perform a shutdown in order to preserve the part and the data. so like. maybe don't. 💀 also: the temperature value gets ignored on clear.

Poison

the physical address to poison. yes, poison. that's the word they chose. 😭

poison is not possible for any address in the PM region if the PM region is locked. injected poison errors only trigger on a subsequent read of the poisoned address — when that happens, the firmware generates an error log, but no alerts are sent. silent treatment.

this command can also be used to clear non-injected poison errors. the data gets zeroed out after clearing. and ngl, there's no requirement to enable error injection before you request to clear poison errors.

you — the caller — are responsible for keeping a list of the injected poison errors, so you can properly clear them afterwards. simply disabling injection does not clear injected poison errors. and heads up: injected poison errors are persistent across power cycles and system resets. they're committed. 👑

⚠️ note: system firmware (BIOS) will not read from any Intel® Optane™ PMem device addresses that are known to be poisoned. for any poisoned address, the first read may result in a hang/fault — but system firmware (BIOS) will mark that address as poisoned, so subsequent attempts to read poisoned addresses get rejected with an error. the result of such an error may prevent booting from a namespace that has poisoned data. so yeah, that's a real one.
⚠️ note: the address must be 256 byte aligned (e.g., 0x10000000, 0x10000100, 0x10000200...).

PoisonType

the type of memory to poison. one of:

  • "PatrolScrub" — injects a poison error at the specified address, simulating an error found during a patrol scrub operation, indifferent to how the memory is currently allocated. this is the default.
  • "MemoryMode" — injects a poison error at the specified address currently allocated in Memory Mode.
  • "AppDirect" — injects a poison error at the specified address currently allocated as App Direct.
⚠️ note: if the address you want to poison isn't currently allocated as the specified memory type, you get an error back. vibe check failed.

PackageSparing

  • "1" — triggers an artificial package sparing. if package sparing is enabled and the PMem module still has spares remaining, this causes the firmware to report that there are no spares remaining.
⚠️ note: injecting package sparing is not supported on Intel® Optane™ Persistent Memory 300 series modules. sorry babes.

PercentageRemaining

injects an artificial percentage remaining value into the PMem module. this makes the firmware take appropriate action based on that value, and if necessary generate an error log, an alert, and update the health status. she's dramatic and the firmware is watching.

FatalMediaError

  • "1" — injects a fake media fatal error, which causes the firmware to generate an error log and an alert. 🔥
⚠️ note: when a media fatal error is injected, the BSR Media Disabled status bit gets set, indicating a media error — and it stays that way until the fatal error is cleared using the disable trigger input parameter to clear this injected fatal error.
⚠️ note: injecting a Fatal Media error is unsupported on Windows*. contact Microsoft* for assistance in performing this action. not us. them.
⚠️ note: when a fatal media error is cleared, a power cycle is needed for this operation to take effect. so actually reboot, bestie.

DirtyShutdown

  • "1" — injects an ADR failure, resulting in a dirty shutdown upon reboot. iconic, honestly.

✨ EXAMPLES ✨

sets the media temperature on all manageable PMem modules to 50 degrees Celsius.

ipmctl set -dimm Temperature=50

clears the injected media temperature on all manageable PMem modules.

ipmctl set -dimm Clear=1 Temperature=1

poison address 0x10000200 on PMem module 1234.

ipmctl set -dimm 1234 Poison=0x10000200

clears the injected poison of address 0x10000200 on PMem module 1234.

ipmctl set -dimm 1234 Poison=0x10000200 Clear=1

triggers an artificial package sparing on all manageable PMem modules.

ipmctl set -dimm PackageSparing=1

sets the life remaining percentage on all manageable PMem modules to 10%.

ipmctl set -dimm PercentageRemaining=10

clears the injected remaining life percentage on all manageable PMem modules. the value of PercentageRemaining is irrelevant here — it's just there for the vibe.

ipmctl set -dimm PercentageRemaining=10 Clear=1

triggers an artificial ADR failure on all manageable PMem modules, resulting in a dirty shutdown on each PMem module on the next reboot.

ipmctl set -dimm DirtyShutdown=1

✨ LIMITATIONS ✨

this command is only available when error injection is enabled on the PMem modules in the BIOS. and to actually execute it successfully, the specified PMem modules have to be manageable by the host software. no manageability, no party. 🙈

✨ RETURN DATA ✨

for each PMem module, the CLI tells you the status of the operation. and if something fails while injecting an error across multiple PMem modules, the process keeps going with the remaining PMem modules. she does not stop for anyone. 💅

✨ SAMPLE OUTPUT ✨

Set temperature on PMem module (DimmID): Success|Error (Code) - (Description)
Clear injected temperature on PMem module (DimmID): Success|Error (Code) - (Description)

Poison address (Address) on PMem module (DimmID): Success|Error (Code) - (Description)
Clear injected poison of address (Address) on PMem module (DimmID): Success|Error (Code) - (Description)

Trigger package sparing on PMem module (DimmID): Success|Error (Code) - (Description)
Clear injected package sparing on PMem module (DimmID): Success|Error (Code) - (Description)

Trigger a spare capacity alarm on PMem module (DimmID): Success|Error (Code) - (Description)
Clear injected spare capacity alarm on PMem module (DimmID): Success|Error (Code) - (Description)

Create a media fatal error on PMem module (DimmID): Success|Error (Code) - (Description)
Clear injected media fatal error on PMem module (DimmID): Success|Error (Code) - (Description)

that's the whole page, bestie, you read it, you understood it, you're basically certified. slay 💖✨

this came out of the ipmctl manual, dated 2024-04-22, and it's page IPMCTL-INJECT-ERROR(1) of the collection. go inject responsibly, mwah 🎀🦋

📦 where this page comes from