power-recovery: uninterruptible power supplies
Add a section on handling a UPS and the requirements around it
Change-Id: I5ff93de04bb8b5b321686adaac318f9c03e7f8b5
Signed-off-by: Andrew Geissler <geissonator@yahoo.com>
diff --git a/designs/power-recovery.md b/designs/power-recovery.md
index 9a198a1..463286e 100644
--- a/designs/power-recovery.md
+++ b/designs/power-recovery.md
@@ -31,6 +31,12 @@
power-on feature to turn chassis power back on as soon as the brownout condition
ends.
+Some system owners may chose to attach an Uninterrupted Power Supply (UPS) to
+their system. A UPS continues to provide power to a system through a blackout
+or brownout scenario. A UPS has a limited amount of power so it's main
+purpose is to handle brief power interruptions or to allow for an orderly
+shutdown of the host firmware.
+
The goal of this design document is to describe how OpenBMC firmware will
deal with these questions.
@@ -108,6 +114,20 @@
- Tell the host firmware that it is a automated power-on recovery initiated
boot when that firmware is what boots the system
+### Uninterruptible Power Supply (UPS)
+When a UPS is present and a blackout or brownout condition occurs, the BMC must:
+- Log an error to indicate the condition has occurred
+- If host firmware is running, notify the host firmware of this utility failure
+ condition (this behavior is build-time configurable)
+- If the UPS battery power becomes low and if host firmware is running, notify
+ the host firmware of the condition, indicating a quick power off is required
+ (this behavior is build-time configurable)
+- Log an error if the UPS battery power becomes low and a power loss to the
+ entire system is imminent(i.e. a blackout scenario where BMC will also lose
+ power and UPS is about to run out of power)
+- Not execute any automated power-on recovery logic to prevent power on/off
+ thrasing (this behavior is build-time configurable)
+
## Proposed Design
### Automated Power-On Recovery
@@ -158,6 +178,7 @@
possible returned values for the power status of the target chassis:
- `Undefined`
- `BrownOut`
+- `UninterruptiblePowerSupply`
- `Good`
The phosphor-psu-monitor application within the phosphor-power repository will
@@ -189,6 +210,28 @@
associated with the chassis(s) with a bad power status will be the only ones
prevented from booting.
+### Uninterruptible Power Supply (UPS)
+A new phosphor-dbus-interface will be defined to represent a UPS. A BMC
+application will implement one of these per UPS attached to the system.
+This application will monitor UPS status and monitor for the following:
+- UPS utility fail (system power has failed and UPS is providing system power)
+- UPS battery low (UPS is about to run out of power)
+
+If the application sees power has been lost and the system is running on
+UPS battery power then it will monitor for the power remaining in the UPS and
+notify the host that a shutdown is required if needed. This application
+will also be responsible for logging an error indicating the UPS backup power
+has been switched to and set the appropriate property in their interface to
+indicate the scenario is present when the system can no longer remain on.
+phosphor-state-manager will query mapper for implementation of this new UPS
+interface and utilize them in combination with power supply brownout status
+when determining the value to return for its `CurrentPowerStatus`.
+
+Similar to the above brownout scenario, phosphor-state-manager will ensure
+automated power-on recovery logic is not run if `PowerStatus` is not set to
+`Good`. This behavior will be build-time configurable within
+phosphor-state-manager.
+
## Alternatives Considered
None, this is a pretty basic feature that does not have a lot of alternatives
(other then just not doing it).
@@ -224,6 +267,9 @@
- System automatically powers back on when brownout condition ends (assuming a
one-time or system auto power-on recovery policy of `AlwaysOn` or `Restore`)
+Plug a UPS into a system and ensure when power is cut to the system that an
+error is logged and the host is notified and allowed to power off.
+
[pdi-restore]:https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Control/Power/RestorePolicy.interface.yaml
[state-mgr]: https://github.com/openbmc/phosphor-state-manager
[bmc-state]:https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/State/BMC.interface.yaml