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