regulators: Create high level design document
Create a high level design document for the phosphor-regulators
application. Summarize the high level algorithms and key C++ classes.
The low level design is documented in doxygen comments in the source
files.
Signed-off-by: Shawn McCarney <shawnmm@us.ibm.com>
Change-Id: I4f57063b2d4516da06a1f063ef83bb7ca92788bf
diff --git a/phosphor-regulators/docs/design.md b/phosphor-regulators/docs/design.md
new file mode 100644
index 0000000..b99fe74
--- /dev/null
+++ b/phosphor-regulators/docs/design.md
@@ -0,0 +1,139 @@
+# 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 system receives standby power.
+
+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.
+
+
+## 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. The D-Bus object implements the Sensor.Value and OperationalStatus
+interfaces. On subsequent reads, the existing D-Bus Sensor object is updated
+with the new sensor value.
+
+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 value of all D-Bus Sensor objects for this Rail will be set to 0.
+* The Functional property of all D-Bus Sensor objects for this Rail will be set
+ to false.
+* Sensor monitoring will continue.
+* The sensors for this Rail will be read again during the next monitoring
+ cycle.
+
+If, after an error occurs, a subsequent attempt to read the sensors for a Rail
+is successful:
+* The D-Bus Sensor objects for this Rail will be set to the new sensor values.
+* The Functional property of the D-Bus Sensor objects for this Rail will be set
+ to true.
+
+When regulator monitoring is disabled, the Manager object calls the
+`disableSensors()` method on all the objects representing the system (System,
+Chassis, Device, and Rail). Each D-Bus Sensor object is set to the special
+value NaN to indicate the Sensor is inactive.