regs: Reorganize regulators documentation
Reorganize the existing phosphor-regulators application documentation.
Break the documentation into smaller files describing one topic.
This will make it easier to add new documentation describing the
upcoming changes for multiple chassis systems.
Most of the 'changes' in this commit are just text that has been moved
between files.
Change-Id: I096f1d396910987188fe1143f36bade61655e7d1
Signed-off-by: Shawn McCarney <shawnmm@us.ibm.com>
diff --git a/phosphor-regulators/README.md b/phosphor-regulators/README.md
index 472197e..9cc3413 100644
--- a/phosphor-regulators/README.md
+++ b/phosphor-regulators/README.md
@@ -5,56 +5,15 @@
The `phosphor-regulators` application configures and monitors voltage
regulators. The application is controlled by a JSON configuration file.
-The application does not control how voltage regulators are enabled or how to
-monitor their Power Good (pgood) status. Those operations are typically
-performed by power sequencer hardware and related firmware.
+## Sub-directories
-## Configuring Voltage Regulators
-
-The configuration of voltage regulators can be modified. Configuration changes
-usually override hardware default settings.
-
-The most common configuration change is setting the output voltage for a
-regulator rail. Other examples include modifying pgood thresholds and
-overcurrent settings.
-
-The configuration changes are applied early in the boot process before
-regulators are enabled.
-
-## Monitoring Voltage Regulators
-
-Two types of regulator monitoring are supported:
-
-- Sensor monitoring
-- Phase fault monitoring
-
-### Sensor Monitoring
-
-The sensor values for a voltage rail are read, such as voltage output, current
-output, and temperature. Sensor values are measured, actual values rather than
-target values.
-
-Sensors are read once per second. The sensor values are stored on D-Bus on the
-BMC, making them available to external interfaces like Redfish.
-
-### Phase Fault Monitoring
-
-Some voltage regulators contain redundant phases. If a redundant phase fails,
-the regulator can continue functioning normally. However redundancy has been
-lost, and the regulator may fail if another phase fails.
-
-Voltage regulators can be monitored for redundant phase faults. If a fault is
-detected, an error is logged on the BMC.
-
-## JSON Configuration File
-
-The JSON configuration file defines the following:
-
-- Voltage regulators in the system.
-- Operations to perform on those regulators, such as configuration or sensor
- monitoring.
-
-Configuration files are stored in the `config_files` directory.
-
-See the [configuration file documentation](docs/config_file/README.md) for
-information on the file format, validation tool, and installation directories.
+- [config_files](config_files/) contains JSON configuration files
+- [docs](docs/) contains documentation on this application and the JSON
+ configuration file format
+- [examples](examples/) contains examples, such as a simple JSON configuration
+ file
+- [schema](schema/) contains schema defining the JSON configuration file format
+- [src](src/) contains the C++ implementation
+- [test](test/) contains automated test cases
+- [tools](tools/) contains command line tools, such as the JSON configuration
+ file validation tool
diff --git a/phosphor-regulators/docs/README.md b/phosphor-regulators/docs/README.md
new file mode 100644
index 0000000..24c32d7
--- /dev/null
+++ b/phosphor-regulators/docs/README.md
@@ -0,0 +1,62 @@
+# phosphor-regulators
+
+## Overview
+
+The `phosphor-regulators` application configures and monitors voltage
+regulators. The application is controlled by a JSON configuration file.
+
+The application does not control how voltage regulators are enabled or how to
+monitor their Power Good (pgood) status. Those operations are typically
+performed by power sequencer hardware and the
+[`phosphor-power-sequencer`](../../phosphor-power-sequencer/docs/README.md)
+application.
+
+## Application
+
+`phosphor-regulators` 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 a system-specific JSON configuration file. The JSON
+file is found and parsed at runtime. The parsing process creates a collection of
+C++ objects. These objects implement the regulator configuration and monitoring
+behavior that was specified in the JSON file.
+
+See [Internal Design](internal_design.md) for more information.
+
+## Configuring voltage regulators
+
+`phosphor-regulators` can modify the configuration of voltage regulators, such
+as modifying the output voltage or overcurrent limits.
+
+See [Regulator Configuration](configuration.md) for more information.
+
+## Monitoring voltage regulators
+
+`phosphor-regulators` supports two types of regulator monitoring:
+
+- Sensor monitoring
+ - Reading sensor values such as voltage output and temperature
+- Phase fault monitoring
+ - Checking if a redundant regulator phase has failed
+
+See [Regulator Monitoring](monitoring.md) for more information.
+
+## JSON configuration file
+
+The JSON configuration file defines the following:
+
+- Voltage regulators in the system.
+- Operations to perform on those regulators, such as configuration or sensor
+ monitoring.
+
+Configuration files are stored in the [`config_files`](../config_files)
+directory.
+
+See the [configuration file documentation](docs/config_file/README.md) for
+information on the file format, validation tool, and installation directories.
+
+## Testing
+
+Automated test cases exist for most of the code in this application. See
+[Testing](testing.md) for more information.
diff --git a/phosphor-regulators/docs/configuration.md b/phosphor-regulators/docs/configuration.md
new file mode 100644
index 0000000..4a3f310
--- /dev/null
+++ b/phosphor-regulators/docs/configuration.md
@@ -0,0 +1,42 @@
+# Regulator Configuration
+
+## Overview
+
+The configuration of voltage regulators can be modified. Configuration changes
+usually override hardware default settings.
+
+The most common configuration change is setting the output voltage for a
+regulator rail. Other examples include modifying pgood thresholds and
+overcurrent settings.
+
+Regulator configuration occurs early in the system boot before regulators have
+been enabled (turned on).
+
+## How configuration is defined
+
+Configuration is defined for a voltage regulator using the
+[configuration](config_file/configuration.md) object in the
+[JSON config file](config_file/README.md).
+
+This object specifies actions to run, such as
+[pmbus_write_vout_command](config_file/pmbus_write_vout_command.md) and
+[i2c_write_byte](config_file/i2c_write_byte.md).
+
+## How configuration is initiated
+
+During the system boot, the systemd service file
+[phosphor-regulators-config.service](../../services/phosphor-regulators-config.service)
+is started. This runs the `regsctl` utility. This utility invokes the D-Bus
+`configure` method on the `phosphor-regulators` application.
+`phosphor-regulators` will perform the configuration defined in the JSON config
+file.
+
+## Error handling
+
+If an error occurs while executing actions to perform configuration:
+
+- The error will be logged.
+- Any remaining actions for the current voltage regulator/rail will be skipped.
+- Configuration changes will still be applied to all remaining voltage
+ regulators in the system.
+- The system boot will continue.
diff --git a/phosphor-regulators/docs/design.md b/phosphor-regulators/docs/design.md
deleted file mode 100644
index 6f5c0c4..0000000
--- a/phosphor-regulators/docs/design.md
+++ /dev/null
@@ -1,170 +0,0 @@
-# Design
-
-This document describes the high-level design of the `phosphor-regulators`
-application.
-
-The low-level design is documented using doxygen comments in the source files.
-
-See [README.md](../README.md) for an overview of the functionality provided by
-this application.
-
-## Overview
-
-The `phosphor-regulators` 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 a system-specific JSON configuration file. The JSON
-file is found and parsed at runtime. The parsing process creates a collection of
-C++ objects. These objects implement the regulator configuration and monitoring
-behavior that was specified in the JSON file.
-
-## Key Classes
-
-- Manager
- - Top level class created in `main()`.
- - Loads the JSON configuration file.
- - Implements the D-Bus `configure` and `monitor` methods.
- - Contains a System object.
-- System
- - Represents the computer system being controlled and monitored by the BMC.
- - Contains one or more Chassis objects.
-- Chassis
- - Represents an enclosure that can be independently powered off and on by the
- BMC.
- - Small and mid-sized systems may contain a single Chassis.
- - In a large rack-mounted system, each drawer may correspond to a Chassis.
- - Contains one or more Device objects.
-- Device
- - Represents a hardware device, such as a voltage regulator or I/O expander.
- - Contains zero or more Rail objects.
-- Rail
- - Represents a voltage rail produced by a voltage regulator, such as 1.1V.
-- Services
- - Abstract base class that provides access to a collection of system services
- like error logging, journal, vpd, and hardware presence.
- - The BMCServices child class provides the real implementation.
- - The MockServices child class provides a mock implementation that can be used
- in gtest test cases.
-
-## Regulator Configuration
-
-Regulator configuration occurs early in the system boot before regulators have
-been enabled (turned on).
-
-A systemd service file runs the `regsctl` utility. This utility invokes the
-D-Bus `configure` method on the `phosphor-regulators` application.
-
-This D-Bus method is implemented by the Manager object. The Manager object calls
-the C++ `configure()` method on all the objects representing the system (System,
-Chassis, Device, and Rail).
-
-The configuration changes are applied to a Device or Rail by executing one or
-more actions, such as
-[pmbus_write_vout_command](config_file/pmbus_write_vout_command.md).
-
-If an error occurs while executing actions:
-
-- The error will be logged.
-- Any remaining actions for the current Device/Rail will be skipped.
-- Configuration changes will still be applied to all remaining Device/Rail
- objects in the system.
-- The system boot will continue.
-
-## Regulator Monitoring
-
-### Enabling Monitoring
-
-Regulator monitoring is enabled during the system boot after regulators are
-enabled (turned on).
-
-A systemd service file runs the `regsctl` utility. This utility invokes the
-D-Bus `monitor` method on the `phosphor-regulators` application. The parameter
-value `true` is passed to the method.
-
-This D-Bus method is implemented by the Manager object. The Manager object
-starts a timer. The timer periodically calls C++ monitoring methods on all the
-objects representing the system (System, Chassis, Device, and Rail).
-
-### Disabling Monitoring
-
-Regulator monitoring is disabled at the beginning of system shutdown before
-regulators are disabled (turned off).
-
-A systemd service file runs the `regsctl` utility. This utility invokes the
-D-Bus `monitor` method on the `phosphor-regulators` application. The parameter
-value `false` is passed to the method.
-
-This D-Bus method is implemented by the Manager object. The Manager object stops
-the timer that was periodically calling C++ monitor methods.
-
-### Sensor Monitoring
-
-When regulator monitoring is enabled, sensor values are read once per second.
-The timer in the Manager object calls the `monitorSensors()` method on all the
-objects representing the system (System, Chassis, Device, and Rail).
-
-The sensor values for a Rail (such as iout, vout, and temperature) are read
-using [pmbus_read_sensor](config_file/pmbus_read_sensor.md) actions.
-
-The first time a sensor value is read, a corresponding sensor object is created
-on D-Bus. On subsequent reads, the existing D-Bus sensor object is updated with
-the new sensor value.
-
-The D-Bus sensor object implements the following interfaces:
-
-- xyz.openbmc_project.Sensor.Value
-- xyz.openbmc_project.State.Decorator.OperationalStatus
-- xyz.openbmc_project.State.Decorator.Availability
-- xyz.openbmc_project.Association.Definitions
-
-An existing D-Bus Sensor object is removed from D-Bus if no corresponding sensor
-values are read during monitoring. This can occur in the following cases:
-
-- The regulator has been removed from the system (no longer present).
-- The regulator was replaced, and the new regulator supports a different set of
- sensors values. For example, temperature_peak is no longer provided.
-
-If an error occurs while reading the sensors for a Rail:
-
-- The error will be logged. If the same error occurs repeatedly on a Rail, it
- will only be logged once per system boot.
-- Any remaining actions for the Rail will be skipped.
-- The following changes will be made to all D-Bus sensor objects for this Rail:
- - The Value property will be set to NaN.
- - The Functional property will be set to false.
-- Sensor monitoring will continue with the next Rail or Device.
-- The sensors for this Rail will be read again during the next monitoring cycle.
-
-If a subsequent attempt to read the sensors for the Rail is successful, the
-following changes will be made to the D-Bus sensor objects:
-
-- The Value property will be set to the new sensor reading.
-- The Functional property will be set to true.
-
-When regulator monitoring is disabled, the following changes will be made to all
-of the D-Bus sensor objects:
-
-- The Value property will be set to NaN.
-- The Available property will be set to false.
-
-### Phase Fault Monitoring
-
-When regulator monitoring is enabled, phase fault detection is performed every
-15 seconds. The timer in the Manager object calls the `detectPhaseFaults()`
-method on all the objects representing the system (System, Chassis, Device).
-
-A phase fault must be detected two consecutive times (15 seconds apart) before
-an error is logged. This provides "de-glitching" to ignore transient hardware
-problems.
-
-A phase fault error will only be logged for a regulator once per system boot.
-
-If a different error occurs while detecting phase faults in a regulator:
-
-- The error will be logged. If the same error occurs repeatedly on regulator, it
- will only be logged once per system boot.
-- Any remaining actions for the regulator will be skipped.
-- Phase fault detection will continue with the next regulator.
-- Phase fault detection will be attempted again for this regulator during the
- next monitoring cycle.
diff --git a/phosphor-regulators/docs/internal_design.md b/phosphor-regulators/docs/internal_design.md
new file mode 100644
index 0000000..b3c96a4
--- /dev/null
+++ b/phosphor-regulators/docs/internal_design.md
@@ -0,0 +1,29 @@
+# Internal Design
+
+## Key classes
+
+- Manager
+ - Top level class created in `main()`.
+ - Loads the JSON configuration file.
+ - Implements the D-Bus `configure` and `monitor` methods.
+ - Contains a System object.
+- System
+ - Represents the computer system being controlled and monitored by the BMC.
+ - Contains one or more Chassis objects.
+- Chassis
+ - Represents an enclosure that can be independently powered off and on by the
+ BMC.
+ - Small and mid-sized systems may contain a single Chassis.
+ - In a large rack-mounted system, each drawer may correspond to a Chassis.
+ - Contains one or more Device objects.
+- Device
+ - Represents a hardware device, such as a voltage regulator or I/O expander.
+ - Contains zero or more Rail objects.
+- Rail
+ - Represents a voltage rail produced by a voltage regulator, such as 1.1V.
+- Services
+ - Abstract base class that provides access to a collection of system services
+ like error logging, journal, vpd, and hardware presence.
+ - The BMCServices child class provides the real implementation.
+ - The MockServices child class provides a mock implementation that can be used
+ in gtest test cases.
diff --git a/phosphor-regulators/docs/monitoring.md b/phosphor-regulators/docs/monitoring.md
new file mode 100644
index 0000000..aa17dfe
--- /dev/null
+++ b/phosphor-regulators/docs/monitoring.md
@@ -0,0 +1,42 @@
+# Regulator Monitoring
+
+## Overview
+
+The `phosphor-regulators` application supports two types of regulator
+monitoring:
+
+- [Sensor monitoring](sensor_monitoring.md)
+ - Reading sensor values such as voltage output and temperature
+- [Phase fault monitoring](phase_fault_monitoring.md)
+ - Checking if a redundant regulator phase has failed
+
+Monitoring is optional and is defined in the
+[JSON config file](config_file/README.md)
+
+## How monitoring is enabled
+
+Regulator monitoring is enabled during the system boot after regulators are
+enabled (turned on).
+
+The systemd service file
+[phosphor-regulators-monitor-enable.service](../../services/phosphor-regulators-monitor-enable.service)
+is started. This runs the `regsctl` utility. This utility invokes the D-Bus
+`monitor` method on the `phosphor-regulators` application. The parameter value
+`true` is passed to the method.
+
+`phosphor-regulators` will start performing the monitoring defined in the JSON
+config file. Monitoring is done periodically based on a timer.
+
+## How monitoring is disabled
+
+Regulator monitoring is disabled at the beginning of system shutdown before
+regulators are disabled (turned off).
+
+The systemd service file
+[phosphor-regulators-monitor-disable.service](../../services/phosphor-regulators-monitor-disable.service)
+is started. This runs the `regsctl` utility. This utility invokes the D-Bus
+`monitor` method on the `phosphor-regulators` application. The parameter value
+`false` is passed to the method.
+
+`phosphor-regulators` will stop performing the monitoring defined in the JSON
+config file.
diff --git a/phosphor-regulators/docs/phase_fault_monitoring.md b/phosphor-regulators/docs/phase_fault_monitoring.md
new file mode 100644
index 0000000..be863cd
--- /dev/null
+++ b/phosphor-regulators/docs/phase_fault_monitoring.md
@@ -0,0 +1,39 @@
+# Phase Fault Monitoring
+
+## Overview
+
+Some voltage regulators contain redundant phases. If a redundant phase fails,
+the regulator can continue functioning normally. However redundancy has been
+lost, and the regulator may fail if another phase fails.
+
+Voltage regulators can be monitored for redundant phase faults. If a fault is
+detected, an error is logged on the BMC.
+
+When [regulator monitoring](monitoring.md) is enabled, the `phosphor-regulators`
+application checks for redundant phase faults every 15 seconds.
+
+A phase fault must be detected two consecutive times (15 seconds apart) before
+an error is logged. This provides "de-glitching" to ignore transient hardware
+problems.
+
+A phase fault error will only be logged for a regulator once per system boot.
+
+## How phase fault detection is defined
+
+Phase fault detection is defined for a voltage regulator using the
+[phase_fault_detection](config_file/phase_fault_detection.md) object in the
+[JSON config file](config_file/README.md).
+
+This object specifies actions to run, such as
+[i2c_compare_byte](config_file/i2c_compare_byte.md).
+
+## Error handling
+
+If a different type of error occurs while detecting phase faults in a regulator:
+
+- The error will be logged. If the same error occurs repeatedly on regulator, it
+ will only be logged once per system boot.
+- Any remaining actions for the regulator will be skipped.
+- Phase fault detection will continue with the next regulator.
+- Phase fault detection will be attempted again for this regulator during the
+ next monitoring cycle.
diff --git a/phosphor-regulators/docs/sensor_monitoring.md b/phosphor-regulators/docs/sensor_monitoring.md
new file mode 100644
index 0000000..123f59d
--- /dev/null
+++ b/phosphor-regulators/docs/sensor_monitoring.md
@@ -0,0 +1,67 @@
+# Sensor Monitoring
+
+## Overview
+
+Sensor values such as output voltage, output current, and temperature can be
+read from some voltage regulators. Sensor values are measured, actual values
+rather than target values.
+
+When [regulator monitoring](monitoring.md) is enabled, the `phosphor-regulators`
+application reads sensor values once per second.
+
+The sensor values are stored on D-Bus on the BMC, making them available to
+external interfaces like Redfish.
+
+## How sensor monitoring is defined
+
+Sensor monitoring is defined for a voltage regulator using the
+[sensor_monitoring](config_file/sensor_monitoring.md) object in the
+[JSON config file](config_file/README.md).
+
+This object specifies actions to run, such as
+[pmbus_read_sensor](config_file/pmbus_read_sensor.md).
+
+## How sensors are stored on D-Bus
+
+The first time a sensor value is read, a corresponding sensor object is created
+on D-Bus. On subsequent reads, the existing D-Bus sensor object is updated with
+the new sensor value.
+
+The D-Bus sensor object implements the following interfaces:
+
+- xyz.openbmc_project.Sensor.Value
+- xyz.openbmc_project.State.Decorator.OperationalStatus
+- xyz.openbmc_project.State.Decorator.Availability
+- xyz.openbmc_project.Association.Definitions
+
+An existing D-Bus Sensor object is removed from D-Bus if no corresponding sensor
+values are read during monitoring. This can occur in the following cases:
+
+- The regulator has been removed from the system (no longer present).
+- The regulator was replaced, and the new regulator supports a different set of
+ sensors values. For example, temperature_peak is no longer provided.
+
+When regulator monitoring is disabled, the following changes will be made to all
+of the D-Bus sensor objects:
+
+- The Value property will be set to NaN.
+- The Available property will be set to false.
+
+## Error handling
+
+If an error occurs while reading the sensors for a voltage regulator rail:
+
+- The error will be logged. If the same error occurs repeatedly on a rail, it
+ will only be logged once per system boot.
+- Any remaining actions for the rail will be skipped.
+- The following changes will be made to all D-Bus sensor objects for this rail:
+ - The Value property will be set to NaN.
+ - The Functional property will be set to false.
+- Sensor monitoring will continue with the next rail or voltage regulator.
+- The sensors for this rail will be read again during the next monitoring cycle.
+
+If a subsequent attempt to read the sensors for the rail is successful, the
+following changes will be made to the D-Bus sensor objects:
+
+- The Value property will be set to the new sensor reading.
+- The Functional property will be set to true.
diff --git a/phosphor-regulators/docs/testing.md b/phosphor-regulators/docs/testing.md
new file mode 100644
index 0000000..e1bfa7d
--- /dev/null
+++ b/phosphor-regulators/docs/testing.md
@@ -0,0 +1,53 @@
+# Testing
+
+## 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::configure()` is tested by
+`TEST(RailTests, Configure)`.
+
+## Mock framework
+
+One of the primary challenges with automated testing is handling external
+interfaces. The `phosphor-regulators` application depends on the following
+external interfaces:
+
+- D-Bus
+- Error logging
+- Hardware presence
+- Hardware Vital Product Data (VPD)
+- Journal
+- Sensors
+
+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
+
+`phosphor-regulators` follows this pattern using the following classes:
+
+- [Services](../src/services.hpp)
+ - [BMCServices](../src/services.hpp)
+ - [MockServices](../test/mock_services.hpp)