pseq: Update documentation
Update the phosphor-power-sequencer documentation to reflect recent
enhancements:
* New JSON configuration file format
* PowerSequencerDevice class hierarchy
* Enhanced pgood isolation support
* Automated tests
Change-Id: I8a7b76f4685cf9d55f1147658cc703b6d558f94b
Signed-off-by: Shawn McCarney <shawnmm@us.ibm.com>
diff --git a/README.md b/README.md
index 8df14f5..dda53c5 100644
--- a/README.md
+++ b/README.md
@@ -3,19 +3,24 @@
This repository contains applications for configuring and monitoring devices
that deliver power to the system.
+Actively-maintained applications:
+
- cold-redundancy: Application that makes power supplies work in Cold Redundancy
mode and rotates them at intervals.
-- [phosphor-power-sequencer](phosphor-power-sequencer/README.md): Applications
- for configuring and monitoring power sequencer and related devices that
- support JSON-driven configuration.
+- [phosphor-power-sequencer](phosphor-power-sequencer/README.md): JSON-driven
+ application that powers the chassis on/off and monitors the power sequencer
+ device.
- [phosphor-power-supply](phosphor-power-supply/README.md): Next generation
power supply monitoring application.
- [phosphor-regulators](phosphor-regulators/README.md): JSON-driven application
that configures and monitors voltage regulators.
-- power-sequencer: A power sequencer monitoring application.
-- power-supply: Original power supply monitoring application.
- tools/power-utils: Power supply utilities.
+Legacy applications:
+
+- power-sequencer: Original power sequencer monitoring application.
+- power-supply: Original power supply monitoring application.
+
## Build
To build all applications in this repository:
diff --git a/phosphor-power-sequencer/README.md b/phosphor-power-sequencer/README.md
index 0666f41..7ed9657 100644
--- a/phosphor-power-sequencer/README.md
+++ b/phosphor-power-sequencer/README.md
@@ -1,21 +1,13 @@
## Overview
-This directory is a repository for applications which perform power control or
-configure or monitor power sequencer or related devices. These applications may
-support JSON-driven configuration.
+The phosphor-power-sequencer application powers the chassis on/off and monitors
+the power sequencer device. The application is configured by an optional JSON
+configuration file.
-The currently implemented application is named `phosphor-power-control` and
-supports GPIO based power control and power sequencer monitoring with specific
-support for the UCD90320 and UCD90160 devices available.
+## Sub-directories
-## JSON Configuration Files
-
-Configuration files are stored in the `config_files` directory. See the
-[Configuration File README](config_files/README.md) for details on the format of
-power sequencer configuration files.
-
-## Source Files
-
-Source files are stored in the `src` directory. See the
-[Source Files README](src/README.md) for details on the design of the
-application source.
+- [config_files](config_files/) contains JSON configuration files
+- [docs](docs/) contains documentation on this application and the JSON
+ configuration file format
+- [src](src/) contains the C++ implementation
+- [test](test/) contains automated test cases
diff --git a/phosphor-power-sequencer/config_files/README.md b/phosphor-power-sequencer/config_files/README.md
deleted file mode 100644
index c2c9374..0000000
--- a/phosphor-power-sequencer/config_files/README.md
+++ /dev/null
@@ -1,77 +0,0 @@
-## Overview
-
-The `UCD90xMonitor` class and its subclasses determine the device configuration
-from a JSON configuration file. The configuration file describes the power
-sequencer rails and power good (pgood) pins defined in the system.
-
-## File Name
-
-The expected filename format is `<device>Monitor_<systemType>.json`, where
-`<device>` is the specific power sequencer device type (UCD90320 or UCD90160),
-and `<systemType>` is a `Compatible System` name from a `Chassis` Entity Manager
-configuration file.
-
-Example file name:
-
-```
-UCD90320Monitor_mysystem.json
-```
-
-## File Format
-
-The configuration consists of an array of `rails` and an array of `pins`. Both
-`rails` and `pins` use a `name` element. The name element should be mnemonic and
-unique. If the BMC system utilizes the openpower-pels extension, then it will be
-used as an index into the `phosphor-logging` Message Registry.
-
-Example `rails` array with `name` elements:
-
-```
-"rails": [
- { "name": "12.0V" },
- { "name": "VDN_DCM0" }
-]
-```
-
-The `pins` array also uses a `line` element which is the GPIO line number of the
-pgood pin in the power sequencer device.
-
-Example `pins` array with `name` and `line` elements:
-
-```
-"pins": [
- {
- "name": "5.0V",
- "line": 67
- },
- {
- "name": "VCS_DCM0",
- "line": 74
- }
-]
-```
-
-Both `rails` and `pins` can optionally define a `presence` element which is an
-inventory path to a system component which must be present in order for the rail
-or pin to be used in failure isolation. By default, a rail or pin is considered
-to be present, which could mean the necessary parts are always present in the
-system or that a not present part would not cause a pgood failure.
-
-Example `rails` array element including `presence` element:
-
-```
-{
- "name": "VCS1",
- "presence": "/xyz/openbmc_project/inventory/system/chassis/motherboard/vrm1"
-}
-```
-
-Example `pins` array element including `presence` element:
-
-```
-{
- "name": "VPCIE",
- "line": 61,
- "presence": "/xyz/openbmc_project/inventory/system/chassis/motherboard/vrm0"
-}
-```
diff --git a/phosphor-power-sequencer/docs/README.md b/phosphor-power-sequencer/docs/README.md
new file mode 100644
index 0000000..3efc172
--- /dev/null
+++ b/phosphor-power-sequencer/docs/README.md
@@ -0,0 +1,169 @@
+## Overview
+
+The phosphor-power-sequencer application powers the chassis on/off and monitors
+the power sequencer device.
+
+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.
+
+## 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.
+
+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.
+
+## 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:
+
+- UCD90160
+- UCD90320
+
+Additional device types can be supported by creating a new sub-class within the
+PowerSequencerDevice class hierarchy.
+
+## Powering on the chassis
+
+- 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 off the 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.
+
+## Pgood fault
+
+A power good (pgood) fault occurs in two scenarios:
+
+- 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.
+
+If the pgood fault occurs when attempting to power on the chassis, the chassis
+pgood signal never changes to true.
+
+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`.
+
+## Identifying the cause of a pgood fault
+
+It is very helpful to identify which voltage rail caused the 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 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.
+
+## 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.
+
+JSON configuration files are system-specific and are stored in the
+[config_files](../config_files/) sub-directory.
+
+[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.
+
+## Testing
+
+Automated test cases exist for most of the code in this application. See
+[testing.md](testing.md) for more information.
diff --git a/phosphor-power-sequencer/docs/config_file/README.md b/phosphor-power-sequencer/docs/config_file/README.md
index a9bb23c..3fcde51 100644
--- a/phosphor-power-sequencer/docs/config_file/README.md
+++ b/phosphor-power-sequencer/docs/config_file/README.md
@@ -43,19 +43,24 @@
Example:
-- `com.ibm.Hardware.Chassis.Model.Rainier4U`
-- `com.ibm.Hardware.Chassis.Model.Rainier`
+- `com.acme.Hardware.Chassis.Model.MegaServer4CPU`
+- `com.acme.Hardware.Chassis.Model.MegaServer`
+- `com.acme.Hardware.Chassis.Model.Server`
-The `phosphor-power-sequencer` application converts each compatible system type
-into a config file name by adding a `.json` suffix.
+The `phosphor-power-sequencer` application searches for a config file name that
+matches one of these compatible system types. It searches from most specific to
+least specific. The first config file found, if any, will be used.
+
+For each compatible system type, the application will look for two config file
+names:
+
+- The complete compatible system type plus a '.json' suffix
+- The last node of the compatible system type plus a '.json' suffix
Example:
-- `com.ibm.Hardware.Chassis.Model.Rainier.json`
-
-The application searches for a config file that exists with one of these file
-names. It searches from most specific to least specific. The first config file
-found, if any, will be used.
+- `com.acme.Hardware.Chassis.Model.MegaServer4CPU.json`
+- `MegaServer4CPU.json`
## Contents
diff --git a/phosphor-power-sequencer/docs/config_file/rail.md b/phosphor-power-sequencer/docs/config_file/rail.md
index a65073d..0cddd7c 100644
--- a/phosphor-power-sequencer/docs/config_file/rail.md
+++ b/phosphor-power-sequencer/docs/config_file/rail.md
@@ -6,7 +6,21 @@
The "check_status_vout", "compare_voltage_to_limit", and "gpio" properties
specify how to obtain the pgood status of the rail. You can specify more than
-one of these properties if necessary.
+one of these properties.
+
+The "check_status_vout" method is usually the most accurate. For example, if a
+pgood fault occurs, the power sequencer device may automatically shut off
+related rails. Ideally the device will only set fault bits in STATUS_VOUT for
+the rail with the pgood fault. However, all the related rails will likely appear
+to be faulted by the other methods.
+
+The "compare_voltage_to_limit" method is helpful when a rail fails to power on
+during the power on sequence and the power sequencer device waits indefinitely
+for it to power on.
+
+The "gpio" method is necessary when no PMBus information is available for the
+rail. It is also helpful when a rail fails to power on during the power on
+sequence and the power sequencer device waits indefinitely for it to power on.
## Properties
diff --git a/phosphor-power-sequencer/docs/testing.md b/phosphor-power-sequencer/docs/testing.md
new file mode 100644
index 0000000..9cb8f60
--- /dev/null
+++ b/phosphor-power-sequencer/docs/testing.md
@@ -0,0 +1,52 @@
+## Overview
+
+The [test](../test) directory contains automated test cases written using the
+[GoogleTest](https://github.com/google/googletest) framework. These tests are
+run during Continuous Integration (CI) testing.
+
+The goal is to write automated test cases for as much application code as
+possible.
+
+## Test case conventions
+
+Each implementation source file should have a corresponding tests file. For
+example, [rail.cpp](../src/rail.cpp) is tested by
+[rail_tests.cpp](../test/rail_tests.cpp).
+
+Within the tests file, there should be a TEST for each public method or global
+scope function. For example, `Rail::isPresent()` is tested by
+`TEST(RailTests, IsPresent)`.
+
+## Mock framework
+
+One of the primary challenges with automated testing is handling external
+interfaces. The phosphor-power-sequencer application depends on the following
+external interfaces:
+
+- D-Bus
+- Journal
+- Error logging
+- GPIOs
+- sysfs files containing PMBus information
+- BMC dump
+
+These interfaces are either not available or do not behave properly within the
+CI test environment. Thus, in automated test cases they need to be mocked.
+
+The GoogleTest mock framework is used to implement mocking. This allows the
+behavior of the external interface to be simulated and controlled within the
+test case.
+
+The mock framework typically relies on a class hierarchy of the following form:
+
+- Abstract base class with virtual methods for external interfaces
+ - Concrete sub-class with real implementation of virtual methods that call
+ 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:
+
+- [Services](../src/services.hpp)
+ - [BMCServices](../src/services.hpp)
+ - [MockServices](../test/mock_services.hpp)
diff --git a/phosphor-power-sequencer/src/README.md b/phosphor-power-sequencer/src/README.md
deleted file mode 100644
index 91a1580..0000000
--- a/phosphor-power-sequencer/src/README.md
+++ /dev/null
@@ -1,57 +0,0 @@
-## Overview
-
-This directory contains the source code for applications performing system power
-on and off control, and power sequencer device configuration and monitoring.
-
-## Class Descriptions
-
-### PowerControl
-
-Implements GPIO control of power on / off and monitoring of the chassis power
-good (pgood). The GPIOs are defined in the device tree and are named
-`power-chassis-control` and `power-chassis-good` respectively. The chassis pgood
-is monitored on a three second poll. Enforces a minimum power off time of 15
-seconds from cold start and 25 seconds from power off.
-
-Provides the server implementation of the `org.openbmc.control.Power` D-Bus
-interface.
-
-Determines the type and I2C information of the power sequencer device with the
-Entity Manager `xyz.openbmc_project.Configuration.UCD90320` or
-`xyz.openbmc_project.Configuration.UCD90160` interface. If a specific device
-interface is not provided or not desired, a generic base class implementation
-(see the `PowerSequencerMonitor` class below) will be used.
-
-### PowerInterface
-
-Defines the `org.openbmc.control.Power` D-Bus interface.
-
-The `state` property is set to initiate a power on or power off sequence. The
-power good `pgood` property reflects the power state of the chassis. At power on
-time the `pgood` will lag the `state` as the power sequencer performs its
-processing. The same lag will occur on a requested power off. Loss of `pgood`
-without a `state` change request indicates a pgood failure.
-
-### PowerSequencerMonitor
-
-Implements a generic power sequencer device monitoring interface. Used when the
-specific device type is not specified or cannot be determined. Also used as a
-base class for specific device classes. The generic implementation does not do
-any device specific analysis and does not need Entity Manager or JSON file
-configuration.
-
-### UCD90xMonitor
-
-Defines a base class for monitoring the UCD90\* family of power sequencer
-devices and implements the common behavior. Uses the Entity Manager
-`IBMCompatibleSystem` interface to locate its JSON based configuration. The
-loaded configuration allows pgood failure analysis to determine the specific
-voltage rail or pgood pin which has failed.
-
-### UCD90320Monitor
-
-Implements a specific UCD90320 power sequencer device monitoring class.
-
-### UCD90160Monitor
-
-Implements a specific UCD90160 power sequencer device monitoring class.