configure.md: updates and clarifications
Signed-off-by: Paul Fertser <fercerpav@gmail.com>
Change-Id: I9fcaa5d7c563c59a9efcf41500db231010a32557
diff --git a/configure.md b/configure.md
index 7c713f8..1d13252 100644
--- a/configure.md
+++ b/configure.md
@@ -2,9 +2,24 @@
A system needs two groups of configurations: zones and sensors.
-## Json Configuration
+They can come either from a dedicated config file or via D-Bus from
+e.g. `entity-manager`.
-The json object should be a dictionary with two keys, `sensors` and `zones`.
+## D-Bus Configuration
+
+If config file does not exist the configuration is obtained from a set of D-Bus
+interfaces. When using `entity-manager` to provide them refer to `Pid`,
+`Pid.Zone` and `Stepwise`
+[schemas](https://github.com/openbmc/entity-manager/tree/master/schemas). The
+key names are not identical to JSON but similar enough to see the
+correspondence.
+
+## JSON Configuration
+
+Default config file path `/usr/share/swampd/config.json` can be overridden by
+using `--conf` command line option.
+
+The JSON object should be a dictionary with two keys, `sensors` and `zones`.
`sensors` is a list of the sensor dictionaries, whereas `zones` is a list of
zones.
@@ -40,9 +55,7 @@
configuration.
The `type` is the type of sensor it is. This influences how its value is
-treated. Supports values are: `fan`, `temp`, and `margin`.
-
-**TODO: Add further details on what the types mean.**
+treated. Supported values are: `fan`, `temp`, and `margin`.
The `readPath` is the path that tells the daemon how to read the value from this
sensor. It is optional, allowing for write-only sensors. If the value is absent
@@ -132,13 +145,14 @@
...
```
-Each zone has its own fields, and a list of PIDs.
+Each zone has its own fields, and a list of controllers.
| field | type | meaning |
| ------------------ | --------- | ----------------------------------------- |
| `id` | `int64_t` | This is a unique identifier for the zone. |
| `minThermalOutput` | `double` | This is the minimum value that should be considered from the thermal outputs. Commonly used as the minimum fan RPM.|
| `failsafePercent` | `double` | If there is a fan PID, it will use this value if the zone goes into fail-safe as the output value written to the fan's sensors.|
+| `pids` | `list of strings` | Fan and thermal controllers used by the zone.|
The `id` field here is used in the d-bus path to talk to the
`xyz.openbmc_project.Control.Mode` interface.
@@ -146,18 +160,26 @@
***TODO:*** Examine how the fan controller always treating its output as a
percentage works for future cases.
-### PIDs
+A zone collects all the setpoints and ceilings from the thermal
+controllers attached to it, selects the maximum setpoint, clamps it by
+the minimum ceiling and `minThermalOutput`; the result is used to
+control fans.
-There are a few PID types: `fan`, `temp`, `margin`, and `stepwise`.
+### Controllers
-The `fan` PID is meant to drive fans. It's expecting to get the maximum RPM
-setpoint value from the owning zone and then drive the fans to that value.
+There are `fan`, `temp`, `margin` (PID), and `stepwise` (discrete steps)
+controllers.
-A `temp` PID is meant to drive the RPM setpoint given an absolute temperature
-value (higher value indicates a warmer temperature).
+The `fan` PID is meant to drive fans or other cooling devices. It's
+expecting to get the setpoint value from the owning zone and then
+drive the fans to that value.
-A `margin` PID is meant to drive the RPM setpoint given a margin value (lower
-value indicates a warmer temperature).
+A `temp` PID is meant to drive the setpoint given an absolute
+temperature value (higher value indicates warmer temperature).
+
+A `margin` PID is meant to drive the setpoint given a margin value
+(lower value indicates warmer temperature, in other words, it's the
+safety margin remaining expressed in degrees Celsius).
The setpoint output from the thermal controllers is called `RPMSetpoint()`
However, it doesn't need to be an RPM value.
@@ -167,6 +189,16 @@
Some PID configurations have fields in common, but may be interpreted
differently.
+When using D-Bus, each configuration can have a list of strings called
+`Profiles`. In this case the controller will be loaded only if at
+least one of them is returned as `Current` from an object implementing
+`xyz.openbmc_project.Control.ThermalMode` interface (which can be
+anywhere on D-Bus). `swampd` will automatically reload full
+configuration whenever `Current` is changed.
+
+D-Bus `Name` attribute is used for indexing in certain cases so should
+be unique for all defined configurations.
+
#### PID Field
If the PID `type` is not `stepwise` then the PID field is defined as follows:
@@ -220,10 +252,6 @@
| `setpoint` | `double` | Presently UNUSED |
| `pid` | `dictionary` | A PID dictionary detailed above. |
-#### type == "temp"
-
-***TODO:*** Add notes for temperature configuration.
-
#### type == "margin"
```
@@ -246,10 +274,25 @@
| `setpoint` | `double` | The setpoint value for the thermal PID. The setpoint for the margin sensors.|
| `pid` | `dictionary` | A PID dictionary detailed above. |
+Each input is normally a temperature difference between some hardware
+threshold and the current state. E.g. a CPU sensor can be reporting
+that it's 20 degrees below the point when it starts thermal
+throttling. So the lower the margin temperature, the higher the
+corresponding absolute value.
+
+Out of all the `inputs` the minimal value is selected and used as an
+input for the PID loop.
+
The output of a `margin` PID loop is that it sets the setpoint value for the
zone. It does this by adding the value to a list of values. The value chosen by
the fan PIDs (in this cascade configuration) is the maximum value.
+#### type == "temp"
+
+Exactly the same as `margin` but all the inputs are supposed to be
+absolute temperatures and so the maximal value is used to feed the PID
+loop.
+
#### type == "stepwise"
***TODO:*** Write up `stepwise` details.