Document I2C actions in regulator config file
Created documentation for the phosphor-regulators config file. This
commit contains documentation for the I2C-specific actions.
Signed-off-by: Shawn McCarney <shawnmm@us.ibm.com>
Change-Id: I702b4b37717159f61334c61183e5b1978d5a8d7a
diff --git a/phosphor-regulators/docs/config_file/i2c_compare_bit.md b/phosphor-regulators/docs/config_file/i2c_compare_bit.md
new file mode 100644
index 0000000..ed91317
--- /dev/null
+++ b/phosphor-regulators/docs/config_file/i2c_compare_bit.md
@@ -0,0 +1,28 @@
+# i2c_compare_bit
+
+## Description
+Compares a bit in a device register to a value. Communicates with the device
+directly using the [I2C interface](i2c_interface.md).
+
+## Properties
+| Name | Required | Type | Description |
+| :--- | :------: | :--- | :---------- |
+| register | yes | string | Device register address expressed in hexadecimal. Must be prefixed with 0x and surrounded by double quotes. |
+| position | yes | number | Bit position value from 0-7. Bit 0 is the least significant bit. |
+| value | yes | number | Expected bit value: 0 or 1. |
+
+## Return Value
+Returns true if the register bit contained the expected value, otherwise
+returns false.
+
+## Example
+```
+{
+ "comments": [ "Check if bit 3 is on in register 0xA0" ],
+ "i2c_compare_bit": {
+ "register": "0xA0",
+ "position": 3,
+ "value": 1
+ }
+}
+```
diff --git a/phosphor-regulators/docs/config_file/i2c_compare_byte.md b/phosphor-regulators/docs/config_file/i2c_compare_byte.md
new file mode 100644
index 0000000..bc43886
--- /dev/null
+++ b/phosphor-regulators/docs/config_file/i2c_compare_byte.md
@@ -0,0 +1,37 @@
+# i2c_compare_byte
+
+## Description
+Compares a device register to a byte value. Communicates with the device
+directly using the [I2C interface](i2c_interface.md).
+
+## Properties
+| Name | Required | Type | Description |
+| :--- | :------: | :--- | :---------- |
+| register | yes | string | Device register address expressed in hexadecimal. Must be prefixed with 0x and surrounded by double quotes. |
+| value | yes | string | Expected byte value expressed in hexadecimal. Must be prefixed with 0x and surrounded by double quotes. |
+| mask | no | string | Bit mask expressed in hexadecimal. Must be prefixed with 0x and surrounded by double quotes. Specifies which bits should be compared within the byte value. Only the bits with a value of 1 in the mask will be compared. |
+
+## Return Value
+Returns true if the register contained the expected value, otherwise returns
+false.
+
+## Examples
+```
+{
+ "comments": [ "Check if register 0xA0 contains 0xFF" ],
+ "i2c_compare_byte": {
+ "register": "0xA0",
+ "value": "0xFF"
+ }
+}
+
+{
+ "comments": [ "Check if register 0x82 contains 0x40.",
+ "Ignore the most significant bit." ],
+ "i2c_compare_byte": {
+ "register": "0x82",
+ "value": "0x40",
+ "mask": "0x7F"
+ }
+}
+```
diff --git a/phosphor-regulators/docs/config_file/i2c_compare_bytes.md b/phosphor-regulators/docs/config_file/i2c_compare_bytes.md
new file mode 100644
index 0000000..62f1b33
--- /dev/null
+++ b/phosphor-regulators/docs/config_file/i2c_compare_bytes.md
@@ -0,0 +1,45 @@
+# i2c_compare_bytes
+
+## Description
+Compares device register bytes to an array of expected values. Communicates
+with the device directly using the [I2C interface](i2c_interface.md).
+
+All of the bytes will be read in a single I2C operation.
+
+The bytes must be specified in the same order as they will be received from the
+device. For example, a PMBus device transmits byte values in little-endian
+order (least significant byte first).
+
+## Properties
+| Name | Required | Type | Description |
+| :--- | :------: | :--- | :---------- |
+| register | yes | string | Device register address expressed in hexadecimal. Must be prefixed with 0x and surrounded by double quotes. This is the location of the first byte. |
+| values | yes | array of strings | One or more expected byte values expressed in hexadecimal. Each value must be prefixed with 0x and surrounded by double quotes. |
+| masks | no | array of strings | One or more bit masks expressed in hexadecimal. Each mask must be prefixed with 0x and surrounded by double quotes. The number of bit masks must match the number of expected byte values. Each mask specifies which bits should be compared within the corresponding byte value. Only the bits with a value of 1 in the mask will be compared. |
+
+## Return Value
+Returns true if all the register bytes contained the expected values, otherwise
+returns false.
+
+## Examples
+```
+{
+ "comments": [ "Check if register 0xA0 contains 0xFF01.",
+ "Device returns bytes in big-endian order." ],
+ "i2c_compare_bytes": {
+ "register": "0xA0",
+ "values": [ "0xFF", "0x01" ]
+ }
+}
+
+{
+ "comments": [ "Check if register 0x82 contains 0x7302.",
+ "Device returns bytes in little-endian order.",
+ "Ignore the most significant bit in each byte." ],
+ "i2c_compare_bytes": {
+ "register": "0x82",
+ "values": [ "0x02", "0x73" ],
+ "masks": [ "0x7F", "0x7F" ]
+ }
+}
+```
diff --git a/phosphor-regulators/docs/config_file/i2c_write_bit.md b/phosphor-regulators/docs/config_file/i2c_write_bit.md
new file mode 100644
index 0000000..ae60631
--- /dev/null
+++ b/phosphor-regulators/docs/config_file/i2c_write_bit.md
@@ -0,0 +1,26 @@
+# i2c_write_bit
+
+## Description
+Writes a bit to a device register. Communicates with the device directly using
+the [I2C interface](i2c_interface.md).
+
+## Properties
+| Name | Required | Type | Description |
+| :--- | :------: | :--- | :---------- |
+| register | yes | string | Device register address expressed in hexadecimal. Must be prefixed with 0x and surrounded by double quotes. |
+| position | yes | number | Bit position value from 0-7. Bit 0 is the least significant bit. |
+| value | yes | number | Value to write: 0 or 1. |
+
+## Return Value
+true
+
+## Example
+```
+{
+ "i2c_write_bit": {
+ "register": "0xA0",
+ "position": 3,
+ "value": 0
+ }
+}
+```
diff --git a/phosphor-regulators/docs/config_file/i2c_write_byte.md b/phosphor-regulators/docs/config_file/i2c_write_byte.md
new file mode 100644
index 0000000..90254cd
--- /dev/null
+++ b/phosphor-regulators/docs/config_file/i2c_write_byte.md
@@ -0,0 +1,25 @@
+# i2c_write_byte
+
+## Description
+Writes a byte to a device register. Communicates with the device directly
+using the [I2C interface](i2c_interface.md).
+
+## Properties
+| Name | Required | Type | Description |
+| :--- | :------: | :--- | :---------- |
+| register | yes | string | Device register address expressed in hexadecimal. Must be prefixed with 0x and surrounded by double quotes. |
+| value | yes | string | Byte value to write expressed in hexadecimal. Must be prefixed with 0x and surrounded by double quotes. |
+| mask | no | string | Bit mask expressed in hexadecimal. Must be prefixed with 0x and surrounded by double quotes. Specifies which bits to write within the byte value. Only the bits with a value of 1 in the mask will be written. |
+
+## Return Value
+true
+
+## Example
+```
+{
+ "i2c_write_byte": {
+ "register": "0x0A",
+ "value": "0xCC"
+ }
+}
+```
diff --git a/phosphor-regulators/docs/config_file/i2c_write_bytes.md b/phosphor-regulators/docs/config_file/i2c_write_bytes.md
new file mode 100644
index 0000000..a6a3cdf
--- /dev/null
+++ b/phosphor-regulators/docs/config_file/i2c_write_bytes.md
@@ -0,0 +1,44 @@
+# i2c_write_bytes
+
+## Description
+Writes bytes to a device register. Communicates with the device directly using
+the [I2C interface](i2c_interface.md).
+
+All of the bytes will be written in a single I2C operation.
+
+The bytes must be specified in the order required by the device. For example,
+a PMBus device requires byte values to be written in little-endian order (least
+significant byte first).
+
+## Properties
+| Name | Required | Type | Description |
+| :--- | :------: | :--- | :---------- |
+| register | yes | string | Device register address expressed in hexadecimal. Must be prefixed with 0x and surrounded by double quotes. This is the location of the first byte. |
+| values | yes | array of strings | One or more byte values to write expressed in hexadecimal. Each value must be prefixed with 0x and surrounded by double quotes. |
+| masks | no | array of strings | One or more bit masks expressed in hexadecimal. Each mask must be prefixed with 0x and surrounded by double quotes. The number of bit masks must match the number of byte values to write. Each mask specifies which bits to write within the corresponding byte value. Only the bits with a value of 1 in the mask will be written. |
+
+## Return Value
+true
+
+## Examples
+```
+{
+ "comments": [ "Write 0xFF01 to register 0xA0. Device requires bytes to be",
+ "written in big-endian order." ],
+ "i2c_write_bytes": {
+ "register": "0xA0",
+ "values": [ "0xFF", "0x01" ]
+ }
+}
+
+{
+ "comments": [ "Write 0x7302 to register 0x82. Device requires bytes to be",
+ "written in little-endian order. Do not write the most",
+ "significant bit in each byte because the bit is reserved." ],
+ "i2c_write_bytes": {
+ "register": "0x82",
+ "values": [ "0x02", "0x73" ],
+ "masks": [ "0x7F", "0x7F" ]
+ }
+}
+```