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