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       PercentageRemaining
126           Injects an artificial percentage remaining value into the PMem
127           module. This will cause the firmware to take appropriate action
128           based on the value and if necessary generate an error log, an
129           alert, and update the health status.
130
131       FatalMediaError
132
133           •   "1": Injects a fake media fatal error which will cause the
134               firmware to generate an error log and an alert.
135
136           Note
137           When media fatal error is injected, BSR Media Disabled status bit
138           will be set indicating media error, until the fatal error is
139           cleared using disable trigger input parameter to clear this
140           injected fatal error.
141
142           Note
143           Injecting a Fatal Media error is unsupported on Windows. Contact
144           Microsoft for assistance in performing this action.
145
146       DirtyShutdown
147
148           •   "1": Injects an ADR failure resulting in dirty shutdown upon
149               reboot.
150

EXAMPLES

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

LIMITATIONS

189       This command is available only when error injection is enabled on the
190       PMem modules in the BIOS. To successfully execute this command, the
191       specified PMem modules must be manageable by the host software.
192

RETURN DATA

194       For each PMem module, the CLI will indicate the status of the
195       operation. If a failure occurs when injecting an error on multiple PMem
196       modules, the process will continue with the remaining PMem modules.
197

SAMPLE OUTPUT

199           Set temperature on PMem module (DimmID): Success|Error (Code) -
200           (Description)
201           Clear injected temperature on PMem module (DimmID): Success|Error
202           (Code) - (Description)
203
204           Poison address (Address) on PMem module (DimmID): Success|Error
205           (Code) - (Description)
206           Clear injected poison of address (Address) on PMem module
207           (DimmID): Success|Error (Code) - (Description)
208
209           Trigger package sparing on PMem module (DimmID): Success|Error
210           (Code) - (Description)
211           Clear injected package sparing on PMem module (DimmID):
212           Success|Error (Code) - (Description)
213
214           Trigger a spare capacity alarm on PMem module (DimmID):
215           Success|Error (Code) - (Description)
216           Clear injected spare capacity alarm on PMem module (DimmID):
217           Success|Error (Code) - (Description)
218
219           Create a media fatal error on PMem module (DimmID): Success|Error
220           (Code) - (Description)
221           Clear injected media fatal error on PMem module (DimmID):
222           Success|Error (Code) - (Description)
223
224
225
226ipmctl                            2021-05-13            IPMCTL-INJECT-ERROR(1)
Impressum