pseq: Document enhanced JSON config file format
The JSON config file format is being enhanced for the
phosphor-power-sequencer application.
The enhancements are intended to provide the following benefits:
* Generalize the format so it can be used for any power sequencer
device. The current format is intended only for UCD90XXX devices.
* Remove the "pins" array. Move the GPIO pin information to an optional
property of a rail object. This will eliminate some duplication and
make pgood isolation more flexible.
* Change the meaning of the rail order within the array of rails.
* In the current format, the array index implies the PMBus PAGE. This
causes problems because it is impossible to ignore a PAGE that is
not a valid voltage rail. It also does not provide information
on the power on sequence, which is often different than the PAGE
order.
* In the new format, the rails in the array will be in power on
sequence order. The PMBus page will be explicitly defined using
a new property.
* Add rail property that specifies the PMBus PAGE.
* Add rail property that specifies the pgood status should be obtained
using the PMBus STATUS_VOUT command.
* Add rail property that specifies the pgood status should be obtained
by comparing the output voltage (READ_VOUT) to the undervoltage
(VOUT_UV_FAULT_LIMIT) and overvoltage (VOUT_OV_FAULT_LIMIT) limits.
* Add rail property that specifies the pgood status should be obtained
from a GPIO.
Note: This commit contains only the new JSON file format documentation.
Subsequent commits will contain the new C++ implementation and new
versions of the existing JSON files. The current documentation, C++,
and JSON files will be retained and will remain active until all of the
new support has been merged.
Change-Id: I358a885f1675a9dd8f9ae0115e560abb3c0828fe
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
new file mode 100644
index 0000000..a9bb23c
--- /dev/null
+++ b/phosphor-power-sequencer/docs/config_file/README.md
@@ -0,0 +1,68 @@
+# phosphor-power-sequencer Configuration File
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Data Format](#data-format)
+- [Name](#name)
+- [Contents](#contents)
+- [Installation](#installation)
+
+## 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 information in the config file is used to determine which voltage rail
+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.
+
+## Data Format
+
+The config file is a text file in the
+[JSON (JavaScript Object Notation)](https://www.json.org/) data format.
+
+## Name
+
+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.
+
+The system type is obtained from a D-Bus Chassis object created by the
+[Entity Manager](https://github.com/openbmc/entity-manager) application. The
+object must implement the `xyz.openbmc_project.Inventory.Decorator.Compatible`
+interface.
+
+The `Names` property of this interface contains a list of one or more compatible
+system types. The types are ordered from most specific to least specific.
+
+Example:
+
+- `com.ibm.Hardware.Chassis.Model.Rainier4U`
+- `com.ibm.Hardware.Chassis.Model.Rainier`
+
+The `phosphor-power-sequencer` application converts each compatible system type
+into a config file name by adding a `.json` suffix.
+
+Example:
+
+- `com.ibm.Hardware.Chassis.Model.Rainier.json`
+
+The application searches for a config file that exists with one of these file
+names. It searches from most specific to least specific. The first config file
+found, if any, will be used.
+
+## Contents
+
+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.
+
+## Installation
+
+The config file is installed in the `/usr/share/phosphor-power-sequencer`
+directory on the BMC.
diff --git a/phosphor-power-sequencer/docs/config_file/config_file.md b/phosphor-power-sequencer/docs/config_file/config_file.md
new file mode 100644
index 0000000..ebfa28f
--- /dev/null
+++ b/phosphor-power-sequencer/docs/config_file/config_file.md
@@ -0,0 +1,30 @@
+# config_file
+
+## Description
+
+The root (outer-most) object in the configuration file.
+
+## 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. |
+
+## Example
+
+```
+{
+ "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/gpio.md b/phosphor-power-sequencer/docs/config_file/gpio.md
new file mode 100644
index 0000000..a7fd737
--- /dev/null
+++ b/phosphor-power-sequencer/docs/config_file/gpio.md
@@ -0,0 +1,23 @@
+# gpio
+
+## Description
+
+A General Purpose Input/Output (GPIO) that can be read to obtain the pgood
+status of a voltage rail.
+
+GPIO values are read using the libgpiod interface.
+
+## Properties
+
+| Name | Required | Type | Description |
+| :--------- | :------: | :---------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| line | yes | number | The libgpiod line offset of the GPIO. |
+| active_low | no | boolean (true or false) | If true, the GPIO value 0 indicates a true pgood status. If false, the GPIO value 1 indicates a true pgood status. The default value of this property is false. |
+
+## Example
+
+```
+{
+ "line": 60
+}
+```
diff --git a/phosphor-power-sequencer/docs/config_file/rail.md b/phosphor-power-sequencer/docs/config_file/rail.md
new file mode 100644
index 0000000..d369405
--- /dev/null
+++ b/phosphor-power-sequencer/docs/config_file/rail.md
@@ -0,0 +1,43 @@
+# rail
+
+## Description
+
+A voltage rail that is enabled or monitored by the power sequencer device.
+
+The "check_status_vout", "compare_voltage_to_limits", and "gpio" properties
+specify how to obtain the pgood status of the rail. You can specify more than
+one of these properties if necessary.
+
+## Properties
+
+| Name | Required | Type | Description |
+| :------------------------ | :-----------------: | :---------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| name | yes | string | Unique name for the rail. Can only contain letters (A-Z, a-z), numbers (0-9), period (.), and underscore (\_). |
+| presence | no | string | D-Bus inventory path of a system component which must be present in order for the rail to be present. If this property is not specified, the rail is assumed to always be present. |
+| page | see [notes](#notes) | number | PMBus PAGE number of the rail. |
+| check_status_vout | no | boolean (true or false) | If true, determine the pgood status of the rail by checking the value of the PMBus STATUS_VOUT command. If one of the error bits is set, the rail pgood will be considered false. The default value of this property is false. |
+| compare_voltage_to_limits | no | boolean (true or false) | If true, determine the pgood status of the rail by comparing the output voltage (READ_VOUT) to the undervoltage (VOUT_UV_FAULT_LIMIT) and overvoltage (VOUT_OV_FAULT_LIMIT) limits. If the output voltage is beyond those limits, the rail pgood will be considered false. The default value of this property is false. |
+| gpio | no | [gpio](gpio.md) | Determine the pgood status of the rail by reading a GPIO. |
+
+### Notes
+
+- The "page" property is required if the "check_status_vout" or
+ "compare_voltage_to_limits" property is specified.
+
+## Examples
+
+```
+{
+ "name": "VDD_CPU0",
+ "page": 11,
+ "check_status_vout": true
+}
+```
+
+```
+{
+ "name": "VCS_CPU1",
+ "presence": "/xyz/openbmc_project/inventory/system/chassis/motherboard/cpu1",
+ "gpio": { "line": 60 }
+}
+```