Initial documentation for regulator config files
Added documentation for the phosphor-regulators config file. The
phosphor-regulators application configures and monitors voltage
regulators.
This commit contains the README, an example config file, and
documentation for the root object within the config file. Subsequent
commits will add documentation for the other JSON objects in the config
file.
Signed-off-by: Shawn McCarney <shawnmm@us.ibm.com>
Change-Id: Ia5cea4bb5a4d4053c1537ce385fcd3c903423e56
diff --git a/phosphor-regulators/docs/config_file/README.md b/phosphor-regulators/docs/config_file/README.md
new file mode 100644
index 0000000..a51f82c
--- /dev/null
+++ b/phosphor-regulators/docs/config_file/README.md
@@ -0,0 +1,189 @@
+# phosphor-regulators Configuration File
+
+## Overview
+
+The `phosphor-regulators` application is controlled by a configuration file
+(config file). The config file defines how to perform the following operations
+on voltage regulators in the system:
+* Modify regulator configuration, such as output voltage or overcurrent
+ settings
+* Read sensor values
+
+The config file 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.
+
+
+## Data Format
+
+The config file is written using the [JSON (JavaScript Object
+Notation)](https://www.json.org/) data format.
+
+The config file can be created using any text editor, such as Atom, Notepad++,
+gedit, Vim, or Emacs. You can select any file name, but it must end with the
+".json" suffix, such as `regulators.json`.
+
+
+## Example
+
+See [config_file.json](../../examples/config_file.json).
+
+
+## Contents
+
+### Structure
+
+The config file typically contains the following structure:
+* Array of [rules](rule.md)
+ * Rules defining how to modify configuration of regulators
+ * Rules defining how to read sensors
+* Array of [chassis](chassis.md) in the system
+ * Array of regulator [devices](device.md) in the chassis
+ * Array of voltage [rails](rail.md) produced by the regulator
+
+Rules provide common, reusable sequences of actions that can be shared by one
+or more regulators. They are optional and can be omitted if each regulator
+requires a unique sequence of actions.
+
+### Syntax
+
+The config file contains a single JSON [config_file](config_file.md) object at
+the root level. That object contains arrays of other JSON objects.
+
+The following JSON object types are supported:
+* [action](action.md)
+* [and](and.md)
+* [chassis](chassis.md)
+* [compare_presence](compare_presence.md)
+* [compare_vpd](compare_vpd.md)
+* [config_file](config_file.md)
+* [configuration](configuration.md)
+* [device](device.md)
+* [i2c_compare_bit](i2c_compare_bit.md)
+* [i2c_compare_byte](i2c_compare_byte.md)
+* [i2c_compare_bytes](i2c_compare_bytes.md)
+* [i2c_interface](i2c_interface.md)
+* [i2c_write_bit](i2c_write_bit.md)
+* [i2c_write_byte](i2c_write_byte.md)
+* [i2c_write_bytes](i2c_write_bytes.md)
+* [if](if.md)
+* [not](not.md)
+* [or](or.md)
+* [pmbus_read_sensor](pmbus_read_sensor.md)
+* [pmbus_write_vout_command](pmbus_write_vout_command.md)
+* [presence_detection](presence_detection.md)
+* [rail](rail.md)
+* [rule](rule.md)
+* [run_rule](run_rule.md)
+* [sensor_monitoring](sensor_monitoring.md)
+* [set_device](set_device.md)
+
+### Comments
+
+The JSON data format does not support comments. However, many of the JSON
+objects in the config file provide an optional "comments" property. The value
+of this property is an array of strings. Use this property to annotate the
+config file. The "comments" properties are ignored when the config file is
+read by the `phosphor-regulators` application.
+
+Examples:
+
+```
+"comments": [ "IR35221 regulator producing the Vdd rail" ]
+
+"comments": [ "Check if register 0x82 contains 0x7302",
+ "Device returns bytes in little-endian order",
+ "Ignore most significant bit in each byte" ]
+```
+
+### Hexadecimal Values
+
+The JSON number data type does not support the hexadecimal format. For this
+reason, properties with hexadecimal values use the string data type.
+
+Example:
+```
+"address": "0x70"
+```
+
+
+## Validation
+
+After creating or modifying a config file, you need to validate it using the
+tool [validate-regulators-config](../../tools/validate-regulators-config).
+
+The validation tool checks the config file for errors, such as:
+* Invalid JSON syntax (like a missing brace)
+* Unrecognized JSON object or property
+* Duplicate rule or device ID
+* Reference to a rule or device ID that does not exist
+* Infinite loop, such as rule A runs rule B which runs rule A
+
+The tool requires two input files:
+* config file to validate
+* [config_schema.json](../../tools/config_schema.json)
+
+The tool has the following command line syntax:
+```
+validate-regulators-config -c <config file> -s config_schema.json
+```
+where `<config file>` is the name of the config file to validate.
+
+
+## Installation
+
+### Standard Directory
+
+`/usr/share/phosphor-regulators`
+
+The standard version of the config file should be installed in this read-only
+directory as part of the firmware image install. This is the config file that
+will normally be used.
+
+### Test Directory
+
+`/etc/phosphor-regulators`
+
+A new version of the config file can be tested by copying it into this writable
+directory. This avoids the need to build and install a new firmware image on
+the BMC.
+
+### Search Order
+
+The `phosphor-regulators` application will search first in the test directory
+for a config file. If no config file is found or the file contains errors, the
+application will next search in the standard directory.
+
+
+## Loading and Reloading
+
+The config file is loaded when the `phosphor-regulators` application starts.
+
+To force the application to reload the config file, use the following command
+on the BMC:
+
+``kill -SIGHUP `pidof phosphor-regulators` ``
+
+
+## Testing
+
+After creating or modifying a config file, you should test it to ensure it
+provides the desired behavior.
+
+Perform the following steps to test the config file:
+* Run the [validation tool](#validation) to ensure the config file contains no
+ errors.
+* Copy the config file into the [test directory](#test-directory) on the BMC.
+* Force the `phosphor-regulators` application to
+ [reload](#loading-and-reloading) its config file, causing it to find and load
+ the file in the test directory.
+* Boot the system. Regulator configuration changes (such as voltage settings)
+ are only applied during the boot.
+
+When finished testing, perform the following steps to revert to the standard
+config file:
+* Remove the config file from the test directory.
+* Force the `phosphor-regulators` application to reload its config file,
+ causing it to find and load the file in the standard directory.
+* Boot the system, if necessary, to apply the regulator configuration changes
+ in the standard config file.
diff --git a/phosphor-regulators/docs/config_file/config_file.md b/phosphor-regulators/docs/config_file/config_file.md
new file mode 100644
index 0000000..dec3ba1
--- /dev/null
+++ b/phosphor-regulators/docs/config_file/config_file.md
@@ -0,0 +1,36 @@
+# config_file
+
+## Description
+The root (outer-most) object in a phosphor-regulators configuration file.
+
+## Properties
+| Name | Required | Type | Description |
+| :--- | :------: | :--- | :---------- |
+| comments | no | array of strings | One or more comment lines describing this file. |
+| rules | no | array of [rules](rule.md) | One or more rules shared by regulators in this file. |
+| chassis | yes | array of [chassis](chassis.md) | One or more chassis in the system. |
+
+## Example
+```
+{
+ "comments": [ "Config file for a FooBar one-chassis system" ],
+ "rules": [
+ {
+ "id": "set_voltage_rule",
+ ... details omitted ...
+ },
+ {
+ "id": "read_sensors_rule",
+ ... details omitted ...
+ }
+ ],
+ "chassis": [
+ {
+ "number": 1,
+ "devices": [
+ ... details omitted ...
+ ]
+ }
+ ]
+}
+```
diff --git a/phosphor-regulators/examples/config_file.json b/phosphor-regulators/examples/config_file.json
new file mode 100644
index 0000000..701322d
--- /dev/null
+++ b/phosphor-regulators/examples/config_file.json
@@ -0,0 +1,106 @@
+{
+ "comments": [ "Config file for a FooBar one-chassis system" ],
+
+ "rules": [
+ {
+ "comments": [ "Sets output voltage for a PMBus regulator rail" ],
+ "id": "set_voltage_rule",
+ "actions": [
+ {
+ "pmbus_write_vout_command": {
+ "format": "linear"
+ }
+ }
+ ]
+ },
+
+ {
+ "comments": [ "Reads sensors from a PMBus regulator rail" ],
+ "id": "read_sensors_rule",
+ "actions": [
+ {
+ "comments": [ "Read output voltage from READ_VOUT." ],
+ "pmbus_read_sensor": {
+ "type": "vout",
+ "command": "0x8B",
+ "format": "linear_16"
+ }
+ },
+
+ {
+ "comments": [ "Read output current from READ_IOUT." ],
+ "pmbus_read_sensor": {
+ "type": "iout",
+ "command": "0x8C",
+ "format": "linear_11"
+ }
+ },
+
+ {
+ "comments": [ "Read temperature from READ_TEMPERATURE_1." ],
+ "pmbus_read_sensor": {
+ "type": "temperature",
+ "command": "0x8D",
+ "format": "linear_11"
+ }
+ }
+ ]
+ }
+ ],
+
+ "chassis": [
+ {
+ "comments": [ "Chassis number 1 containing CPUs and memory" ],
+ "number": 1,
+ "devices": [
+ {
+ "comments": [ "IR35221 regulator producing the Vdd rail" ],
+ "id": "vdd_regulator",
+ "is_regulator": true,
+ "fru": "/system/chassis/motherboard/regulator1",
+ "i2c_interface": {
+ "bus": 1,
+ "address": "0x70"
+ },
+ "rails": [
+ {
+ "comments": [ "Vdd rail" ],
+ "id": "vdd",
+ "configuration": {
+ "volts": 1.03,
+ "rule_id": "set_voltage_rule"
+ },
+ "sensor_monitoring": {
+ "rule_id": "read_sensors_rule"
+ }
+ }
+ ]
+ },
+
+ {
+ "comments": [ "IR35221 regulator producing the Vio rail" ],
+ "id": "vio_regulator",
+ "is_regulator": true,
+ "fru": "/system/chassis/motherboard/regulator2",
+ "i2c_interface": {
+ "bus": 1,
+ "address": "0x71"
+ },
+ "rails": [
+ {
+ "comments": [ "Vio rail" ],
+ "id": "vio",
+ "configuration": {
+ "volts": 1.1,
+ "rule_id": "set_voltage_rule"
+ },
+ "sensor_monitoring": {
+ "rule_id": "read_sensors_rule"
+ }
+ }
+ ]
+ }
+ ]
+ }
+ ]
+}