pseq: Update documentation for multi-chassis
Update the phosphor-power-sequencer documentation to define the support
required for multiple chassis systems.
The support described is currently only in the design stage. After this
review is complete, future commits will implement the multiple chassis
support.
The goal is for the phosphor-power-sequencer support to be largely
unchanged for single chassis systems.
This documentation also refers to planned enhancements to two other
applications:
* phosphor-chassis-state-manager (enhance multi-chassis support)
* phosphor-chassis-power (new application)
Change-Id: I10ed0ba3c73008ba297c8c7b47293eefc998a2ea
Signed-off-by: Shawn McCarney <shawnmm@us.ibm.com>
diff --git a/phosphor-power-sequencer/docs/README.md b/phosphor-power-sequencer/docs/README.md
index 82f662d..adad552 100644
--- a/phosphor-power-sequencer/docs/README.md
+++ b/phosphor-power-sequencer/docs/README.md
@@ -2,108 +2,83 @@
## Overview
-The phosphor-power-sequencer application powers the chassis on/off and monitors
-the power sequencer device.
+The `phosphor-power-sequencer` application powers all the chassis in the system
+on and off. It also monitors the power good (pgood) state in each chassis.
-If the chassis power good (pgood) status changes to false unexpectedly, the
-application uses information from the power sequencer device to determine the
-cause. Typically this is a voltage rail that shut down due to a fault.
+**Note:** Many changes have been made to this documentation to define how
+multiple chassis support will work. This support is not yet implemented in this
+application. The support is also dependent on changes to the existing
+`phosphor-chassis-state-manager` application and the planned new
+`phosphor-chassis-power` application. This disclaimer will be removed when this
+support is fully implemented.
## Application
-The application is a single-threaded C++ executable. It is a 'daemon' process
-that runs continually. The application is launched by systemd when the BMC
-reaches the Ready state and before the chassis is powered on.
+`phosphor-power-sequencer` is a single-threaded C++ executable. It is a daemon
+process that runs continually. It is launched by systemd when the BMC reaches
+the Ready state and before the system is powered on.
-The application is driven by an optional, system-specific JSON configuration
-file. The config file is found and parsed at runtime. The parsing process
-creates a collection of C++ objects. These objects represent the power sequencer
-device, voltage rails, GPIOs, and fault checks to perform.
+`phosphor-power-sequencer` is driven by an optional, system-specific JSON
+configuration file. The config file is found and parsed at runtime. The parsing
+process creates a collection of C++ objects. These objects represent the
+chassis, power sequencer devices, voltage rails, GPIOs, and fault checks to
+perform.
+
+See [Internal Design](internal_design.md) for more information.
## Power sequencer device
A power sequencer device enables (turns on) the voltage rails in the correct
order and monitors them for pgood faults.
-This application currently supports the following power sequencer device types:
+`phosphor-power-sequencer` currently supports the following power sequencer
+device types:
- UCD90160
- UCD90320
Additional device types can be supported by creating a new sub-class within the
-PowerSequencerDevice class hierarchy.
+PowerSequencerDevice class hierarchy. See [Internal Design](internal_design.md)
+for more information.
-## Powering on the chassis
+If the power sequencer device type is not supported, `phosphor-power-sequencer`
+can still power the system on/off and detect chassis pgood faults. However, it
+will not be able to determine which voltage rail caused a pgood fault.
-- A BMC application or script sets the `state` property to 1 on the
- `org.openbmc.control.Power` D-Bus interface.
-- The phosphor-power-sequencer application writes the value 1 to the named GPIO
- `power-chassis-control`.
- - This GPIO is defined in the device tree. The GPIO name is defined in the
- [Device Tree GPIO Naming in OpenBMC document](https://github.com/openbmc/docs/blob/master/designs/device-tree-gpio-naming.md)
-- The power sequencer device powers on all the voltage rails in the correct
- order.
-- When all rails have been successfully powered on, the power sequencer device
- sets the named `power-chassis-good` GPIO to the value 1.
- - This GPIO is defined in the device tree. The GPIO name is defined in the
- [Device Tree GPIO Naming in OpenBMC document](https://github.com/openbmc/docs/blob/master/designs/device-tree-gpio-naming.md)
-- The phosphor-power-sequencer application sets the `pgood` property to 1 on the
- `org.openbmc.control.Power` D-Bus interface.
-- The rest of the boot continues
+## Powering on the system
-## Powering off the chassis
+`phosphor-power-sequencer` uses the power sequencer device to power on all main
+(non-standby) voltage rails in each chassis.
-- A BMC application or script sets the `state` property to 0 on the
- `org.openbmc.control.Power` D-Bus interface.
-- The phosphor-power-sequencer application writes the value 0 to the named GPIO
- `power-chassis-control`.
-- The power sequencer device powers off all the voltage rails in the correct
- order.
-- When all rails have been successfully powered off, the power sequencer device
- sets the named `power-chassis-good` GPIO to the value 0.
-- The phosphor-power-sequencer application sets the `pgood` property to 0 on the
- `org.openbmc.control.Power` D-Bus interface.
+See [Powering On](powering_on.md) for more information.
-## Pgood fault
+## Powering off the system
-A power good (pgood) fault occurs in two scenarios:
+`phosphor-power-sequencer` uses the power sequencer device to power off all main
+(non-standby) voltage rails in each chassis.
-- When attempting to power on the chassis:
- - The power sequencer device is powering on all voltage rails in order, and
- one of the rails does not turn on.
-- After the chassis was successfully powered on:
- - A voltage rail suddenly turns off or stops providing the expected level of
- voltage. This could occur if the voltage regulator stops working or if it
- shuts itself off due to exceeding a temperature/voltage/current limit.
+See [Powering Off](powering_off.md) for more information.
-If the pgood fault occurs when attempting to power on the chassis, the chassis
-pgood signal never changes to true.
+## Monitoring chassis pgood
-If the pgood fault occurs after the chassis was successfully powered on, the
-chassis pgood signal changes from true to false. This application monitors the
-chassis power good status by reading the named GPIO `power-chassis-good`.
+`phosphor-power-sequencer` periodically reads the chassis pgood state from the
+power sequencer device. See
+[Monitoring Chassis Power Good](monitoring_chassis_pgood.md) for more
+information.
-## Identifying the cause of a pgood fault
+## Chassis pgood faults
-It is very helpful to identify which voltage rail caused the pgood fault. That
-determines what hardware potentially needs to be replaced.
+If the chassis pgood state is false when it should be true, a chassis pgood
+fault has occurred. `phosphor-power-sequencer` uses information from the power
+sequencer device to determine the cause.
-Determining the correct rail requires the following:
-
-- The power sequencer device type is supported by this application
-- A JSON config file is defined for the current system
-
-If those requirements are met, the application will attempt to determine which
-voltage rail caused the chassis pgood fault. If found, an error is logged
-against that specific rail.
-
-If those requirements are not met, a general pgood fault error is logged.
+See [Power Good Faults](pgood_faults.md) for more information.
## JSON configuration file
-This application is configured by an optional JSON configuration file. The
-configuration file defines the voltage rails in the system and how they should
-be monitored.
+`phosphor-power-sequencer` is configured by an optional JSON configuration file.
+The configuration file defines the voltage rails in the system and how they
+should be monitored.
JSON configuration files are system-specific and are stored in the
[config_files](../config_files/) sub-directory.
@@ -111,61 +86,34 @@
[Documentation](config_file/README.md) is available on the configuration file
format.
-If no configuration file is found for the current system, this application can
-still power the chassis on/off and detect chassis pgood faults. However, it will
-not be able to determine which voltage rail caused a pgood fault.
-
-## Key Classes
-
-- PowerInterface
- - Defines the `org.openbmc.control.Power` D-Bus interface.
- - The `state` property is set to power the chassis on or off. This contains
- the desired power state.
- - The `pgood` property contains the actual power state of the chassis.
-- PowerControl
- - Created in `main()`. Handles the event loop.
- - Sub-class of PowerInterface that provides a concrete implementation of the
- `org.openbmc.control.Power` D-Bus interface.
- - Finds and loads the JSON configuration file.
- - Finds power sequencer device information.
- - Creates a sub-class of PowerSequencerDevice that matches power sequencer
- device information.
- - Powers the chassis on and off using the `power-chassis-control` named GPIO.
- - Monitors the chassis pgood status every 3 seconds using the
- `power-chassis-good` named GPIO.
- - Enforces a minimum power off time of 15 seconds from cold start and 25
- seconds from power off.
-- DeviceFinder
- - Finds power sequencer device information on D-Bus published by
- EntityManager.
-- Rail
- - A voltage rail that is enabled or monitored by the power sequencer device.
-- PowerSequencerDevice
- - Abstract base class for a power sequencer device.
- - Defines virtual methods that must be implemented by all child classes.
-- StandardDevice
- - Sub-class of PowerSequencerDevice that implements the standard pgood fault
- detection algorithm.
-- PMBusDriverDevice
- - Sub-class of StandardDevice for power sequencer devices that are bound to a
- PMBus device driver.
-- UCD90xDevice
- - Sub-class of PMBusDriverDevice for the UCD90X family of power sequencer
- devices.
-- UCD90160Device
- - Sub-class of UCD90xDevice representing a UCD90160 power sequencer device.
-- UCD90320Device
- - Sub-class of UCD90xDevice representing a UCD90320 power sequencer device.
-- Services
- - Abstract base class that provides an interface to system services like error
- logging and the journal.
-- BMCServices
- - Sub-class of Services with real implementation of methods.
-- MockServices
- - Sub-class of Services with mock implementation of methods for automated
- testing.
+If no configuration file is found for the current system,
+`phosphor-power-sequencer` can still power the system on/off and detect chassis
+pgood faults. However, it will not be able to determine which voltage rail
+caused a pgood fault.
## Testing
Automated test cases exist for most of the code in this application. See
-[testing.md](testing.md) for more information.
+[Testing](testing.md) for more information.
+
+## Related applications
+
+### phosphor-chassis-state-manager
+
+The `phosphor-chassis-state-manager` application exists in the
+phosphor-state-manager repository. It supports user requests to power on and off
+the system hardware. It publishes the [`xyz.openbmc_project.State.Chassis`][1]
+D-Bus interface.
+
+### phosphor-chassis-power
+
+The `phosphor-chassis-power` application exists in the phosphor-power
+repository. It monitors the chassis input power state using GPIOs.
+
+### phosphor-power-supply
+
+The `phosphor-power-supply` application exists in the phosphor-power repository.
+It monitors the power supply devices within each chassis.
+
+[1]:
+ https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/State/Chassis.interface.yaml
diff --git a/phosphor-power-sequencer/docs/chassis_status.md b/phosphor-power-sequencer/docs/chassis_status.md
new file mode 100644
index 0000000..f04d0bf
--- /dev/null
+++ b/phosphor-power-sequencer/docs/chassis_status.md
@@ -0,0 +1,236 @@
+# Chassis Status
+
+## Overview
+
+There are multiple D-Bus interfaces and properties that describe the chassis
+status. The `phosphor-power-sequencer` application publishes one of those
+interfaces. The other interfaces are published by different applications and are
+used as input by `phosphor-power-sequencer.`
+
+## state and pgood properties
+
+The `state` and `pgood` properties exist on the `org.openbmc.control.Power`
+D-Bus interface.
+
+`state` has a value of 0 or 1. `state` represents the desired power state for
+the chassis. 0 means off, and 1 means on. This property is set when the system
+is being powered [on](powering_on.md) or [off](powering_off.md).
+
+`pgood` has a value of 0 or 1. `pgood` represents the power good (pgood) state
+of the chassis. 0 means off, and 1 means on. This is the actual, current power
+state. This property is set based on the chassis power good signal from the
+power sequencer device.
+
+`phosphor-power-sequencer` publishes the `org.openbmc.control.Power` interface
+on the following object paths:
+
+- `/org/openbmc/control/power0`: Represents the entire system
+- `/org/openbmc/control/power1`: Represents chassis 1
+- `/org/openbmc/control/power2`: Represents chassis 2
+- ...
+- `/org/openbmc/control/powerN`: Represents chassis N
+
+### Single chassis system
+
+On a single chassis system, only the first two object paths are published,
+representing the entire system and chassis 1. The values of the `state` and
+`pgood` properties are identical for both object paths.
+
+When the system is powered off, the `state` and `pgood` properties for both
+object paths are 0.
+
+When the system is being powered on, the `state` property of both object paths
+is set to 1. When the chassis has successfully powered on, the `pgood` property
+of both object paths is set to 1.
+
+When the system is being powered off, the `state` property of both object paths
+is set to 0. When the chassis has successfully powered off, the `pgood` property
+of both object paths is set to 0.
+
+### Multiple chassis system
+
+On a multiple chassis system with N chassis, all of the object paths above are
+published. The first object path represents the state of the entire system, and
+the other object paths represent the state of the individual chassis.
+
+When the system is powered off, the `state` and `pgood` properties for all of
+the object paths are 0.
+
+When the system is being powered on, the `state` will be changed to 1 for the
+system and for all chassis that **can** be powered on. It may not be possible to
+power on some chassis, such as if they are missing or have no input power. See
+[Powering On](powering_on.md) for more information.
+
+When an individual chassis has successfully powered on, the `pgood` property for
+that object path will change to 1. When all chassis whose `state` was set to 1
+have successfully powered on, the `pgood` property for the system object path
+will change to 1.
+
+If a power good fault occurs in a chassis after the system powered on, the
+`pgood` property for that chassis's object path will change to 0. The `pgood`
+property for the system object path will remain set to 1 for a period of time.
+Eventually the system will be powered off due to the power good fault. See
+[Power Good Faults](pgood_faults.md) for more information.
+
+When the system is being powered off, the `state` will be changed to 0 for the
+system and for all chassis that are being powered off.
+
+When an individual chassis has successfully powered off, the `pgood` property
+for that object path will change to 0. When all chassis have successfully
+powered off, the `pgood` property for the system object path will change to 0.
+
+### Initial property values
+
+When `phosphor-power-sequencer` is started, it needs to set initial values for
+the `state` and `pgood` properties. This occurs when a system first receives
+input power or after the BMC is reset.
+
+The chassis power good signal is read from the power sequencer device. Both the
+`state` and `pgood` properties are set to the value of the power good signal.
+For example, if the chassis power good is true, both `state` and `pgood` are set
+to the value 1. Thus, `phosphor-power-sequencer` assumes the chassis `state`
+based on the chassis `pgood`.
+
+In a multiple chassis system, it might not be possible to read the chassis power
+good signal. For example, the chassis might not be present or might have no
+input power. See the sections below for information about how the `pgood`
+property will be set.
+
+## Present property
+
+The `Present` property exists in the [`xyz.openbmc_project.Inventory.Item`][1]
+D-Bus interface.
+
+This interface is published on the D-Bus inventory path for each chassis.
+`phosphor-power-sequencer` does not publish this interface, but it checks the
+`Present` property on multiple chassis systems.
+
+The `Present` property indicates whether a chassis is physically present.
+
+If `Present` is set to false for a chassis:
+
+- The chassis power good signal from the power sequencer will **not** be read.
+ Since the chassis is not present, the `pgood` property on the
+ `org.openbmc.control.Power` interface for the chassis will be set to 0.
+- The chassis will **not** be powered on when the system is being powered on.
+ The `state` property on the `org.openbmc.control.Power` interface for the
+ chassis will remain set to 0.
+
+## Available property
+
+The `Available` property exists in the
+[`xyz.openbmc_project.State.Decorator.Availability`][2] D-Bus interface.
+
+This interface is published on the D-Bus inventory path for each chassis.
+`phosphor-power-sequencer` does not publish this interface, but it checks the
+`Available` property on multiple chassis systems.
+
+This interface is optional. If the interface exists and `Available` is set to
+false, it means that communication to the chassis is not possible. For example,
+the chassis does not have any input power ([blackout](power_loss.md)) or
+communication cables to the BMC are disconnected.
+
+If `Available` is set to false for a chassis:
+
+- The chassis power good signal from the power sequencer will **not** be read.
+ Since communication to the chassis is not possible, the value of the power
+ good signal is unknown. The following algorithm is used to set the value:
+ - If the chassis is experiencing a blackout, the chassis has no input power
+ and `pgood` will be set to 0.
+ - If all other chassis have a `pgood` value of 0, the `pgood` value will be
+ set to 0 for this chassis.
+ - If at least one other chassis has a `pgood` value of 1, the `pgood` value
+ will be set to 1 for this chassis.
+- The chassis will **not** be powered on when the system is being powered on.
+ The `state` property on the `org.openbmc.control.Power` interface for the
+ chassis will remain set to 0.
+
+## Enabled property
+
+The `Enabled` property exists in the [`xyz.openbmc_project.Object.Enable`][3]
+D-Bus interface.
+
+This interface is published on the D-Bus inventory path for each chassis.
+`phosphor-power-sequencer` does not publish this interface, but it checks the
+`Enabled` property on multiple chassis systems.
+
+This interface is optional. If the interface exists and `Enabled` is set to
+false, it means that the chassis has been put in hardware isolation (guarded). A
+critical error has been detected in the chassis, and it will not be used when
+the system is powered on.
+
+If `Enabled` is set to false for a chassis:
+
+- The chassis power good signal from the power sequencer will be read. The
+ `pgood` property on the `org.openbmc.control.Power` interface for the chassis
+ will be set to the value of this signal.
+- The chassis will **not** be powered on when the system is being powered on.
+ The `state` property on the `org.openbmc.control.Power` interface for the
+ chassis will remain set to 0.
+
+## Status property
+
+The `Status` property exists in the
+[`xyz.openbmc_project.State.Decorator.PowerSystemInputs`][4] D-Bus interface.
+
+`phosphor-power-sequencer` does not publish this interface, but it checks the
+`Status` property on multiple chassis systems.
+
+This interface is optional. If the interface exists and `Status` is set to
+`Fault`, it means that the chassis is experiencing a blackout or brownout. A
+[power loss](power_loss.md) is occurring, such as a power company utility
+failure or an unplugged power cord. See the sub-sections below for more
+information.
+
+### Chassis power status
+
+The `phosphor-chassis-power` application publishes the
+`xyz.openbmc_project.State.Decorator.PowerSystemInputs` interface on the
+following object paths:
+
+- `/xyz/openbmc_project/power/chassis/chassis1`
+- `/xyz/openbmc_project/power/chassis/chassis2`
+- ...
+- `/xyz/openbmc_project/power/chassis/chassisN`
+
+If `Status` is set to `Fault` for a chassis:
+
+- The chassis is experiencing a blackout.
+- The chassis power good signal from the power sequencer will **not** be read.
+ Since the chassis has no input power, the `pgood` property on the
+ `org.openbmc.control.Power` interface for the chassis will be set to 0.
+- The chassis will **not** be powered on when the system is being powered on.
+ The `state` property on the `org.openbmc.control.Power` interface for the
+ chassis will remain set to 0. An error will be logged indicating that the
+ chassis was not powered on due to an input power problem.
+
+### Power supplies power status
+
+The `phosphor-power-supply` application publishes the
+`xyz.openbmc_project.State.Decorator.PowerSystemInputs` interface on the
+following object paths:
+
+- `/xyz/openbmc_project/power/power_supplies/chassis1/psus`
+- `/xyz/openbmc_project/power/power_supplies/chassis2/psus`
+- ...
+- `/xyz/openbmc_project/power/power_supplies/chassisN/psus`
+
+If `Status` is set to `Fault` for the PSUs in a chassis:
+
+- The chassis is experiencing a brownout.
+- The chassis power good signal from the power sequencer will be read. The
+ `pgood` property on the `org.openbmc.control.Power` interface for the chassis
+ will be set to the value of this signal.
+- The chassis will **not** be powered on when the system is being powered on.
+ The `state` property on the `org.openbmc.control.Power` interface for the
+ chassis will remain set to 0. An error will be logged indicating that the
+ chassis was not powered on due to an input power problem.
+
+[1]:
+ https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Inventory/Item.interface.yaml
+[2]:
+ https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/State/Decorator/Availability.interface.yaml
+[3]:
+ https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Object/Enable.interface.yaml
+[4]:
+ https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/State/Decorator/PowerSystemInputs.interface.yaml
diff --git a/phosphor-power-sequencer/docs/internal_design.md b/phosphor-power-sequencer/docs/internal_design.md
new file mode 100644
index 0000000..750b0cd
--- /dev/null
+++ b/phosphor-power-sequencer/docs/internal_design.md
@@ -0,0 +1,51 @@
+# Internal Design
+
+## Key classes
+
+- PowerInterface
+ - Defines the `org.openbmc.control.Power` D-Bus interface.
+ - The `state` property is set to power the chassis on or off. This contains
+ the desired power state.
+ - The `pgood` property contains the actual power state of the chassis.
+- PowerControl
+ - Created in `main()`. Handles the event loop.
+ - Sub-class of PowerInterface that provides a concrete implementation of the
+ `org.openbmc.control.Power` D-Bus interface.
+ - Finds and loads the JSON configuration file.
+ - Finds power sequencer device information.
+ - Creates a sub-class of PowerSequencerDevice that matches power sequencer
+ device information.
+ - Powers the chassis on and off using the `power-chassis-control` named GPIO.
+ - Monitors the chassis pgood status every 3 seconds using the
+ `power-chassis-good` named GPIO.
+ - Enforces a minimum power off time of 15 seconds from cold start and 25
+ seconds from power off.
+- DeviceFinder
+ - Finds power sequencer device information on D-Bus published by
+ EntityManager.
+- Rail
+ - A voltage rail that is enabled or monitored by the power sequencer device.
+- PowerSequencerDevice
+ - Abstract base class for a power sequencer device.
+ - Defines virtual methods that must be implemented by all child classes.
+- StandardDevice
+ - Sub-class of PowerSequencerDevice that implements the standard pgood fault
+ detection algorithm.
+- PMBusDriverDevice
+ - Sub-class of StandardDevice for power sequencer devices that are bound to a
+ PMBus device driver.
+- UCD90xDevice
+ - Sub-class of PMBusDriverDevice for the UCD90X family of power sequencer
+ devices.
+- UCD90160Device
+ - Sub-class of UCD90xDevice representing a UCD90160 power sequencer device.
+- UCD90320Device
+ - Sub-class of UCD90xDevice representing a UCD90320 power sequencer device.
+- Services
+ - Abstract base class that provides an interface to system services like error
+ logging and the journal.
+- BMCServices
+ - Sub-class of Services with real implementation of methods.
+- MockServices
+ - Sub-class of Services with mock implementation of methods for automated
+ testing.
diff --git a/phosphor-power-sequencer/docs/monitoring_chassis_pgood.md b/phosphor-power-sequencer/docs/monitoring_chassis_pgood.md
new file mode 100644
index 0000000..61cdbcb
--- /dev/null
+++ b/phosphor-power-sequencer/docs/monitoring_chassis_pgood.md
@@ -0,0 +1,73 @@
+# Monitoring Chassis Power Good
+
+## Overview
+
+The power sequencer device provides a chassis power good (pgood) signal. This
+indicates that all of the main (non-standby) voltage rails are powered on.
+
+The `phosphor-power-sequencer` application periodically reads (polls) the
+chassis pgood signal from a named GPIO. For more information, see
+[Named GPIOs](named_gpios.md).
+
+The resulting chassis pgood value is used to set the `pgood` property for the
+chassis. See [Chassis Status](chassis_status.md) for more information on this
+property.
+
+If the chassis pgood state is false when it should be true, a chassis power good
+(pgood) fault has occurred. See [Power Good Faults](pgood_faults.md) for more
+information.
+
+## Unable to read chassis power good signal
+
+`phosphor-power-sequencer` may become unable to read the chassis power good
+signal from the named GPIO due to:
+
+- Hardware communication problems
+ - Unable to read from named GPIO after multiple retries.
+- The `Available` property of the chassis changes to false.
+
+### During power on
+
+If `phosphor-power-sequencer` is unable to read the chassis power good signal
+during a power on attempt, the application will do the following:
+
+- If this is a single chassis system:
+ - Log an error specifying the power on attempt failed due to an inability to
+ read the chassis power good status.
+ - `phosphor-chassis-state-manager` will [power off](powering_off.md) the
+ system.
+- If this is a multiple chassis system:
+ - If the chassis is experiencing a blackout:
+ - Log an error specifying an input power problem.
+ - If the chassis is not experiencing a blackout:
+ - Log an error specifying the power on attempt failed due to an inability to
+ read the chassis power good status.
+ - If the read failure was due to hardware communication problems, add the
+ inventory path of the chassis to the error log. This may result in
+ hardware isolation, which will cause the `Enabled` property of the chassis
+ to be false.
+ - `phosphor-chassis-state-manager` will power the system
+ [off](powering_off.md) and then [on](powering_on.md) again. If the chassis's
+ `Available` or `Enabled` property is false, the chassis will not be powered
+ on.
+
+### After power on
+
+If `phosphor-power-sequencer` is unable to read the chassis power good signal
+after the chassis powered on, the application will do the following:
+
+- If this is a single chassis system:
+ - Log an error specifying an inability to read the chassis power good status.
+ - Do **not** power off the system.
+ - Leave the `pgood` property set to the value 1.
+- If this is a multiple chassis system:
+ - If the chassis is experiencing a blackout:
+ - Set `pgood` value to 0.
+ - Log an error specifying an input power problem.
+ - Power the system off and then on again. If the chassis's `Available`
+ property is false, the chassis will not be powered on.
+ - If the chassis is not experiencing a blackout:
+ - Log an error specifying an inability to read the chassis power good
+ status.
+ - Do **not** power off the system.
+ - Leave the `pgood` property set to the value 1.
diff --git a/phosphor-power-sequencer/docs/multiple_chassis.md b/phosphor-power-sequencer/docs/multiple_chassis.md
new file mode 100644
index 0000000..bb43887
--- /dev/null
+++ b/phosphor-power-sequencer/docs/multiple_chassis.md
@@ -0,0 +1,63 @@
+# Multiple Chassis
+
+## Overview
+
+A BMC-based system can contain one or more chassis. A chassis is typically a
+physical enclosure that contains system components such as CPUs, fans, power
+supplies, and PCIe cards.
+
+A chassis can be stand-alone, such as a tower or desktop. A chassis can also be
+designed to be mounted in an equipment rack.
+
+For the `phosphor-power-sequencer` application, the term "single chassis system"
+means the system type has a maximum configuration of one chassis. If the system
+type has a maximum configuration of multiple chassis, then it is considered a
+"multiple chassis system" even if the current system only contains one chassis.
+
+## Differences between single and multiple chassis systems
+
+### System and chassis power state
+
+In a single chassis system, the system and chassis power state are identical.
+Both are either on or off.
+
+In a multiple chassis system, each chassis has its own power state. Even if the
+system is on, an individual chassis may be off. This can occur if that chassis
+does not have input power or has a critical hardware problem.
+
+See [Chassis Status](chassis_status.md) for more information.
+
+### Chassis power good faults
+
+If a single chassis system experiences a power good (pgood) fault, the system is
+powered off.
+
+If a multiple chassis system experiences a power good (pgood) fault in one
+chassis, the system will be powered off and then powered on again without that
+chassis.
+
+See [Power Good Faults](pgood_faults.md) for more information.
+
+### Brownouts
+
+If a single chassis system that was powered on experiences a brownout, the
+system will be powered off.
+
+If a multiple chassis system that was powered on experiences a brownout in one
+chassis, the system will be powered off and then powered on again without that
+chassis.
+
+See [Power Loss](power_loss.md) for more information.
+
+### Blackouts
+
+If a single chassis system that was powered on experiences a blackout, the
+system loses all power. It will be completely off until utility power is
+restored. It may then automatically power on again depending on the Auto Power
+Restart settings.
+
+If a multiple chassis system that was powered on experiences a blackout in one
+chassis, that chassis loses all power. The system will be powered off and then
+powered on again without that chassis.
+
+See [Power Loss](power_loss.md) for more information.
diff --git a/phosphor-power-sequencer/docs/named_gpios.md b/phosphor-power-sequencer/docs/named_gpios.md
new file mode 100644
index 0000000..9e30fdd
--- /dev/null
+++ b/phosphor-power-sequencer/docs/named_gpios.md
@@ -0,0 +1,32 @@
+# Named GPIOs
+
+## Chassis power control
+
+The main (non-standby) voltage rails in a chassis are powered on or off by
+toggling a named GPIO to the power sequencer device in the chassis.
+
+The GPIO name is defined in the Linux device tree. For single chassis systems,
+the standard GPIO name is `power-chassis-control`. See
+[Device Tree GPIO Naming in OpenBMC](https://github.com/openbmc/docs/blob/master/designs/device-tree-gpio-naming.md)
+for more information.
+
+The GPIO name in each chassis is specified in the
+[JSON configuration file](config_file/README.md). If no configuration file is
+found for the current system, the standard GPIO name is used.
+
+## Chassis power good (pgood)
+
+The power sequencer device provides a chassis power good (pgood) signal,
+indicating whether all the main (non-standby) rails are powered on.
+
+The `phosphor-power-sequencer` application reads the chassis power good signal
+from a named GPIO.
+
+The GPIO name is defined in the Linux device tree. For single chassis systems,
+the standard GPIO name is `power-chassis-good`. See
+[Device Tree GPIO Naming in OpenBMC](https://github.com/openbmc/docs/blob/master/designs/device-tree-gpio-naming.md)
+for more information.
+
+The GPIO name in each chassis is specified in the
+[JSON configuration file](config_file/README.md). If no configuration file is
+found for the current system, the standard GPIO name is used.
diff --git a/phosphor-power-sequencer/docs/pgood_faults.md b/phosphor-power-sequencer/docs/pgood_faults.md
new file mode 100644
index 0000000..559b9c7
--- /dev/null
+++ b/phosphor-power-sequencer/docs/pgood_faults.md
@@ -0,0 +1,108 @@
+# Power Good Faults
+
+## Overview
+
+The power sequencer device provides a chassis power good (pgood) signal. This
+indicates that all of the main (non-standby) voltage rails are powered on.
+
+If the chassis pgood state is false when it should be true, a chassis power good
+(pgood) fault has occurred.
+
+## Pgood fault while powering on the system
+
+When the power sequencer device is powering on the main voltage rails in order,
+one of the rails may fail to power on. This is often due to a hardware problem.
+
+When a voltage rail fails to power on, the power sequencer device may
+immediately indicate an error. However, the device may instead wait indefinitely
+for the rail to power on. In both cases the chassis pgood signal never changes
+to true.
+
+## Pgood fault after the system was powered on
+
+A pgood fault can occur after a system has been powered on. The system may have
+been successfully running for days or months.
+
+A voltage rail may suddenly power off or stop providing the expected level of
+voltage. This could occur if the voltage regulator stops working or if it shuts
+itself off due to exceeding a temperature/voltage/current limit.
+
+The power sequencer device will detect that the voltage rail has failed. The
+device will change the state of the chassis pgood signal to false. The device
+may also power off several other related voltage rails, depending on how the
+hardware is configured.
+
+## Pgood fault handling
+
+`phosphor-power-sequencer` detects a pgood fault by monitoring the chassis pgood
+signal:
+
+- Powering on chassis: pgood signal never changes to true.
+- Chassis was powered on: pgood signal changes from true to false.
+
+When a pgood fault is detected, `phosphor-power-sequencer` will perform the
+following steps:
+
+- Use information from the power sequencer device to determine the cause of the
+ fault.
+- Log an error with information about the fault.
+- If this is a single chassis system:
+ - The system will be [powered off](powering_off.md).
+- If this is a multiple chassis system:
+ - Wait a short period of time, and then check if all the other chassis that
+ were powered on are also experiencing a pgood fault. If so, check if any
+ chassis is experiencing a brownout or blackout. This determines whether this
+ is a chassis-specific problem or a system-wide problem due to a
+ [Power Loss](power_loss.md).
+ - If this is a chassis-specific problem, add the inventory path of the chassis
+ to the error log. This may result in hardware isolation, which will cause
+ the `Enabled` property of the chassis to be false.
+ - The system will be powered [off](powering_off.md) and then
+ [on](powering_on.md) again.
+ - Chassis with an `Enabled` value of false will **not** be powered back on.
+
+See [Chassis Status](chassis_status.md) for more information on the `Enabled`
+property.
+
+Note that when a pgood error happens **during** a power on attempt, the
+`phosphor-chassis-state-manager` application handles the power off/power cycle.
+When the pgood error happens **after** the system was powered on, the
+`phosphor-power-sequencer` application handles the power off/power cycle. This
+is due to the complex service file relationships that occur during a power on
+attempt.
+
+## Determining the cause of a pgood fault
+
+It is very helpful to determine which voltage rail caused a pgood fault. That
+determines what hardware potentially needs to be replaced.
+
+Determining the correct rail requires the following:
+
+- The power sequencer device type is supported by `phosphor-power-sequencer`.
+- A [JSON configuration file](config_file/README.md) is defined for the system.
+
+If those requirements are not met, a general pgood error will be logged.
+
+If those requirements are met, `phosphor-power-sequencer` will attempt to
+determine which voltage rail caused the chassis pgood fault. The following
+methods are supported in the JSON configuration file:
+
+- Read a GPIO from the power sequencer device
+- Check the PMBus STATUS_VOUT command value
+- Compare the PMBus READ_VOUT value to the PMBus VOUT_UV_FAULT_LIMIT value
+
+Multiple methods might need to be used on the same rail. For example, the PMBus
+STATUS_VOUT error bits might be set for a pgood fault after the system powered
+on, but they might not be set during a power on attempt because the power
+sequencer is waiting indefinitely for the rail to power on.
+
+See the [rail](config_file/rail.md) object in the configuration file for more
+information.
+
+If a specific voltage rail is found, an error is logged against that rail.
+
+If the voltage rail is from the power supplies, and the `phosphor-power-supply`
+application found a power supply error, then the power supply error is logged as
+the cause of the pgood fault.
+
+If no voltage rail is found, a general pgood error is logged.
diff --git a/phosphor-power-sequencer/docs/power_loss.md b/phosphor-power-sequencer/docs/power_loss.md
new file mode 100644
index 0000000..1f3f8a2
--- /dev/null
+++ b/phosphor-power-sequencer/docs/power_loss.md
@@ -0,0 +1,81 @@
+# Power Loss
+
+## Overview
+
+Power distribution in a computer system is complex. It typically flows from a
+wall outlet to power supplies to voltage regulators to system components. Other
+devices may exist between the wall outlet and the power supplies, such as an
+Uninterruptible Power Supply (UPS) or an Enclosure Power Distribution Unit
+(ePDU).
+
+A **brownout** is a partial reduction in voltage to the power supplies. In some
+situations, the standby voltage rails are still powered on but the main voltage
+rails are powered off. As a result, the BMC may still be running, but the host
+processor and other system components have lost power.
+
+A **blackout** is a complete loss of power to the power supplies.
+
+In a multiple chassis system, a brownout or blackout might only occur in some of
+the chassis.
+
+## System behavior during a brownout
+
+If the chassis was powered off when the brownout occurred, the
+`phosphor-power-sequencer` application will take no action.
+
+If the chassis was powered on when the brownout occurred, the power sequencer
+device will normally change the chassis power good (pgood) signal from true to
+false. `phosphor-power-sequencer` will isolate the failure to the power supply
+rail. `phosphor-power-sequencer` will log a power supply error. This error will
+specify the problem was the input voltage rather than the power supply hardware.
+See [Power Good Faults](pgood_faults.md) for more information.
+
+## System behavior during a blackout
+
+### Single chassis system
+
+The system loses all power. It will be completely off until utility power is
+restored.
+
+When power is restored, if the system was previously powered on, it may be
+automatically powered on again by the `phosphor-chassis-state-manager`
+application. This depends on the Auto Power Restart settings.
+
+### Multiple chassis system
+
+If the blackout affects all chassis, the system loses all power. It will behave
+as described above for a single chassis system.
+
+If the blackout only affects some chassis, the following steps will occur:
+
+- The `phosphor-chassis-power` application will do the following:
+ - Detect which chassis are experiencing a blackout.
+ - Set the `Status` property of the
+ `xyz.openbmc_project.State.Decorator.PowerSystemInputs` D-Bus interface to
+ `Fault` for the chassis experiencing a blackout.
+- The `Available` property will be set to false for chassis that are
+ experiencing a blackout.
+ - This is due to the `PowerSystemInputs` `Status` property being set to
+ `Fault` for the chassis.
+- If the BMC was reset by hardware due to the blackout, the following will
+ occur:
+ - `phosphor-power-sequencer` will read the pgood signal for each chassis and
+ use that value for the `state` and `pgood` properties of the
+ `org.openbmc.control.Power` D-Bus interface for the chassis.
+ - For chassis experiencing a blackout, the `state` and `pgood` properties
+ will be set to 0.
+ - `phosphor-chassis-state-manager` will obtain the previous on/off state of
+ each chassis from saved data.
+ - `phosphor-chassis-state-manager` will determine if a power problem has
+ occurred by checking if the following are all true:
+ - At least one chassis was previously on and is now off.
+ - The host operating system is not running or communicating
+ - If a power problem has occurred, `phosphor-chassis-state-manager` will do
+ the following:
+ - Log an error
+ - Power the system [off](powering_off.md) and then [on](powering_on.md)
+ again. The chassis with `Available` set to false will **not** be powered
+ on.
+
+See [Chassis Status](chassis_status.md) for more information on the D-Bus
+chassis status properties.
diff --git a/phosphor-power-sequencer/docs/powering_off.md b/phosphor-power-sequencer/docs/powering_off.md
new file mode 100644
index 0000000..0beb4ad
--- /dev/null
+++ b/phosphor-power-sequencer/docs/powering_off.md
@@ -0,0 +1,63 @@
+# Powering Off
+
+## Initiating a power off
+
+The system can be powered off by several methods, such as the `obmcutil` tool, a
+Redfish command, or a power button on the system enclosure.
+
+Whichever method is used, it sets the `state` property to 0 on the
+`org.openbmc.control.Power` D-Bus interface. The D-Bus object path is
+`/org/openbmc/control/power0`, which represents the entire system. See
+[Chassis Status](chassis_status.md) for more information.
+
+The `phosphor-power-sequencer` application only supports powering off the entire
+system. In a multiple chassis system, `phosphor-power-sequencer` does not
+support powering off individual chassis independent of the rest of the system.
+
+## Determining which chassis to power off
+
+In a single chassis system, `phosphor-power-sequencer` will always attempt to
+power off the chassis.
+
+In a multiple chassis system, `phosphor-power-sequencer` will only attempt to
+power off chassis with the proper status:
+
+- `Present` property is true
+- `Available` property is true (if interface exists)
+
+`phosphor-power-sequencer` will set the `state` property to 0 for all chassis.
+
+`phosphor-power-sequencer` will set the `pgood` property to 0 for all chassis
+where `Present` or `Available` are false.
+
+See [Chassis Status](chassis_status.md) for more information on these
+properties.
+
+## Powering off the voltage rails
+
+`phosphor-power-sequencer` powers off the main (non-standby) voltage rails in a
+chassis by toggling a named GPIO to the power sequencer device in the chassis.
+For more information, see [Named GPIOs](named_gpios.md).
+
+In each chassis being powered off, the power sequencer device powers off the
+individual voltage rails in the correct order.
+
+## Determining when power off is complete
+
+When the voltage rails have been powered off in a chassis, the power sequencer
+device will set the chassis power good (pgood) signal to false.
+
+`phosphor-power-sequencer` reads the chassis pgood signal from a named GPIO. For
+more information, see
+[Monitoring Chassis Power Good](monitoring_chassis_pgood.md).
+
+When the chassis power good signal changes to false, `phosphor-power-sequencer`
+will set the `pgood` property to 0 on the `org.openbmc.control.Power` interface
+for the **chassis** object path. The power off has finished for that chassis.
+
+When all chassis that were being powered off have finished,
+`phosphor-power-sequencer` will set the `pgood` property to 0 on the
+`org.openbmc.control.Power` interface for the **system** object path.
+
+See [Chassis Status](chassis_status.md) for more information on the `pgood`
+property.
diff --git a/phosphor-power-sequencer/docs/powering_on.md b/phosphor-power-sequencer/docs/powering_on.md
new file mode 100644
index 0000000..2f82ff2
--- /dev/null
+++ b/phosphor-power-sequencer/docs/powering_on.md
@@ -0,0 +1,95 @@
+# Powering On
+
+## Initiating a power on
+
+The system can be powered on by several methods, such as the `obmcutil` tool, a
+Redfish command, or a power button on the system enclosure.
+
+Whichever method is used, it sets the `state` property to 1 on the
+`org.openbmc.control.Power` D-Bus interface. The D-Bus object path is
+`/org/openbmc/control/power0`, which represents the entire system. See
+[Chassis Status](chassis_status.md) for more information.
+
+The `phosphor-power-sequencer` application only supports powering on the entire
+system. In a multiple chassis system, `phosphor-power-sequencer` does not
+support powering on individual chassis independent of the rest of the system.
+
+## Determining which chassis to power on
+
+In a single chassis system, `phosphor-power-sequencer` will always attempt to
+power on the chassis.
+
+In a multiple chassis system, `phosphor-power-sequencer` will only attempt to
+power on chassis with the proper status:
+
+- `Present` property is true
+- `Enabled` property is true (if interface exists)
+- `Available` property is true (if interface exists)
+- `Status` property is `Good` (if interface exists)
+
+`phosphor-power-sequencer` will set the `state` property to 1 for each chassis
+that is being powered on. It will set `state` to 0 for each chassis not being
+powered on.
+
+If no chassis are in the proper status to power on, `phosphor-power-sequencer`
+will log an error. `phosphor-chassis-state-manager` will
+[power off](powering_off.md) the system.
+
+See [Chassis Status](chassis_status.md) for more information on these
+properties.
+
+## Powering on the voltage rails
+
+`phosphor-power-sequencer` powers on the main (non-standby) voltage rails in a
+chassis by toggling a named GPIO to the power sequencer device in the chassis.
+For more information, see [Named GPIOs](named_gpios.md).
+
+In each chassis being powered on, the power sequencer device powers on the
+individual voltage rails in the correct order.
+
+## Determining when power on is complete
+
+When all voltage rails have been successfully powered on in a chassis, the power
+sequencer device will set the chassis power good (pgood) signal to true.
+
+`phosphor-power-sequencer` reads the chassis pgood signal from a named GPIO. For
+more information, see
+[Monitoring Chassis Power Good](monitoring_chassis_pgood.md).
+
+When the chassis power good signal changes to true, `phosphor-power-sequencer`
+will set the `pgood` property to 1 on the `org.openbmc.control.Power` interface
+for the **chassis** object path. The power on has finished for that chassis.
+
+When all chassis that were being powered on have finished,
+`phosphor-power-sequencer` will set the `pgood` property to 1 on the
+`org.openbmc.control.Power` interface for the **system** object path.
+
+See [Chassis Status](chassis_status.md) for more information on the `pgood`
+property.
+
+After all chassis have powered on, the rest of the boot process continues. The
+host operating system will eventually be started.
+
+## Handling errors
+
+### Power good fault
+
+When the power sequencer device is powering on the main voltage rails, one of
+the rails may fail to power on. Similarly, after the system has powered on, one
+of the voltage rails that had been providing power to the chassis might suddenly
+power off.
+
+In both cases the result is a pgood fault. See
+[Power Good Faults](pgood_faults.md) for information on how the error is
+handled.
+
+### Unable to read chassis power good signal
+
+`phosphor-power-sequencer` may become unable to read the chassis power good
+signal from the named GPIO due to:
+
+- Hardware communication problems.
+- The `Available` property of the chassis changes to false.
+
+See [Monitoring Chassis Power Good](monitoring_chassis_pgood.md) for more
+information on how the error is handled.
diff --git a/phosphor-power-sequencer/docs/testing.md b/phosphor-power-sequencer/docs/testing.md
index 56ac124..64560f0 100644
--- a/phosphor-power-sequencer/docs/testing.md
+++ b/phosphor-power-sequencer/docs/testing.md
@@ -1,4 +1,4 @@
-# phosphor-power-sequencer testing
+# Testing
## Overview
@@ -22,7 +22,7 @@
## Mock framework
One of the primary challenges with automated testing is handling external
-interfaces. The phosphor-power-sequencer application depends on the following
+interfaces. The `phosphor-power-sequencer` application depends on the following
external interfaces:
- D-Bus
@@ -46,8 +46,7 @@
actual external interfaces
- Mock sub-class that provides mock implementation of virtual methods
-The phosphor-power-sequencer application follows this pattern using the
-following classes:
+`phosphor-power-sequencer` follows this pattern using the following classes:
- [Services](../src/services.hpp)
- [BMCServices](../src/services.hpp)