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
20 can be a pin hole reset. This is a manual mechanism for the user to force a hard
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
31 recovery features. A brownout is a scenario where BMC firmware detects (or is
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
47 The BMC already implements a limited subset of function in this area. The
69   chassis power off services to ensure a clean state of software and hardware)
76 OpenBMC software must also support the concept of a one_time power restore
77 policy. This is a separate instance of the `PowerRestorePolicy` which will be
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
87 In situations where the BMC or the system have gotten into a bad state, and the
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
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
103 this scenario after a BMC reboot, chassis-state-manager will check to see what
105 pgood pin. Blackouts can be intentionally triggered by a user (i.e a pinhole
110 - Provide a generic target, `obmc-chassis-blackout@.target` to be called when a
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
129 - Support the ability for host firmware to indicate a one-time power restore
131 - Identify when a brownout condition has completed
138 - Discover if system is in a brownout situation
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
147 When a UPS is present and a blackout or brownout condition occurs, the BMC must:
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
156   entire system is imminent(i.e. a blackout scenario where BMC will also lose
179 The BMC state manager application currently looks at a file in the sysfs to try
180 and determine the cause of a BMC reboot. It then puts this reason in the
183 One possible cause of a BMC reset is an external reset (EXTRST). There are a
188 which reports whether a pin hole reset has occurred on the previous reboot of
192 reboot via the sysfs or sysfs reports a EXTRST reason (in which case the GPIO
197 which are not pin hole reset caused, will cause `RebootCause` to go back to a
200 The phosphor-state-manager chassis software will not log a blackout error if it
201 sees the `PinholeReset` reason (or any other reason that indicates a user
202 initiated a reset of the system).
208 called when the BMC detects a blackout. The target will allow for system owners
211 be called after a blackout.
216 support a `CurrentPowerStatus` property. The existing
218 the system, will support a read of this property. The following will be the
227 be responsible for monitoring for brownout conditions. It will support a
232 and aggregate the status (i.e. if any reports a brownout, then `BrownOut` will
233 be returned). This interface will be defined in a later update to this document.
237 applications will log an error when a brownout occurs and initiate the fast
244 When the phosphor-power application detects that a brownout condition has
251 associated with the chassis(s) with a bad power status will be the only ones
256 A new phosphor-dbus-interface will be defined to represent a UPS. A BMC
265 the host that a shutdown is required if needed. This application will also be
280 None, this is a pretty basic feature that does not have a lot of alternatives
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
307 power on when a normal reboot of the BMC is done.
309 A brownout condition should be injected into a system and appropriate paths
315 - Power recovery function is not run while a brownout is present
316 - System automatically powers back on when brownout condition ends (assuming a
319 Plug a UPS into a system and ensure when power is cut to the system that an