docs/designs/power-recovery.md

11 Modern computer systems have a feature, automated power-on recovery, which in
12 essence is the ability to tell your system what to do when it hits issues with
13 power to the system. If the system had a black out (i.e. power was completely
14 cut to the system), should it automatically power the system on? Should it leave
15 it off? Or maybe the user would like the system to go to whichever state it was
19 occur. For example, some systems have op-panels, and on these op-panels there
22 situations, the user may wish for the system to not automatically power on the
23 system, because they want to debug the reason for the BMC error.
25 During blackout scenarios, system owners may have a set of services they need
27 to off in a blackout. OpenBMC needs to provide a mechanism for system owners to
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
36 Some system owners may chose to attach an Uninterrupted Power Supply (UPS) to
37 their system. A UPS continues to provide power to a system through a blackout or
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
73 detect that chassis power is already on to the system when it comes out of
78 hosted under a D-Bus object path which ends with "one_time". If 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
85 ### BMC and System Recovery Paths
87 In situations where the BMC or the system have gotten into a bad state, and the
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
96 - Not implement any power recovery policy on the system
97 - Turn power recovery back on once BMC has a normal reboot
101 A blackout occurs when AC power is cut from the system, resulting in a total
102 loss of power if there is no UPS installed to keep the system on. To identify
103 this scenario after a BMC reboot, chassis-state-manager will check to see what
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
134   policy defined for the system
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
156   entire system is imminent(i.e. a blackout scenario where BMC will also lose
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
174 This function will be hosted in phosphor-state-manger and potentially
175 x86-power-control.
177 ### BMC and System Recovery Paths
187 A new GPIO name will be added to the [device-tree-gpio-naming.md][dev-tree]
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
207 system maintainers to call services in this condition. This new target will be
208 called when the BMC detects a blackout. The target will allow for system owners
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
218 the system, will support a read of this property. The following will be the
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
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
250 multiple chassis and/or host instances in the system then the host instances
256 A new phosphor-dbus-interface will be defined to represent a UPS. A BMC
257 application will implement one of these per UPS attached to the system. This
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)
263 If the application sees power has been lost and the system is running on UPS
268 scenario is present when the system can no longer remain on.
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
302 power on the system when policy is `AlwaysOn` or `Restore`.
304 On supported systems, a pin hole reset should be done with a system that has a
305 policy set to always power on. Tester should verify system does not
309 A brownout condition should be injected into a system and appropriate paths
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`)
319 Plug a UPS into a system and ensure when power is cut to the system that an
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