Document PMBus actions in regulator config file
Created documentation for the phosphor-regulators config file. This
commit contains documentation for the PMBus-specific actions.
Signed-off-by: Shawn McCarney <shawnmm@us.ibm.com>
Change-Id: Iec1b8de2b27b8e0ee26cd6ce8204907c6d89a12f
diff --git a/phosphor-regulators/docs/config_file/pmbus_read_sensor.md b/phosphor-regulators/docs/config_file/pmbus_read_sensor.md
new file mode 100644
index 0000000..3a0b451
--- /dev/null
+++ b/phosphor-regulators/docs/config_file/pmbus_read_sensor.md
@@ -0,0 +1,113 @@
+# pmbus_read_sensor
+
+## Description
+Reads one sensor for a PMBus regulator rail. Communicates with the device
+directly using the [I2C interface](i2c_interface.md).
+
+This action should be executed during [sensor_monitoring](sensor_monitoring.md)
+for the rail.
+
+### Sensor Value Type
+Currently the following sensor value types are supported:
+
+| Type | Description |
+| :--- | :---------- |
+| iout | Output current |
+| iout_peak | Highest output current |
+| iout_valley | Lowest output current |
+| pout | Output power |
+| temperature | Temperature |
+| temperature_peak | Highest temperature |
+| vout | Output voltage |
+| vout_peak | Highest output voltage |
+| vout_valley | Lowest output voltage |
+
+Notes:
+* Some regulators only support a subset of these sensor value types.
+* Some of these sensor value types are not part of the PMBus specification and
+ must be obtained by reading from manufacturer-specific commands.
+
+### Data Format
+Currently the following PMBus data formats are supported:
+
+| Format | Description |
+| :----- | :---------- |
+| linear_11 | Linear data format used for values not related to voltage output, such as output current, input voltage, and temperature. Two byte value with an 11-bit, two's complement mantissa and a 5-bit, two's complement exponent. |
+| linear_16 | Linear data format used for values related to voltage output. Two byte (16-bit), unsigned integer that is raised to the power of an exponent. The exponent is not stored within the two bytes. |
+
+### Exponent For "linear_16" Data Format
+The "linear_16" data format requires an exponent value.
+
+If the device supports the PMBus VOUT_MODE command, the exponent value can be
+read from the device.
+
+If VOUT_MODE is not supported by the device, the exponent value must be
+specified using the "exponent" property. The exponent value can normally be
+found in the device documentation (data sheet).
+
+### D-Bus Sensor
+A [D-Bus sensor
+object](https://github.com/openbmc/docs/blob/master/sensor-architecture.md)
+will be created on the BMC to store the sensor value. This makes the sensor
+available to external interfaces like Redfish.
+
+D-Bus sensors have an object path with the following format:
+```
+/xyz/openbmc_project/sensors/<type>/<label>
+```
+
+The D-Bus `<type>` is the hwmon class name. The following table shows how the
+sensor value type is mapped to a D-Bus `<type>`.
+
+| Sensor Value Type | D-Bus `<type>` |
+| :---------------- | :------------- |
+| iout | current |
+| iout_peak | current |
+| iout_valley | current |
+| pout | power |
+| temperature | temperature |
+| temperature_peak | temperature |
+| vout | voltage |
+| vout_peak | voltage |
+| vout_valley | voltage |
+
+The D-Bus `<label>` is the sensor name. It must be unique within the entire
+system. The `<label>` will be set to the following:
+```
+<rail_id>_<sensor_value_type>
+```
+For example, if sensor monitoring for rail "vdd0" reads a "vout_peak" sensor,
+the resulting D-Bus `<label>` will be "vdd0_vout_peak".
+
+## Properties
+| Name | Required | Type | Description |
+| :--- | :------: | :--- | :---------- |
+| type | yes | string | Sensor value type. Specify one of the following: "iout", "iout_peak", "iout_valley", "pout", "temperature", "temperature_peak", "vout", "vout_peak", "vout_valley". |
+| command | yes | string | PMBus command code expressed in hexadecimal. Must be prefixed with 0x and surrounded by double quotes. |
+| format | yes | string | Data format of the sensor value returned by the device. Specify one of the following: "linear_11", "linear_16".
+| exponent | no | number | Exponent value for "linear_16" data format. Can be positive or negative. If not specified, the exponent value will be read from VOUT_MODE. |
+
+## Return Value
+true
+
+## Examples
+```
+{
+ "comments": [ "Read output current from READ_IOUT." ],
+ "pmbus_read_sensor": {
+ "type": "iout",
+ "command": "0x8C",
+ "format": "linear_11"
+ }
+}
+
+{
+ "comments": [ "Read output voltage from READ_VOUT. Specify exponent." ],
+ "pmbus_read_sensor": {
+ "type": "vout",
+ "command": "0x8B",
+ "format": "linear_16",
+ "exponent": -8
+ }
+}
+```
diff --git a/phosphor-regulators/docs/config_file/pmbus_write_vout_command.md b/phosphor-regulators/docs/config_file/pmbus_write_vout_command.md
new file mode 100644
index 0000000..5aa91c5
--- /dev/null
+++ b/phosphor-regulators/docs/config_file/pmbus_write_vout_command.md
@@ -0,0 +1,78 @@
+# pmbus_write_vout_command
+
+## Description
+Writes the value of VOUT_COMMAND to set the output voltage of a PMBus regulator
+rail. Communicates with the device directly using the [I2C
+interface](i2c_interface.md).
+
+This action should be executed during [configuration](configuration.md) for the
+rail.
+
+### Data Format
+The PMBus specification defines four modes/formats for the value of
+VOUT_COMMAND:
+* Linear
+* VID
+* Direct
+* IEEE Half-Precision Floating Point
+
+Currently only the linear format is supported. The decimal value of the
+"volts" property is converted into linear format before being written.
+
+### Exponent For Linear Data Format
+The linear data format requires an exponent value.
+
+If the device supports the PMBus VOUT_MODE command, the exponent value can be
+read from the device.
+
+If VOUT_MODE is not supported by the device, the exponent value must be
+specified using the "exponent" property. The exponent value can normally be
+found in the device documentation (data sheet).
+
+### Write Verification
+If you wish to verify that the specified volts value was successfully written
+to VOUT_COMMAND, specify the "is_verified" property with a value of true.
+
+The value of VOUT_COMMAND will be read from the device after it is written to
+ensure that it contains the expected value. If VOUT_COMMAND contains an
+unexpected value, an error will be logged and no further configuration will be
+performed for this regulator rail.
+
+To perform verification, the device must return all 16 bits of voltage data
+that were written to VOUT_COMMAND. The PMBus specification permits a device to
+have less than 16 bit internal data resolution, resulting in some low order
+bits being zero when read back. However, verification is not supported on
+devices that provide less than 16 bit internal data resolution.
+
+## Properties
+| Name | Required | Type | Description |
+| :--- | :------: | :--- | :---------- |
+| volts | no | number | Volts value to write, expressed as a decimal number. If not specified, the "volts" property from the [configuration](configuration.md) will be used. |
+| format | yes | string | Data format of the value written to VOUT_COMMAND. Currently the only supported format is "linear". |
+| exponent | no | number | Exponent value for linear data format. Can be positive or negative. If not specified, the exponent value will be read from VOUT_MODE. |
+| is_verified | no | boolean (true or false) | If true, the updated value of VOUT_COMMAND is verified by reading it from the device. If false or not specified, the updated value is not verified. |
+
+## Return Value
+true
+
+## Examples
+```
+{
+ "comments": [ "Set output voltage. Get volts value from configuration.",
+ "Get exponent from VOUT_MODE." ],
+ "pmbus_write_vout_command": {
+ "format": "linear"
+ }
+}
+
+{
+ "comments": [ "Set output voltage. Explicitly specify volts and exponent.",
+ "Verify value was successfully written to VOUT_COMMAND." ],
+ "pmbus_write_vout_command": {
+ "volts": 1.03,
+ "format": "linear",
+ "exponent": -8,
+ "is_verified": true
+ }
+}
+```