docs/designs/power-recovery.md

1 # OpenBMC Server Power Recovery
11 Modern computer systems have a feature, automated power-on recovery, which in
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
16 at before the power loss.
18 There are also instances where the user may not want automatic power recovery to
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
26 run once the power is restored. For example, IBM requires all LED's be toggled
30 A brownout is another scenario that commonly utilizes automated power-on
32 told) that chassis power can no longer be supported, but power to the BMC will
33 be retained. On some systems, it's desired to utilize the automated power-on
34 feature to turn chassis power back on as soon as the brownout condition ends.
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
38 brownout scenario. A UPS has a limited amount of power so it's main purpose is
39 to handle brief power interruptions or to allow for an orderly shutdown of the
48 [PowerRestorePolicy][pdi-restore] property out in phosphor-dbus-interface
52 Configuration and Power Interface (ACPI).
54 [openbmc/phosphor-state-manager][state-mgr] supports this property as defined in
55 the phosphor-dbus-interface.
59 ### Automated Power-On Recovery
61 OpenBMC software must ensure it persists the state of power to the chassis so it
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
69   chassis power off services to ensure a clean state of software and hardware)
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
76 OpenBMC software must also support the concept of a one_time power restore
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
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
104 the last power state was before the loss of power and compares it against the
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
121 As noted above, a brownout condition is when AC power can not continue to be
122 supplied to the chassis, but the BMC can continue to have power and run.
126 - Power system off as quickly as situations requires (or gracefully handle the
127   loss of power if it occurred without warning)
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
145 ### Uninterruptible Power Supply (UPS)
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
157   power and UPS is about to run out of power)
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
166 determined which will only run if the chassis power is not on.
174 This function will be hosted in phosphor-state-manger and potentially
175 x86-power-control.
179 The BMC state manager application currently looks at a file in the sysfs to try
187 A new GPIO name will be added to the [device-tree-gpio-naming.md][dev-tree]
189 the BMC. The BMC state manager application will enhance its support of the
195 If the power recovery software sees the `PinholeReset` reason within the
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
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
219 possible returned values for the power status of the target chassis:
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
235 The application(s) responsible for detecting and reporting chassis power will
238 power off.
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
249 when the power supply interface reports the power status is good. If there are
251 associated with the chassis(s) with a bad power status will be the only ones
254 ### Uninterruptible Power Supply (UPS)
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)
263 If the application sees power has been lost and the system is running on UPS
264 battery power then it will monitor for the power remaining in the UPS and notify
266 responsible for logging an error indicating the UPS backup power has been
269 phosphor-state-manager will query mapper for implementation of this new UPS
270 interface and utilize them in combination with power supply brownout status when
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.
292 #  Power Restore Policy
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:…
302 power on the system when policy is `AlwaysOn` or `Restore`.
305 policy set to always power on. Tester should verify system does not
306 automatically power on after a pin hole reset. Verify it does automatically
307 power on when a normal reboot of the BMC is done.
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
320 error is logged and the host is notified and allowed to power off.
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