docs/designs/power-recovery.md

11 Modern computer systems have a feature, automated power-on recovery, which in
19 occur. For example, some systems have op-panels, and on these op-panels there
20 can be a pin hole reset. This is a manual mechanism for the user to force a hard
21 reset to the BMC in situations where it is hung or not responding. In these
30 A brownout is another scenario that commonly utilizes automated power-on
31 recovery features. A brownout is a scenario where BMC firmware detects (or is
33 be retained. On some systems, it's desired to utilize the automated power-on
40 host firmware.
42 The goal of this design document is to describe how OpenBMC firmware will deal
48 [PowerRestorePolicy][pdi-restore] property out in phosphor-dbus-interface
54 [openbmc/phosphor-state-manager][state-mgr] supports this property as defined in
55 the phosphor-dbus-interface.
59 ### Automated Power-On Recovery
66 - Do nothing when power is lost to the system (this will be the default)
67 - Always power the system on and boot the host
68 - Always power the system off (previous power was on, power is now off, run all
70 - Restore the previous state of the chassis power and host
78 hosted under a D-Bus object path which ends with "one_time". If this one_time
80 defined under it, and then reset the one_time property to `None`. This one_time
81 feature is a way for software to utilize automated power-on recovery function
82 for other areas like firmware update scenarios where a certain power on behavior
88 user has initiated some form of manual reset which is detectable by the BMC as
91 - Fill in appropriate `RebootCause` within the [BMC state interface][bmc-state]
92   - At a minimum, `PinholeReset` will be added. Others can be added as needed
93 - Log an error indicating a user initiated forced reset has occurred
94 - Not log an error indicating a blackout has occurred if chassis power was on
95   prior to the pin hole reset
96 - Not implement any power recovery policy on the system
97 - Turn power recovery back on once BMC has a normal reboot
103 this scenario after a BMC reboot, chassis-state-manager will check to see what
106 reset) or in severe cases occur when there is some sort of an external outage.
110 - Provide a generic target, `obmc-chassis-blackout@.target` to be called when a
112 - Adhere to the current power restore policy
114 BMC firmware must also be able to:
116 - Discover why the system is in a blackout situation. From either loss of power
126 - Power system off as quickly as situations requires (or gracefully handle the
128 - Log an error indicating the brownout event has occurred
129 - Support the ability for host firmware to indicate a one-time power restore
131 - Identify when a brownout condition has completed
132 - Wait for the brownout to complete and implement the one-time power restore
133   policy. If no one-time policy is defined then run the standard power restore
136 BMC firmware must also be able to:
138 - Discover if system is in a brownout situation
139   - Run when the BMC first comes up to know if it should implement any automated
140     power-on recovery
141 - Not run any power-on recovery logic when a brownout is occurring
142 - Tell the host firmware that it is a automated power-on recovery initiated boot
143   when that firmware is what boots the system
149 - Log an error to indicate the condition has occurred
150 - If host firmware is running, notify the host firmware of this utility failure
151   condition (this behavior is build-time configurable)
152 - If the UPS battery power becomes low and if host firmware is running, notify
153   the host firmware of the condition, indicating a quick power off is required
154   (this behavior is build-time configurable)
155 - Log an error if the UPS battery power becomes low and a power loss to the
158 - Not execute any automated power-on recovery logic to prevent power on/off
159   thrasing (this behavior is build-time configurable)
163 ### Automated Power-On Recovery
169 not `None`. If it does use the one_time setting then it will reset it to `None`
174 This function will be hosted in phosphor-state-manger and potentially
175 x86-power-control.
183 One possible cause of a BMC reset is an external reset (EXTRST). There are a
184 variety of reasons an external reset can occur. Some systems are adding GPIOs to
187 A new GPIO name will be added to the [device-tree-gpio-naming.md][dev-tree]
188 which reports whether a pin hole reset has occurred on the previous reboot of
197 which are not pin hole reset caused, will cause `RebootCause` to go back to a
198 default and therefore power recovery policy will be re-enabled on that BMC boot.
200 The phosphor-state-manager chassis software will not log a blackout error if it
202 initiated a reset of the system).
206 A new systemd target `obmc-chassis-blackout.target` should be added to allow
210 Phosphor-chassis-state-manager will ensure `obmc-chassis-blackout.target` will
217 phosphor-chassis-state-manager, which is instantiated per instance of chassis in
221 - `Undefined`
222 - `BrownOut`
223 - `UninterruptiblePowerSupply`
224 - `Good`
226 The phosphor-psu-monitor application within the phosphor-power repository will
228 per-chassis interface which represents the status of the power going into the
230 host it to report the status of the power. The state-manager software will
240 If the system design needs it, the existing one-time function provided by
241 phosphor-state-manager for auto power on policy will be utilized for when the
244 When the phosphor-power application detects that a brownout condition has
245 completed it will reset its interface representing power status to good and
246 start the state-manager service which executes the automated power-on logic.
248 phosphor-state-manager will ensure automated power-on recovery logic is only run
256 A new phosphor-dbus-interface will be defined to represent a UPS. A BMC
260 - UPS utility fail (system power has failed and UPS is providing system power)
261 - UPS battery low (UPS is about to run out of power)
269 phosphor-state-manager will query mapper for implementation of this new UPS
273 Similar to the above brownout scenario, phosphor-state-manager will ensure
274 automated power-on recovery logic is not run if `PowerStatus` is not set to
275 `Good`. This behavior will be build-time configurable within
276 phosphor-state-manager.
293 curl -k -H "Content-Type: application/json" -X PATCH -d '{"PowerRestorePolicy":"AlwaysOn"}' https:/…
294 curl -k -H "Content-Type: application/json" -X PATCH -d '{"PowerRestorePolicy":"AlwaysOff"}' https:…
295 curl -k -H "Content-Type: application/json" -X PATCH -d '{"PowerRestorePolicy":"LastState"}' https:…
301 Validate that when multiple black outs occur, the firmware continues to try and
304 On supported systems, a pin hole reset should be done with a system that has a
306 automatically power on after a pin hole reset. Verify it does automatically
312 - Error log generated
313 - Host notified (if running and notification possible)
314 - System quickly powered off
315 - Power recovery function is not run while a brownout is present
316 - System automatically powers back on when brownout condition ends (assuming a
317   one-time or system auto power-on recovery policy of `AlwaysOn` or `Restore`)
322 [pdi-restore]:
323 …https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Control/P…
324 [state-mgr]: https://github.com/openbmc/phosphor-state-manager
325 [bmc-state]:
326 …https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/State/BMC…
327 [dev-tree]:
328   https://github.com/openbmc/docs/blob/master/designs/device-tree-gpio-naming.md