1IPMCTL-INJECT-ERROR(1)              ipmctl              IPMCTL-INJECT-ERROR(1)
2
3
4

NAME

6       ipmctl-inject-error - Injects an error or clears a previously injected
7       error
8

SYNOPSIS

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

DESCRIPTION

13       Injects an error or clears a previously injected error on one or more
14       PMem module for testing purposes.
15

OPTIONS

17       -h, -help
18           Displays help for the command.
19
20       -ddrt
21           Used to specify DDRT as the desired transport protocol for the
22           current invocation of ipmctl.
23
24       -smbus
25           Used to specify SMBUS as the desired transport protocol for the
26           current invocation of ipmctl.
27
28           Note
29           The -ddrt and -smbus options are mutually exclusive and may not be
30           used together.
31
32       -o (text|nvmxml), -output (text|nvmxml)
33           Changes the output format. One of: "text" (default) or "nvmxml".
34

TARGETS

36       -dimm [DimmIDs]
37           Injects or clears an error on specific PMem modules by supplying
38           one or more comma separated PMem module identifiers. The default is
39           to inject the error on all manageable PMem modules.
40

PROPERTIES

42       This command only supports setting or clearing one type of error at a
43       time.
44
45       Clear
46
47           •   "1": Clears a previously injected error. This property must be
48               combined with one of the other properties indicating the
49               previously injected error to clear.
50
51       Temperature
52           Injects an artificial media temperature in degrees Celsius into the
53           PMem module. The firmware that is monitoring the temperature of the
54           PMem module will then be alerted and take necessary precautions to
55           preserve the PMem module. The value is injected immediately and
56           will override the firmware from reading the actual media
57           temperature of the device and use this value instead which may
58           cause adverse reactions by the firmware and result in an alert or
59           log.
60
61           Note
62           The injected temperature value will remain until the next reboot or
63           until it is cleared. The media temperature is an artificial
64           temperature and will not cause harm to the part. Although firmware
65           actions due to improper temperature injections may cause adverse
66           effects on the PMem module.
67           If the Critical Shutdown Temperature, or higher, is passed in, this
68           may cause the PMem module firmware to perform a shutdown in order
69           to preserve the part and data.
70           The temperature value will be ignored on clear.
71
72       Poison
73           The physical address to poison.
74           Poison is not possible for any address in the PM region if the PM
75           region is locked. Injected poison errors are only triggered on a
76           subsequent read of the poisoned address in which case an error log
77           will be generated by the firmware, but no alerts will be sent.
78           This command can be used to clear non-injected poison errors. The
79           data will be zeroed after clearing. There is no requirement to
80           enable error injection prior to request to clear poison errors.
81           The caller is responsible for keeping a list of injected poison
82           errors, in order to properly clear the injected errors afterwards.
83           Simply disabling injection does not clear injected poison errors.
84           Injected poison errors are persistent across power cycles and
85           system resets.
86
87           Note
88           System firmware (BIOS) will not read from any Intel® Optane™ PMem
89           device addresses that are known to be poisoned. For any poisoned
90           address, the first read may result in a hang/fault, but system
91           firmware (BIOS) will mark this address as poisoned so subsequent
92           attempts to read poisoned addresses will be rejected with an error.
93           The result of such an error may prevent booting from a namespace
94           that has poisoned data.
95
96           Note
97           The address must be 256 byte aligned (e.g., 0x10000000, 0x10000100,
98           0x10000200...).
99
100       PoisonType
101           The type of memory to poison. One of:
102
103           •   "PatrolScrub": Injects a poison error at the specified address
104               simulating an error found during a patrol scrub operation
105               indifferent to how the memory is currently allocated. This is
106               the default.
107
108           •   "MemoryMode": Injects a poison error at the specified address
109               currently allocated in Memory Mode.
110
111           •   "AppDirect": Injects a poison error at the specified address
112               currently allocated as App Direct.
113
114           Note
115           If the address to poison is not currently allocated as the
116           specified memory type, an error is returned.
117
118       PackageSparing
119
120           •   "1": Triggers an artificial package sparing. If package sparing
121               is enabled and the PMem module still has spares remaining, this
122               will cause the firmware to report that there are no spares
123               remaining.
124
125           Note
126           Injecting package sparing is not supported on Intel® Optane™
127           Persistent Memory 300 series modules.
128
129       PercentageRemaining
130           Injects an artificial percentage remaining value into the PMem
131           module. This will cause the firmware to take appropriate action
132           based on the value and if necessary generate an error log, an
133           alert, and update the health status.
134
135       FatalMediaError
136
137           •   "1": Injects a fake media fatal error which will cause the
138               firmware to generate an error log and an alert.
139
140           Note
141           When media fatal error is injected, BSR Media Disabled status bit
142           will be set indicating media error, until the fatal error is
143           cleared using disable trigger input parameter to clear this
144           injected fatal error.
145
146           Note
147           Injecting a Fatal Media error is unsupported on Windows*. Contact
148           Microsoft* for assistance in performing this action.
149
150           Note
151           When a fatal media error is cleared, A power cycle is needed for
152           this operation to take effect.
153
154       DirtyShutdown
155
156           •   "1": Injects an ADR failure resulting in dirty shutdown upon
157               reboot.
158

