regs: Enhance multiple chassis documentation
Enhance the multiple chassis documentation for the phosphor-regulators
application.
Some of the documented changes are not yet implemented in C++. Future
commits will implement these changes.
Change-Id: I64a5d3f49c6ad0aa66d39631735dab8a7486612f
Signed-off-by: Shawn McCarney <shawnmm@us.ibm.com>
diff --git a/phosphor-regulators/docs/README.md b/phosphor-regulators/docs/README.md
index 24c32d7..610ca13 100644
--- a/phosphor-regulators/docs/README.md
+++ b/phosphor-regulators/docs/README.md
@@ -11,11 +11,17 @@
[`phosphor-power-sequencer`](../../phosphor-power-sequencer/docs/README.md)
application.
+**Note:** Many changes have been made to this documentation to define
+enhancements to the multiple chassis support. These enhancements are not yet
+implemented in this application. The enhancements are also dependent on the
+planned new `phosphor-chassis-power` application. This disclaimer will be
+removed when this support is fully implemented.
+
## Application
`phosphor-regulators` is a single-threaded C++ executable. It is a 'daemon'
process that runs continually. The application is launched by systemd when the
-BMC reaches the Ready state and before the chassis is powered on.
+BMC reaches the Ready state and before the system is powered on.
The application is driven by a system-specific JSON configuration file. The JSON
file is found and parsed at runtime. The parsing process creates a collection of
@@ -56,6 +62,14 @@
See the [configuration file documentation](docs/config_file/README.md) for
information on the file format, validation tool, and installation directories.
+## Multiple chassis systems
+
+A BMC-based system can contain one or more chassis. A chassis is typically a
+physical enclosure that contains system components such as CPUs, fans, power
+supplies, and PCIe cards.
+
+See [Multiple Chassis](multiple_chassis.md) for more information.
+
## Testing
Automated test cases exist for most of the code in this application. See
diff --git a/phosphor-regulators/docs/config_file/chassis.md b/phosphor-regulators/docs/config_file/chassis.md
index a995377..2bde4e9 100644
--- a/phosphor-regulators/docs/config_file/chassis.md
+++ b/phosphor-regulators/docs/config_file/chassis.md
@@ -4,9 +4,10 @@
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.
+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 regulators
that need to be configured or monitored.
diff --git a/phosphor-regulators/docs/configuration.md b/phosphor-regulators/docs/configuration.md
index 4a3f310..60f194d 100644
--- a/phosphor-regulators/docs/configuration.md
+++ b/phosphor-regulators/docs/configuration.md
@@ -31,6 +31,18 @@
`phosphor-regulators` will perform the configuration defined in the JSON config
file.
+## Multiple chassis
+
+In a [multiple chassis](multiple_chassis.md) system, `phosphor-regulators` will
+only configure regulators in chassis with the proper status:
+
+- `Present` property is true
+- `Enabled` property is true (if interface exists)
+- `Available` property is true (if interface exists)
+
+See [Chassis Status](../phosphor-power-sequencer/docs/chassis_status.md) for
+more information on these properties.
+
## Error handling
If an error occurs while executing actions to perform configuration:
diff --git a/phosphor-regulators/docs/internal_design.md b/phosphor-regulators/docs/internal_design.md
index b3c96a4..a6fffe3 100644
--- a/phosphor-regulators/docs/internal_design.md
+++ b/phosphor-regulators/docs/internal_design.md
@@ -11,8 +11,7 @@
- Represents the computer system being controlled and monitored by the BMC.
- Contains one or more Chassis objects.
- Chassis
- - Represents an enclosure that can be independently powered off and on by the
- BMC.
+ - Represents a physical enclosure that can be powered on and off 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.
- Contains one or more Device objects.
diff --git a/phosphor-regulators/docs/monitoring.md b/phosphor-regulators/docs/monitoring.md
index aa17dfe..6efcfcb 100644
--- a/phosphor-regulators/docs/monitoring.md
+++ b/phosphor-regulators/docs/monitoring.md
@@ -40,3 +40,15 @@
`phosphor-regulators` will stop performing the monitoring defined in the JSON
config file.
+
+## Multiple chassis
+
+In a [multiple chassis](multiple_chassis.md) system, `phosphor-regulators` will
+only monitor regulators in chassis with the proper status:
+
+- `Present` property is true
+- `pgood` property is 1
+- `Available` property is true (if interface exists)
+
+See [Chassis Status](../phosphor-power-sequencer/docs/chassis_status.md) for
+more information on these properties.
diff --git a/phosphor-regulators/docs/multiple_chassis.md b/phosphor-regulators/docs/multiple_chassis.md
new file mode 100644
index 0000000..e7387d7
--- /dev/null
+++ b/phosphor-regulators/docs/multiple_chassis.md
@@ -0,0 +1,61 @@
+# Multiple Chassis
+
+## Overview
+
+A BMC-based system can contain one or more chassis. A chassis is 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.
+
+For the `phosphor-regulators` application, the term "single chassis system"
+means the system type has a maximum configuration of one chassis. If the system
+type has a maximum configuration of multiple chassis, then it is considered a
+"multiple chassis system" even if the current system only contains one chassis.
+
+`phosphor-regulators` only supports powering on and off the entire system. It
+does not support powering on/off individual chassis independent of the rest of
+the system.
+
+## Defining the chassis in a system
+
+The [JSON configuration file](config_file/README.md) contains an array of one or
+more [chassis](config_file/chassis.md) objects. Each chassis object corresponds
+to a physical chassis in the system.
+
+## Differences between single and multiple chassis systems
+
+### System and chassis power state
+
+In a single chassis system, the system and chassis power state are identical.
+Both are either on or off.
+
+In a multiple chassis system, each chassis has its own power state. Even if the
+system is on, an individual chassis may be off. This can occur if that chassis
+does not have input power or has a critical hardware problem.
+
+See [Chassis Status](../phosphor-power-sequencer/docs/chassis_status.md) for
+more information.
+
+### Configuration
+
+In a single chassis system, regulator configuration is always performed on the
+chassis.
+
+In a multiple chassis system, regulator configuration will only be performed on
+chassis with the proper status. For example, a chassis that is missing or has no
+input power cannot be configured.
+
+See [Regulator Configuration](configuration.md) for more information.
+
+### Monitoring
+
+In a single chassis system, regulator monitoring is always performed on the
+chassis.
+
+In a multiple chassis system, regulator monitoring will only be performed on
+chassis with the proper status. For example, a chassis that is missing or has no
+input power cannot be monitored.
+
+See [Regulator Monitoring](monitoring.md) for more information.
diff --git a/phosphor-regulators/docs/sensor_monitoring.md b/phosphor-regulators/docs/sensor_monitoring.md
index 123f59d..8a5f3fa 100644
--- a/phosphor-regulators/docs/sensor_monitoring.md
+++ b/phosphor-regulators/docs/sensor_monitoring.md
@@ -40,6 +40,8 @@
- The regulator has been removed from the system (no longer present).
- The regulator was replaced, and the new regulator supports a different set of
sensors values. For example, temperature_peak is no longer provided.
+- The chassis containing the regulator has an incorrect status, such as missing
+ or no input power.
When regulator monitoring is disabled, the following changes will be made to all
of the D-Bus sensor objects: