README.md
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