regulators: Update sensor monitoring documentation
Update the documentation for the pmbus_read_sensor action:
* Improve description of the D-Bus sensor object paths.
* Document how peak/valley sensors are set and when they are cleared.
* Use the simpler term 'Sensor Type' instead of 'Sensor Value Type' to
match the same change in the code.
Update the internal design documentation:
* Update list of interfaces implemented by D-Bus sensors.
* Describe what the D-Bus Value, Functional, and Available properties
will be set to in various scenarios.
* Add brief description of Services class hierarchy.
Signed-off-by: Shawn McCarney <shawnmm@us.ibm.com>
Change-Id: I895bf980300a81bcfbaef975edd41aa7d1d81331
diff --git a/phosphor-regulators/docs/config_file/pmbus_read_sensor.md b/phosphor-regulators/docs/config_file/pmbus_read_sensor.md
index 06c62ac..a0f34a1 100644
--- a/phosphor-regulators/docs/config_file/pmbus_read_sensor.md
+++ b/phosphor-regulators/docs/config_file/pmbus_read_sensor.md
@@ -7,8 +7,8 @@
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:
+### Sensor Type
+Currently the following sensor types are supported:
| Type | Description |
| :--- | :---------- |
@@ -23,9 +23,9 @@
| 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.
+* Some regulators only support a subset of these sensor types.
+* Some of these sensor 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:
@@ -53,13 +53,14 @@
D-Bus sensors have an object path with the following format:
```
-/xyz/openbmc_project/sensors/<type>/<label>
+/xyz/openbmc_project/sensors/<namespace>/<sensor_name>
```
-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>`.
+The D-Bus sensors `<namespace>` is the general category of the sensor. The
+following table shows how the sensor type is mapped to a D-Bus sensors
+`<namespace>`.
-| Sensor Value Type | D-Bus `<type>` |
+| Sensor Type | D-Bus `<namespace>` |
| :---------------- | :------------- |
| iout | current |
| iout_peak | current |
@@ -71,18 +72,26 @@
| 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:
+The D-Bus `<sensor_name>` must be unique across the entire system. It will be
+set to the following:
```
-<rail_id>_<sensor_value_type>
+<rail_id>_<sensor_type>
```
For example, if sensor monitoring for rail "vdd0" reads a "vout_peak" sensor,
-the resulting D-Bus `<label>` will be "vdd0_vout_peak".
+the resulting D-Bus `<sensor_name>` will be "vdd0_vout_peak".
+
+Peak and valley sensor values are calculated internally by the regulator since
+it can sample values very frequently and catch transient events. When these
+peak/valley values are read over PMBus, the regulator will often clear its
+internal value and start calculating a new peak/valley. To avoid losing
+information, the D-Bus sensor will contain the highest peak/lowest valley value
+that has been read since the system was powered on. When the system is powered
+off, the D-Bus peak/valley sensor values are cleared.
## 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". |
+| type | yes | string | Sensor 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. |
diff --git a/phosphor-regulators/docs/design.md b/phosphor-regulators/docs/design.md
index b4c154c..a9ed1c2 100644
--- a/phosphor-regulators/docs/design.md
+++ b/phosphor-regulators/docs/design.md
@@ -43,6 +43,12 @@
* Contains zero or more Rail objects.
* Rail
* Represents a voltage rail produced by a voltage regulator, such as 1.1V.
+* Services
+ * Abstract base class that provides access to a collection of system services
+ like error logging, journal, vpd, and hardware presence.
+ * The BMCServices child class provides the real implementation.
+ * The MockServices child class provides a mock implementation that can be
+ used in gtest test cases.
## Regulator Configuration
@@ -105,11 +111,16 @@
The sensor values for a Rail (such as iout, vout, and temperature) are read
using [pmbus_read_sensor](config_file/pmbus_read_sensor.md) actions.
-The first time a sensor value is read, a corresponding Sensor object is created
-on D-Bus. The D-Bus object implements the Sensor.Value and OperationalStatus
-interfaces. On subsequent reads, the existing D-Bus Sensor object is updated
+The first time a sensor value is read, a corresponding sensor object is created
+on D-Bus. On subsequent reads, the existing D-Bus sensor object is updated
with the new sensor value.
+The D-Bus sensor object implements the following interfaces:
+* xyz.openbmc_project.Sensor.Value
+* xyz.openbmc_project.State.Decorator.OperationalStatus
+* xyz.openbmc_project.State.Decorator.Availability
+* xyz.openbmc_project.Association.Definitions
+
An existing D-Bus Sensor object is removed from D-Bus if no corresponding
sensor values are read during monitoring. This can occur in the following
cases:
@@ -121,20 +132,20 @@
* The error will be logged. If the same error occurs repeatedly on a Rail, it
will only be logged once per system boot.
* Any remaining actions for the Rail will be skipped.
-* The value of all D-Bus Sensor objects for this Rail will be set to 0.
-* The Functional property of all D-Bus Sensor objects for this Rail will be set
- to false.
-* Sensor monitoring will continue.
+* The following changes will be made to all D-Bus sensor objects for this Rail:
+ * The Value property will be set to NaN.
+ * The Functional property will be set to false.
+* Sensor monitoring will continue with the next Rail or Device.
* The sensors for this Rail will be read again during the next monitoring
cycle.
-If, after an error occurs, a subsequent attempt to read the sensors for a Rail
-is successful:
-* The D-Bus Sensor objects for this Rail will be set to the new sensor values.
-* The Functional property of the D-Bus Sensor objects for this Rail will be set
- to true.
+If a subsequent attempt to read the sensors for the Rail is successful, the
+following changes will be made to the D-Bus sensor objects:
+* The Value property will be set to the new sensor reading.
+* The Functional property will be set to true.
-When regulator monitoring is disabled, the Manager object calls the
-`disableSensors()` method on all the objects representing the system (System,
-Chassis, Device, and Rail). Each D-Bus Sensor object is set to the special
-value NaN to indicate the Sensor is inactive.
+When regulator monitoring is disabled, the following changes will be made to
+all of the D-Bus sensor objects:
+* The Value property will be set to NaN.
+* The Available property will be set to false.
+