Document operations in regulator config file
Created documentation for the phosphor-regulators config file. This
commit contains documentation for the JSON objects that perform the high
level regulator operations, such as modifying the regulator
configuration or reading all regulator sensors.
Signed-off-by: Shawn McCarney <shawnmm@us.ibm.com>
Change-Id: I08a8291e0df0f33b7725cf42a98c6d05d0cd59bb
diff --git a/phosphor-regulators/docs/config_file/configuration.md b/phosphor-regulators/docs/config_file/configuration.md
new file mode 100644
index 0000000..f5ca84d
--- /dev/null
+++ b/phosphor-regulators/docs/config_file/configuration.md
@@ -0,0 +1,56 @@
+# configuration
+
+## Description
+Configuration changes that should be applied to a device or regulator rail.
+These 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 during the boot before regulators are
+enabled.
+
+The configuration changes are applied by executing one or more actions. The
+actions can be specified in two ways:
+* Use the "rule_id" property to specify a standard rule to run.
+* Use the "actions" property to specify an array of actions that are unique to
+ this device.
+
+## Properties
+| Name | Required | Type | Description |
+| :--- | :------: | :--- | :---------- |
+| comments | no | array of strings | One or more comment lines describing the configuration changes. |
+| volts | no | number | Output voltage expressed as a decimal number. Applied using the [pmbus_write_vout_command](pmbus_write_vout_command.md) action. |
+| rule_id | see [notes](#notes) | string | Unique ID of the [rule](rule.md) to execute. |
+| actions | see [notes](#notes) | array of [actions](action.md) | One or more actions to execute. |
+
+### Notes
+* You must specify either "rule_id" or "actions".
+
+## Examples
+```
+{
+ "comments": [ "Set rail to 1.25V using standard rule" ],
+ "volts": 1.25,
+ "rule_id": "set_voltage_rule"
+}
+
+{
+ "comments": [ "If version register 0x75 contains 1, device is downlevel",
+ "and registers 0x31/0x34 need to be updated." ],
+ "actions": [
+ {
+ "if": {
+ "condition": {
+ "i2c_compare_byte": { "register": "0x75", "value": "0x01" }
+ },
+ "then": [
+ { "i2c_write_byte": { "register": "0x31", "value": "0xDB" } },
+ { "i2c_write_byte": { "register": "0x34", "value": "0x1B" } }
+ ]
+ }
+ }
+ ]
+}
+```
diff --git a/phosphor-regulators/docs/config_file/presence_detection.md b/phosphor-regulators/docs/config_file/presence_detection.md
new file mode 100644
index 0000000..293cb3c
--- /dev/null
+++ b/phosphor-regulators/docs/config_file/presence_detection.md
@@ -0,0 +1,62 @@
+# presence_detection
+
+## Description
+Specifies how to detect whether a device is present.
+
+Some devices are only present in certain system configurations. For example:
+* A regulator is only present when a related processor or memory module is
+ present.
+* A system supports multiple storage backplane types, and the device only
+ exists on one of the backplanes.
+
+Device presence is detected by executing actions, such as
+[compare_presence](compare_presence.md) and [compare_vpd](compare_vpd.md).
+
+Device operations like [configuration](configuration.md) and [sensor
+monitoring](sensor_monitoring.md) will only be performed if the actions
+indicate the device is present.
+
+The actions can be specified in two ways:
+* Use the "rule_id" property to specify a standard rule to run.
+* Use the "actions" property to specify an array of actions that are unique to
+ this device.
+
+The return value of the rule or the last action in the array indicates whether
+the device is present. A return value of true means the device is present;
+false means the device is missing.
+
+Device presence will only be detected once per boot of the system. Presence
+will be determined prior to the first device operation (such as configuration).
+When the system is re-booted, presence will be re-detected. As a result,
+presence detection is not supported for devices that can be removed or added
+(hot-plugged) while the system is booted and running.
+
+## Properties
+| Name | Required | Type | Description |
+| :--- | :------: | :--- | :---------- |
+| comments | no | array of strings | One or more comment lines describing the presence detection. |
+| rule_id | see [notes](#notes) | string | Unique ID of the [rule](rule.md) to execute. |
+| actions | see [notes](#notes) | array of [actions](action.md) | One or more actions to execute. |
+
+### Notes
+* You must specify either "rule_id" or "actions".
+
+## Examples
+```
+{
+ "comments": [ "Regulator is only present on the FooBar backplane" ],
+ "rule_id": "is_foobar_backplane_installed_rule"
+}
+
+{
+ "comments": [ "Regulator is only present when CPU 3 is present" ],
+ "actions": [
+ {
+ "compare_presence": {
+ "fru": "/system/chassis/motherboard/cpu3",
+ "value": true
+ }
+ }
+ ]
+}
+```
diff --git a/phosphor-regulators/docs/config_file/sensor_monitoring.md b/phosphor-regulators/docs/config_file/sensor_monitoring.md
new file mode 100644
index 0000000..4fa18df
--- /dev/null
+++ b/phosphor-regulators/docs/config_file/sensor_monitoring.md
@@ -0,0 +1,53 @@
+# sensor_monitoring
+
+## Description
+Defines how to read the sensors for a voltage rail, such as voltage output,
+current output, and temperature. Sensor values are measured, actual values
+rather than target values.
+
+Sensors will be read once per second. The sensor values will be stored on
+D-Bus on the BMC, making them available to external interfaces like Redfish.
+
+The [pmbus_read_sensor](pmbus_read_sensor.md) action is used to read one
+sensor. To read multiple sensors, multiple "pmbus_read_sensor" actions need to
+be executed.
+
+The "pmbus_read_sensor" actions can be specified in two ways:
+* Use the "rule_id" property to specify a standard rule to run.
+* Use the "actions" property to specify an array of actions that are unique to
+ this device.
+
+## Properties
+| Name | Required | Type | Description |
+| :--- | :------: | :--- | :---------- |
+| comments | no | array of strings | One or more comment lines describing the sensor monitoring. |
+| rule_id | see [notes](#notes) | string | Unique ID of the [rule](rule.md) to execute. |
+| actions | see [notes](#notes) | array of [actions](action.md) | One or more actions to execute. |
+
+### Notes
+* You must specify either "rule_id" or "actions".
+
+## Examples
+```
+{
+ "comments": [ "Read all sensors supported by the IR35221 regulator" ],
+ "rule_id": "read_ir35221_sensors_rule"
+}
+
+{
+ "comments": [ "Only read sensors if version register 0x75 contains 2.",
+ "Earlier versions produced invalid sensor values." ],
+ "actions": [
+ {
+ "if": {
+ "condition": {
+ "i2c_compare_byte": { "register": "0x75", "value": "0x02" }
+ },
+ "then": [
+ { "run_rule": "read_sensors_rule" }
+ ]
+ }
+ }
+ ]
+}
+```