1## Overview 2 3The phosphor-power-sequencer application powers the chassis on/off and monitors 4the power sequencer device. 5 6If the chassis power good (pgood) status changes to false unexpectedly, the 7application uses information from the power sequencer device to determine the 8cause. Typically this is a voltage rail that shut down due to a fault. 9 10## Application 11 12The application is a single-threaded C++ executable. It is a 'daemon' process 13that runs continually. The application is launched by systemd when the BMC 14reaches the Ready state and before the chassis is powered on. 15 16The application is driven by an optional, system-specific JSON configuration 17file. The config file is found and parsed at runtime. The parsing process 18creates a collection of C++ objects. These objects represent the power sequencer 19device, voltage rails, GPIOs, and fault checks to perform. 20 21## Power sequencer device 22 23A power sequencer device enables (turns on) the voltage rails in the correct 24order and monitors them for pgood faults. 25 26This application currently supports the following power sequencer device types: 27 28- UCD90160 29- UCD90320 30 31Additional device types can be supported by creating a new sub-class within the 32PowerSequencerDevice class hierarchy. 33 34## Powering on the chassis 35 36- A BMC application or script sets the `state` property to 1 on the 37 `org.openbmc.control.Power` D-Bus interface. 38- The phosphor-power-sequencer application writes the value 1 to the named GPIO 39 `power-chassis-control`. 40 - This GPIO is defined in the device tree. The GPIO name is defined in the 41 [Device Tree GPIO Naming in OpenBMC document](https://github.com/openbmc/docs/blob/master/designs/device-tree-gpio-naming.md) 42- The power sequencer device powers on all the voltage rails in the correct 43 order. 44- When all rails have been successfully powered on, the power sequencer device 45 sets the named `power-chassis-good` GPIO to the value 1. 46 - This GPIO is defined in the device tree. The GPIO name is defined in the 47 [Device Tree GPIO Naming in OpenBMC document](https://github.com/openbmc/docs/blob/master/designs/device-tree-gpio-naming.md) 48- The phosphor-power-sequencer application sets the `pgood` property to 1 on the 49 `org.openbmc.control.Power` D-Bus interface. 50- The rest of the boot continues 51 52## Powering off the chassis 53 54- A BMC application or script sets the `state` property to 0 on the 55 `org.openbmc.control.Power` D-Bus interface. 56- The phosphor-power-sequencer application writes the value 0 to the named GPIO 57 `power-chassis-control`. 58- The power sequencer device powers off all the voltage rails in the correct 59 order. 60- When all rails have been successfully powered off, the power sequencer device 61 sets the named `power-chassis-good` GPIO to the value 0. 62- The phosphor-power-sequencer application sets the `pgood` property to 0 on the 63 `org.openbmc.control.Power` D-Bus interface. 64 65## Pgood fault 66 67A power good (pgood) fault occurs in two scenarios: 68 69- When attempting to power on the chassis: 70 - The power sequencer device is powering on all voltage rails in order, and 71 one of the rails does not turn on. 72- After the chassis was successfully powered on: 73 - A voltage rail suddenly turns off or stops providing the expected level of 74 voltage. This could occur if the voltage regulator stops working or if it 75 shuts itself off due to exceeding a temperature/voltage/current limit. 76 77If the pgood fault occurs when attempting to power on the chassis, the chassis 78pgood signal never changes to true. 79 80If the pgood fault occurs after the chassis was successfully powered on, the 81chassis pgood signal changes from true to false. This application monitors the 82chassis power good status by reading the named GPIO `power-chassis-good`. 83 84## Identifying the cause of a pgood fault 85 86It is very helpful to identify which voltage rail caused the pgood fault. That 87determines what hardware potentially needs to be replaced. 88 89Determining the correct rail requires the following: 90 91- The power sequencer device type is supported by this application 92- A JSON config file is defined for the current system 93 94If those requirements are met, the application will attempt to determine which 95voltage rail caused the chassis pgood fault. If found, an error is logged 96against that specific rail. 97 98If those requirements are not met, a general pgood fault error is logged. 99 100## JSON configuration file 101 102This application is configured by an optional JSON configuration file. The 103configuration file defines the voltage rails in the system and how they should 104be monitored. 105 106JSON configuration files are system-specific and are stored in the 107[config_files](../config_files/) sub-directory. 108 109[Documentation](config_file/README.md) is available on the configuration file 110format. 111 112If no configuration file is found for the current system, this application can 113still power the chassis on/off and detect chassis pgood faults. However, it will 114not be able to determine which voltage rail caused a pgood fault. 115 116## Key Classes 117 118- PowerInterface 119 - Defines the `org.openbmc.control.Power` D-Bus interface. 120 - The `state` property is set to power the chassis on or off. This contains 121 the desired power state. 122 - The `pgood` property contains the actual power state of the chassis. 123- PowerControl 124 - Created in `main()`. Handles the event loop. 125 - Sub-class of PowerInterface that provides a concrete implementation of the 126 `org.openbmc.control.Power` D-Bus interface. 127 - Finds and loads the JSON configuration file. 128 - Finds power sequencer device information. 129 - Creates a sub-class of PowerSequencerDevice that matches power sequencer 130 device information. 131 - Powers the chassis on and off using the `power-chassis-control` named GPIO. 132 - Monitors the chassis pgood status every 3 seconds using the 133 `power-chassis-good` named GPIO. 134 - Enforces a minimum power off time of 15 seconds from cold start and 25 135 seconds from power off. 136- DeviceFinder 137 - Finds power sequencer device information on D-Bus published by 138 EntityManager. 139- Rail 140 - A voltage rail that is enabled or monitored by the power sequencer device. 141- PowerSequencerDevice 142 - Abstract base class for a power sequencer device. 143 - Defines virtual methods that must be implemented by all child classes. 144- StandardDevice 145 - Sub-class of PowerSequencerDevice that implements the standard pgood fault 146 detection algorithm. 147- PMBusDriverDevice 148 - Sub-class of StandardDevice for power sequencer devices that are bound to a 149 PMBus device driver. 150- UCD90xDevice 151 - Sub-class of PMBusDriverDevice for the UCD90X family of power sequencer 152 devices. 153- UCD90160Device 154 - Sub-class of UCD90xDevice representing a UCD90160 power sequencer device. 155- UCD90320Device 156 - Sub-class of UCD90xDevice representing a UCD90320 power sequencer device. 157- Services 158 - Abstract base class that provides an interface to system services like error 159 logging and the journal. 160- BMCServices 161 - Sub-class of Services with real implementation of methods. 162- MockServices 163 - Sub-class of Services with mock implementation of methods for automated 164 testing. 165 166## Testing 167 168Automated test cases exist for most of the code in this application. See 169[testing.md](testing.md) for more information. 170