pseq: multi-chassis: Update JSON config file docs
Update the JSON configuration file documentation for multiple chassis
support. Add new JSON elements and properties.
Change-Id: Id99db5a3a7af700377010adb6ee5a12f5e4409d2
Signed-off-by: Shawn McCarney <shawnmm@us.ibm.com>
diff --git a/phosphor-power-sequencer/docs/config_file/README.md b/phosphor-power-sequencer/docs/config_file/README.md
index 3fcde51..e0ff2ec 100644
--- a/phosphor-power-sequencer/docs/config_file/README.md
+++ b/phosphor-power-sequencer/docs/config_file/README.md
@@ -10,16 +10,22 @@
## Overview
-The `phosphor-power-sequencer` configuration file (config file) contains
-information about the power sequencer device within a system. This device is
-responsible for enabling the voltage rails in order and monitoring them for
-pgood faults.
+The `phosphor-power-sequencer` application is controlled by a configuration file
+(config file). The config file contains information about the chassis, power
+sequencer devices, GPIOs, and voltage rails within the system.
-The information in the config file is used to determine which voltage rail
-caused a pgood fault.
+This information is used to power the system on/off, detect
+[pgood faults](../pgood_faults.md), and identify the voltage rail that caused a
+pgood fault.
-The config file is optional. If no file is found, the application will log a
-general error when a pgood fault occurs. No specific rail will be identified.
+The config file is optional. If no file is found, the application will do the
+following:
+
+- Assume this is a single chassis system.
+- Assume the standard [GPIO names](../named_gpios.md) are used to power the
+ system on/off and detect pgood faults.
+- Log a general error if a pgood fault occurs. No specific voltage rail will be
+ identified.
## Data Format
@@ -31,7 +37,7 @@
The config file name is based on the system type that it supports.
A config file is normally system-specific. Each system type usually has a
-different set of voltage rails and GPIOs.
+different set of chassis, power sequencer devices, GPIOs, and voltage rails.
The system type is obtained from a D-Bus Chassis object created by the
[Entity Manager](https://github.com/openbmc/entity-manager) application. The
@@ -67,6 +73,36 @@
The config file contains a single JSON [config_file](config_file.md) object at
the root level. That object contains arrays of other JSON objects.
+### Comments
+
+The JSON data format does not support comments. However, some of the JSON
+objects in the config file provide an optional "comments" property. The value of
+this property is an array of strings. Use this property to annotate the config
+file. The "comments" properties are ignored when the config file is read by the
+`phosphor-power-sequencer` application.
+
+Examples:
+
+```json
+"comments": ["Chassis 2: Standard hardware layout"],
+```
+
+```json
+"comments": ["The first of two UCD90320 power sequencers in the chassis.",
+ "Controls/monitors rails 0-15."]
+```
+
+### Hexadecimal Values
+
+The JSON number data type does not support the hexadecimal format. For this
+reason, properties with hexadecimal values use the string data type.
+
+Example:
+
+```json
+"address": "0x70"
+```
+
## Installation
The config file is installed in the `/usr/share/phosphor-power-sequencer`
diff --git a/phosphor-power-sequencer/docs/config_file/chassis.md b/phosphor-power-sequencer/docs/config_file/chassis.md
new file mode 100644
index 0000000..9e6e149
--- /dev/null
+++ b/phosphor-power-sequencer/docs/config_file/chassis.md
@@ -0,0 +1,80 @@
+# chassis
+
+## Description
+
+A chassis within the system.
+
+Chassis are typically a physical enclosure that contains system components such
+as CPUs, fans, power supplies, and PCIe cards. A chassis can be stand-alone,
+such as a tower or desktop. A chassis can also be designed to be mounted in an
+equipment rack.
+
+A chassis only needs to be defined in the config file if it contains a power
+sequencer device.
+
+### Chassis Templates
+
+In a multiple chassis system, two or more of the chassis may have the same
+hardware design.
+
+A [chassis template](chassis_template.md) can be used to avoid duplicate data.
+
+Specify the "template_id" and "template_variable_values" properties to use a
+chassis template.
+
+## Properties
+
+| Name | Required | Type | Description |
+| :----------------------- | :-----------------: | :------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------- |
+| comments | no | array of strings | One or more comment lines describing this chassis. |
+| number | see [notes](#notes) | number | Chassis number within the system. Chassis numbers start at 1 because chassis 0 represents the entire system. |
+| inventory_path | see [notes](#notes) | string | D-Bus inventory path of the chassis, such as "/xyz/openbmc_project/inventory/system/chassis". |
+| power_sequencers | see [notes](#notes) | array of [power_sequencers](power_sequencer.md) | One or more power sequencer devices within the chassis. |
+| template_id | see [notes](#notes) | string | Unique ID of the [chassis template](chassis_template.md) to use for the contents of this chassis. |
+| template_variable_values | see [notes](#notes) | [template_variable_values](template_variable_values.md) | Chassis-specific values for chassis template variables. |
+
+### Notes
+
+- You must specify exactly one of the following two groups of properties:
+ - "number", "inventory_path", and "power_sequencers"
+ - "template_id" and "template_variable_values"
+
+## Examples
+
+```json
+{
+ "number": 1,
+ "inventory_path": "/xyz/openbmc_project/inventory/system/chassis",
+ "power_sequencers": [
+ {
+ "type": "UCD90320",
+ "i2c_interface": { "bus": 3, "address": "0x11" },
+ "power_control_gpio_name": "power-chassis-control",
+ "power_good_gpio_name": "power-chassis-good",
+ "rails": [
+ {
+ "name": "VDD_CPU0",
+ "page": 11,
+ "check_status_vout": true
+ },
+ {
+ "name": "VCS_CPU1",
+ "presence": "/xyz/openbmc_project/inventory/system/chassis/motherboard/cpu1",
+ "gpio": { "line": 60 }
+ }
+ ]
+ }
+ ]
+}
+```
+
+```json
+{
+ "comments": ["Chassis 2: Standard hardware layout"],
+ "template_id": "standard_chassis_template",
+ "template_variable_values": {
+ "chassis_number": "2",
+ "sequencer_bus_number": "13"
+ }
+}
+```
diff --git a/phosphor-power-sequencer/docs/config_file/chassis_template.md b/phosphor-power-sequencer/docs/config_file/chassis_template.md
new file mode 100644
index 0000000..80b5a16
--- /dev/null
+++ b/phosphor-power-sequencer/docs/config_file/chassis_template.md
@@ -0,0 +1,82 @@
+# chassis_template
+
+## Description
+
+Chassis templates are used to avoid duplicate data.
+
+In a multiple chassis system, two or more of the [chassis](chassis.md) may have
+the same hardware design. The corresponding chassis objects in the config file
+would be almost identical with a few minor property value differences.
+
+A chassis template defines the power sequencers, GPIOs, and voltage rails in a
+chassis. One or more property values in the template contain variables, such as
+`${chassis_number}`, to support chassis-specific values.
+
+Multiple chassis can use the template rather than duplicating the information.
+The individual chassis specify values for the template variables, such as
+setting `${chassis_number}` to "1" or "2".
+
+### Template Variables
+
+Variables are specified in property values of a chassis template. This includes
+the properties of contained sub-objects like
+[power_sequencers](power_sequencer.md) or [rails](rail.md).
+
+The syntax to specify a variable is `${variable_name}`.
+
+Variable names can only contain letters (A-Z, a-z), numbers (0-9), and
+underscores (\_).
+
+Variables can be specified as the entire property value or as part of the
+property value:
+
+```json
+"number": "${chassis_number}",
+"power_good_gpio_name": "power-chassis${chassis_number}-good",
+```
+
+Variables are supported for the property types string, number, and boolean.
+
+Variables must be specified within a string value (surrounded by double quotes).
+If the property type is number or boolean, the string will be converted to the
+required type.
+
+## Properties
+
+| Name | Required | Type | Description |
+| :--------------- | :------: | :---------------------------------------------- | :------------------------------------------------------------------------------------------------------------ |
+| comments | no | array of strings | One or more comment lines describing this chassis template. |
+| id | yes | string | Unique ID for this chassis template. Can only contain letters (A-Z, a-z), numbers (0-9), and underscore (\_). |
+| number | yes | number | Chassis number within the system. Chassis numbers start at 1 because chassis 0 represents the entire system. |
+| inventory_path | yes | string | D-Bus inventory path of the chassis, such as "/xyz/openbmc_project/inventory/system/chassis". |
+| power_sequencers | yes | array of [power_sequencers](power_sequencer.md) | One or more power sequencer devices within the chassis. |
+
+## Example
+
+```json
+{
+ "id": "standard_chassis_template",
+ "number": "${chassis_number}",
+ "inventory_path": "/xyz/openbmc_project/inventory/system/chassis${chassis_number}",
+ "power_sequencers": [
+ {
+ "type": "UCD90320",
+ "i2c_interface": { "bus": "${sequencer_bus_number}", "address": "0x11" },
+ "power_control_gpio_name": "power-chassis${chassis_number}-control",
+ "power_good_gpio_name": "power-chassis${chassis_number}-good",
+ "rails": [
+ {
+ "name": "VDD_CPU0",
+ "page": 11,
+ "check_status_vout": true
+ },
+ {
+ "name": "VCS_CPU1",
+ "presence": "/xyz/openbmc_project/inventory/system/chassis${chassis_number}/motherboard/cpu1",
+ "gpio": { "line": 60 }
+ }
+ ]
+ }
+ ]
+}
+```
diff --git a/phosphor-power-sequencer/docs/config_file/config_file.md b/phosphor-power-sequencer/docs/config_file/config_file.md
index 611e899..976e373 100644
--- a/phosphor-power-sequencer/docs/config_file/config_file.md
+++ b/phosphor-power-sequencer/docs/config_file/config_file.md
@@ -6,24 +6,55 @@
## Properties
-| Name | Required | Type | Description |
-| :---- | :------: | :------------------------ | :-------------------------------------------------------------------------------------------------------------------------- |
-| rails | yes | array of [rails](rail.md) | One or more voltage rails enabled or monitored by the power sequencer device. The rails must be in power on sequence order. |
+| Name | Required | Type | Description |
+| :---------------- | :------: | :------------------------------------------------ | :----------------------------------------------------------------------------------------------------- |
+| comments | no | array of strings | One or more comment lines describing this file. |
+| chassis_templates | no | array of [chassis_templates](chassis_template.md) | One or more chassis templates. Templates are used to avoid duplicate data in multiple chassis systems. |
+| chassis | yes | array of [chassis](chassis.md) | One or more chassis in the system. |
-## Example
+## Examples
```json
{
- "rails": [
+ "comments": [ "Config file for a FooBar one-chassis system" ],
+ "chassis": [
{
- "name": "VDD_CPU0",
- "page": 11,
- "check_status_vout": true
+ "number": 1,
+ "inventory_path": "/xyz/openbmc_project/inventory/system/chassis",
+ "power_sequencers": [
+ ... details omitted ...
+ ]
+ }
+ ]
+}
+```
+
+```json
+{
+ "chassis_templates": [
+ {
+ "id": "standard_chassis_template",
+ "number": "${chassis_number}",
+ "inventory_path": "/xyz/openbmc_project/inventory/system/chassis${chassis_number}",
+ "power_sequencers": [
+ ... details omitted ...
+ ]
+ }
+ ],
+ "chassis": [
+ {
+ "comments": ["Chassis 1"],
+ "template_id": "standard_chassis_template",
+ "template_variable_values": {
+ "chassis_number": "1"
+ }
},
{
- "name": "VCS_CPU1",
- "presence": "/xyz/openbmc_project/inventory/system/chassis/motherboard/cpu1",
- "gpio": { "line": 60 }
+ "comments": ["Chassis 2"],
+ "template_id": "standard_chassis_template",
+ "template_variable_values": {
+ "chassis_number": "2"
+ }
}
]
}
diff --git a/phosphor-power-sequencer/docs/config_file/i2c_interface.md b/phosphor-power-sequencer/docs/config_file/i2c_interface.md
new file mode 100644
index 0000000..91fa28b
--- /dev/null
+++ b/phosphor-power-sequencer/docs/config_file/i2c_interface.md
@@ -0,0 +1,21 @@
+# i2c_interface
+
+## Description
+
+I2C interface to a 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
+
+```json
+{
+ "bus": 1,
+ "address": "0x70"
+}
+```
diff --git a/phosphor-power-sequencer/docs/config_file/power_sequencer.md b/phosphor-power-sequencer/docs/config_file/power_sequencer.md
new file mode 100644
index 0000000..d57cac7
--- /dev/null
+++ b/phosphor-power-sequencer/docs/config_file/power_sequencer.md
@@ -0,0 +1,55 @@
+# power_sequencer
+
+## Description
+
+A power sequencer device within a chassis.
+
+The power sequencer is responsible for performing the following tasks on a set
+of [voltage rails](rail.md):
+
+- Power the rails on in the correct order
+- Monitor the rails for a [pgood fault](../pgood_faults.md)
+- Power off the rails in the correct order
+
+Note that some voltage rails may automatically power on/off without the power
+sequencer, but they might still be monitored for pgood faults.
+
+[Named GPIOs](../named_gpios.md) are used for the following:
+
+- Power the sequencer on and off
+- Monitor the power good signal from the sequencer. This signal is true when all
+ rails are providing the expected voltage level.
+
+## Properties
+
+| Name | Required | Type | Description |
+| :---------------------- | :------: | :-------------------------------- | :---------------------------------------------------------------------------------------------------------------------------- |
+| comments | no | array of strings | One or more comment lines describing this power sequencer. |
+| type | yes | string | Power sequencer type. Specify one of the following supported types: "UCD90160", "UCD90320". |
+| i2c_interface | yes | [i2c_interface](i2c_interface.md) | I2C interface to this power sequencer. |
+| power_control_gpio_name | yes | string | Named GPIO for turning this power sequencer on and off. |
+| power_good_gpio_name | yes | string | Named GPIO for reading the power good signal from this power sequencer. |
+| rails | yes | array of [rails](rail.md) | One or more voltage rails powered on/off and monitored by this power sequencer. The rails must be in power on sequence order. |
+
+## Example
+
+```json
+{
+ "type": "UCD90320",
+ "i2c_interface": { "bus": 3, "address": "0x11" },
+ "power_control_gpio_name": "power-chassis-control",
+ "power_good_gpio_name": "power-chassis-good",
+ "rails": [
+ {
+ "name": "VDD_CPU0",
+ "page": 11,
+ "check_status_vout": true
+ },
+ {
+ "name": "VCS_CPU1",
+ "presence": "/xyz/openbmc_project/inventory/system/chassis/motherboard/cpu1",
+ "gpio": { "line": 60 }
+ }
+ ]
+}
+```
diff --git a/phosphor-power-sequencer/docs/config_file/rail.md b/phosphor-power-sequencer/docs/config_file/rail.md
index 3130697..5372a60 100644
--- a/phosphor-power-sequencer/docs/config_file/rail.md
+++ b/phosphor-power-sequencer/docs/config_file/rail.md
@@ -2,7 +2,7 @@
## Description
-A voltage rail that is enabled or monitored by the power sequencer device.
+A voltage rail that is enabled or monitored by a power sequencer device.
The "check_status_vout", "compare_voltage_to_limit", and "gpio" properties
specify how to obtain the pgood status of the rail. You can specify more than
diff --git a/phosphor-power-sequencer/docs/config_file/template_variable_values.md b/phosphor-power-sequencer/docs/config_file/template_variable_values.md
new file mode 100644
index 0000000..2e8162a
--- /dev/null
+++ b/phosphor-power-sequencer/docs/config_file/template_variable_values.md
@@ -0,0 +1,45 @@
+# template_variable_values
+
+## Description
+
+Template variable values for a specific chassis.
+
+In a multiple chassis system, two or more of the [chassis](chassis.md) may have
+the same hardware design.
+
+A [chassis template](chassis_template.md) can be used to avoid duplicate data.
+The chassis template defines the power sequencers, GPIOs, and voltage rails in a
+chassis. One or more property values in the template contain variables, such as
+`${chassis_number}`, to support chassis-specific values.
+
+Each chassis using a template must specify values for each template variable.
+For example, the value of `${chassis_number}` is "1" for the first chassis and
+"2" for the second chassis.
+
+All chassis variable values are specified as a string (surrounded by double
+quotes). If the property value where the variable occurs has a different data
+type, such as number, the string will be converted to the required type.
+
+## Properties
+
+| Name | Required | Type | Description |
+| :------------------------------------ | :------: | :----- | :------------------------------------------------------ |
+| Variable 1 name (see [notes](#notes)) | yes | string | Value of the template variable with the specified name. |
+| Variable 2 name (see [notes](#notes)) | yes | string | Value of the template variable with the specified name. |
+| ... | | | |
+| Variable N name (see [notes](#notes)) | yes | string | Value of the template variable with the specified name. |
+
+### Notes
+
+- The variable names are defined in the chassis template, such as
+ "chassis_number" and "sequencer_bus_number".
+- The variable name must be specified without the "$", "{", and "}" characters.
+
+## Example
+
+```json
+{
+ "chassis_number": "2",
+ "sequencer_bus_number": "13"
+}
+```