docs/designs/power-recovery.md

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
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.
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
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
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
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
104 the last power state was before the loss of power and compares it against the
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.
127   loss of power if it occurred without warning)
129 - Support the ability for host firmware to indicate a one-time power restore
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
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
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
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
166 determined which will only run if the chassis power is not on.
175 x86-power-control.
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.
219 possible returned values for the power status of the target chassis:
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.
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
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
270 interface and utilize them in combination with power supply brownout status when
274 automated power-on recovery logic is not run if `PowerStatus` is not set to
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.
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.