Document hardware objects in regulator config file
Added documentation for the phosphor-regulators config file. This
commit contains documentation for the JSON objects that represent the
hardware in the system.
Signed-off-by: Shawn McCarney <shawnmm@us.ibm.com>
Change-Id: Ida8f7e5ce375a7cc7453eb3576aa9b09f4da50ed
diff --git a/phosphor-regulators/docs/config_file/chassis.md b/phosphor-regulators/docs/config_file/chassis.md
new file mode 100644
index 0000000..e3e52d0
--- /dev/null
+++ b/phosphor-regulators/docs/config_file/chassis.md
@@ -0,0 +1,36 @@
+# chassis
+
+## Description
+A chassis within the system.
+
+Chassis are large enclosures 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.
+
+A chassis only needs to be defined in the config file if it contains regulators
+that need to be configured or monitored.
+
+## Properties
+| Name | Required | Type | Description |
+| :--- | :------: | :--- | :---------- |
+| comments | no | array of strings | One or more comment lines describing this chassis. |
+| number | yes | number | Chassis number within the system. Chassis numbers start at 1 because chassis 0 represents the entire system. |
+| devices | no | array of [devices](device.md) | One or more devices within the chassis. The array should contain regulator devices and any related devices required to perform regulator operations. |
+
+## Example
+```
+{
+ "comments": [ "Chassis number 1 containing CPUs and memory" ],
+ "number": 1,
+ "devices": [
+ {
+ "id": "vdd_regulator",
+ ... details omitted ...
+ },
+ {
+ "id": "vio_regulator",
+ ... details omitted ...
+ }
+ ]
+}
+```
diff --git a/phosphor-regulators/docs/config_file/device.md b/phosphor-regulators/docs/config_file/device.md
new file mode 100644
index 0000000..f01c37d
--- /dev/null
+++ b/phosphor-regulators/docs/config_file/device.md
@@ -0,0 +1,44 @@
+# device
+
+## Description
+A hardware device within the chassis.
+
+The following devices should be defined in the config file:
+* Voltage regulators that require configuration or monitoring.
+* Other devices that are required to configure or monitor regulators. For
+ example, an I/O expander may provide necessary information about a regulator.
+
+## Properties
+| Name | Required | Type | Description |
+| :--- | :------: | :--- | :---------- |
+| comments | no | array of strings | One or more comment lines describing this device. |
+| id | yes | string | Unique ID for this device. Can only contain letters (A-Z, a-z), numbers (0-9), and underscore (\_). |
+| is_regulator | yes | boolean (true or false) | Indicates whether this device is a voltage regulator (phase controller). |
+| fru | yes | string | Field-Replaceable Unit (FRU) for this device. Specify the D-Bus inventory path of the FRU. If the device itself is not a FRU, specify the FRU that contains it. |
+| i2c_interface | yes | [i2c_interface](i2c_interface.md) | I2C interface to this device. |
+| presence_detection | no | [presence_detection](presence_detection.md) | Specifies how to detect whether this device is present. If this property is not specified, the device is assumed to always be present. |
+| configuration | no | [configuration](configuration.md) | Specifies configuration changes that should be applied to this device. These changes usually override hardware default settings. The configuration changes are applied during the boot before regulators are enabled. |
+| rails | no | array of [rails](rail.md) | One or more voltage rails produced by this device. This property can only be specified if the "is_regulator" property is true. |
+
+## Example
+```
+{
+ "comments": [ "IR35221 regulator producing the Vdd rail" ],
+ "id": "vdd_regulator",
+ "is_regulator": true,
+ "fru": "/system/chassis/motherboard/regulator2",
+ "i2c_interface": {
+ "bus": 1,
+ "address": "0x70"
+ },
+ "configuration": {
+ "rule_id": "configure_ir35221_rule"
+ },
+ "rails": [
+ {
+ "id": "vdd",
+ ... details omitted ...
+ }
+ ]
+}
+```
diff --git a/phosphor-regulators/docs/config_file/i2c_interface.md b/phosphor-regulators/docs/config_file/i2c_interface.md
new file mode 100644
index 0000000..4f6b3b0
--- /dev/null
+++ b/phosphor-regulators/docs/config_file/i2c_interface.md
@@ -0,0 +1,24 @@
+# i2c_interface
+
+## Description
+I2C interface to a device.
+
+Direct I2C communication to the device will be performed using the [i2c-dev
+API](https://www.kernel.org/doc/Documentation/i2c/dev-interface).
+
+To avoid race conditions and conflicts, no device driver should be bound to the
+device.
+
+## Properties
+| Name | Required | Type | Description |
+| :--- | :------: | :--- | :---------- |
+| bus | yes | number | I2C bus number of the device. The first bus is 0. |
+| address | yes | string | 7-bit I2C address of the device expressed in hexadecimal. Must be prefixed with 0x and surrounded by double quotes. |
+
+## Example
+```
+{
+ "bus": 1,
+ "address": "0x70"
+}
+```
diff --git a/phosphor-regulators/docs/config_file/rail.md b/phosphor-regulators/docs/config_file/rail.md
new file mode 100644
index 0000000..6b8a0b6
--- /dev/null
+++ b/phosphor-regulators/docs/config_file/rail.md
@@ -0,0 +1,33 @@
+# rail
+
+## Description
+A voltage rail produced by a regulator.
+
+Voltage regulators produce one or more rails. Each rail typically provides a
+different output voltage level, such as 1.1V.
+
+On a PMBus regulator with multiple rails, the current rail is selected using
+the PAGE command. Subsequent PMBus commands are sent to that PAGE/rail.
+
+## Properties
+| Name | Required | Type | Description |
+| :--- | :------: | :--- | :---------- |
+| comments | no | array of strings | One or more comment lines describing this rail. |
+| id | yes | string | Unique ID for this rail. Can only contain letters (A-Z, a-z), numbers (0-9), and underscore (\_). |
+| configuration | no | [configuration](configuration.md) | Specifies configuration changes that should be applied to this rail. These changes usually override hardware default settings. The configuration changes are applied during the boot before regulators are enabled. |
+| sensor_monitoring | no | [sensor_monitoring](sensor_monitoring.md) | Specifies how to read the sensors for this rail. |
+
+## Example
+```
+{
+ "comments": [ "Vdd rail on PAGE 0 of the Vdd/Vio regulator" ],
+ "id": "vdd",
+ "configuration": {
+ "volts": 1.1,
+ "rule_id": "set_page0_voltage_rule"
+ },
+ "sensor_monitoring": {
+ "rule_id": "read_ir35221_page0_sensors_rule"
+ }
+}
+```