Document rule and action in regulator config file
Created documentation for the phosphor-regulators config file. This
commit contains documentation for the JSON action and rule objects.
Signed-off-by: Shawn McCarney <shawnmm@us.ibm.com>
Change-Id: Idc534ce59928822a6d1d88dadf1b80fdaca32ea9
diff --git a/phosphor-regulators/docs/config_file/action.md b/phosphor-regulators/docs/config_file/action.md
new file mode 100644
index 0000000..f60e8a4
--- /dev/null
+++ b/phosphor-regulators/docs/config_file/action.md
@@ -0,0 +1,57 @@
+# action
+
+## Description
+Action to execute.
+
+Actions are executed to perform the following regulator operations:
+* [presence_detection](presence_detection.md)
+* [configuration](configuration.md)
+* [sensor_monitoring](sensor_monitoring.md)
+
+Many actions read from or write to a hardware device. Initially this is the
+[device](device.md) that contains the regulator operation. However, the device
+can be changed using the [set_device](set_device.md) action.
+
+## Properties
+| Name | Required | Type | Description |
+| :--- | :------: | :--- | :---------- |
+| comments | no | array of strings | One or more comment lines describing this action. |
+| and | see [notes](#notes) | array of actions | Action type [and](and.md). |
+| compare_presence | see [notes](#notes) | [compare_presence](compare_presence.md) | Action type [compare_presence](compare_presence.md). |
+| compare_vpd | see [notes](#notes) | [compare_vpd](compare_vpd.md) | Action type [compare_vpd](compare_vpd.md). |
+| i2c_compare_bit | see [notes](#notes) | [i2c_compare_bit](i2c_compare_bit.md) | Action type [i2c_compare_bit](i2c_compare_bit.md). |
+| i2c_compare_byte | see [notes](#notes) | [i2c_compare_byte](i2c_compare_byte.md) | Action type [i2c_compare_byte](i2c_compare_byte.md). |
+| i2c_compare_bytes | see [notes](#notes) | [i2c_compare_bytes](i2c_compare_bytes.md) | Action type [i2c_compare_bytes](i2c_compare_bytes.md). |
+| i2c_write_bit | see [notes](#notes) | [i2c_write_bit](i2c_write_bit.md) | Action type [i2c_write_bit](i2c_write_bit.md). |
+| i2c_write_byte | see [notes](#notes) | [i2c_write_byte](i2c_write_byte.md) | Action type [i2c_write_byte](i2c_write_byte.md). |
+| i2c_write_bytes | see [notes](#notes) | [i2c_write_bytes](i2c_write_bytes.md) | Action type [i2c_write_bytes](i2c_write_bytes.md). |
+| if | see [notes](#notes) | [if](if.md) | Action type [if](if.md). |
+| not | see [notes](#notes) | action | Action type [not](not.md). |
+| or | see [notes](#notes) | array of actions | Action type [or](or.md). |
+| pmbus_read_sensor | see [notes](#notes) | [pmbus_read_sensor](pmbus_read_sensor.md) | Action type [pmbus_read_sensor](pmbus_read_sensor.md). |
+| pmbus_write_vout_command | see [notes](#notes) | [pmbus_write_vout_command](pmbus_write_vout_command.md) | Action type [pmbus_write_vout_command](pmbus_write_vout_command.md). |
+| run_rule | see [notes](#notes) | string | Action type [run_rule](run_rule.md). |
+| set_device | see [notes](#notes) | string | Action type [set_device](set_device.md). |
+
+### Notes
+* You must specify exactly one action type property, such as "i2c_write_byte"
+ or "run_rule".
+
+## Return Value
+When the action completes, it returns a true or false value. The documentation
+for the specified action type describes what value will be returned.
+
+## Examples
+```
+{
+ "comments": [ "Set frequency to 800kHz" ],
+ "i2c_write_byte": {
+ "register": "0x2C",
+ "value": "0x0F"
+ }
+}
+
+{
+ "run_rule": "set_voltage_rule"
+}
+```
diff --git a/phosphor-regulators/docs/config_file/rule.md b/phosphor-regulators/docs/config_file/rule.md
new file mode 100644
index 0000000..1526432
--- /dev/null
+++ b/phosphor-regulators/docs/config_file/rule.md
@@ -0,0 +1,40 @@
+# rule
+
+## Description
+A rule is a sequence of actions that can be shared by multiple regulators in
+the config file. Rules define a standard way to perform an operation. Rules
+are used to minimize duplication in the config file.
+
+For example, the following action sequences might be sharable using a rule:
+* Actions that set the output voltage of a regulator rail
+* Actions that read all the sensors of a regulator rail
+* Actions that detect down-level hardware using version registers
+
+## Properties
+| Name | Required | Type | Description |
+| :--- | :------: | :--- | :---------- |
+| comments | no | array of strings | One or more comment lines describing this rule. |
+| id | yes | string | Unique ID for this rule. Can only contain letters (A-Z, a-z), numbers (0-9), and underscore (\_). |
+| actions | yes | array of [actions](action.md) | One or more actions to execute. |
+
+## Return Value
+Return value of the last action in the "actions" property.
+
+## Example
+```
+{
+ "comments": [ "Sets output voltage of PAGE 0 of a PMBus regulator" ],
+ "id": "set_page0_voltage_rule",
+ "actions": [
+ { "i2c_write_byte": { "register": "0x00", "value": "0x00" } },
+ { "pmbus_write_vout_command": { "format": "linear" } }
+ ]
+}
+
+... later in the config file ...
+
+"configuration": {
+ "volts": 1.03,
+ "rule_id": "set_page0_voltage_rule"
+}
+```