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
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
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
81 feature is a way for software to utilize automated power-on recovery function
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
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
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
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
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
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
174 This function will be hosted in phosphor-state-manger and potentially
175 x86-power-control.
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
206 A new systemd target `obmc-chassis-blackout.target` should be added to allow
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
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
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:…
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