EXAMPLES

160       Sets the media temperature on all manageable PMem modules to 50 degrees
161       Celsius.
162
163           ipmctl set -dimm Temperature=50
164
165       Clears the injected media temperature on all manageable PMem modules.
166
167           ipmctl set -dimm Clear=1 Temperature=1
168
169       Poison address 0x10000200 on PMem module 1234.
170
171           ipmctl set -dimm 1234 Poison=0x10000200
172
173       Clears the injected poison of address 0x10000200 on PMem module 1234.
174
175           ipmctl set -dimm 1234 Poison=0x10000200 Clear=1
176
177       Triggers an artificial package sparing on all manageable PMem modules.
178
179           ipmctl set -dimm PackageSparing=1
180
181       Sets the life remaining percentage on all manageable PMem modules to
182       10%.
183
184           ipmctl set -dimm PercentageRemaining=10
185
186       Clears the injected remaining life percentage on all manageable PMem
187       modules. The value of PercentageRemaining is irrelevant.
188
189           ipmctl set -dimm PercentageRemaining=10 Clear=1
190
191       Triggers an artificial ADR failure on all manageable PMem modules
192       resulting in a dirty shutdown on each PMem module on the next reboot.
193
194           ipmctl set -dimm DirtyShutdown=1
195

LIMITATIONS

197       This command is available only when error injection is enabled on the
198       PMem modules in the BIOS. To successfully execute this command, the
199       specified PMem modules must be manageable by the host software.
200

RETURN DATA

202       For each PMem module, the CLI will indicate the status of the
203       operation. If a failure occurs when injecting an error on multiple PMem
204       modules, the process will continue with the remaining PMem modules.
205

SAMPLE OUTPUT

207           Set temperature on PMem module (DimmID): Success|Error (Code) -
208           (Description)
209           Clear injected temperature on PMem module (DimmID): Success|Error
210           (Code) - (Description)
211
212           Poison address (Address) on PMem module (DimmID): Success|Error
213           (Code) - (Description)
214           Clear injected poison of address (Address) on PMem module
215           (DimmID): Success|Error (Code) - (Description)
216
217           Trigger package sparing on PMem module (DimmID): Success|Error
218           (Code) - (Description)
219           Clear injected package sparing on PMem module (DimmID):
220           Success|Error (Code) - (Description)
221
222           Trigger a spare capacity alarm on PMem module (DimmID):
223           Success|Error (Code) - (Description)
224           Clear injected spare capacity alarm on PMem module (DimmID):
225           Success|Error (Code) - (Description)
226
227           Create a media fatal error on PMem module (DimmID): Success|Error
228           (Code) - (Description)
229           Clear injected media fatal error on PMem module (DimmID):
230           Success|Error (Code) - (Description)
231
232
233
234ipmctl                            2023-07-20            IPMCTL-INJECT-ERROR(1)
Impressum