control:docs: Add a section on debug
Describe how fanctl dump and fanctl query_dump can be used to help with
debug.
Signed-off-by: Matt Spinler <spinler@us.ibm.com>
Change-Id: Iac9b50685c03b5f030af1f965ca776e1d16f3f81
diff --git a/docs/control/README.md b/docs/control/README.md
index 60dec7b..9e75bb9 100644
--- a/docs/control/README.md
+++ b/docs/control/README.md
@@ -9,6 +9,7 @@
* [Validation](#validation)
* [Firmware Updates](#firmware-updates)
* [Loading and Reloading](#loading-and-reloading)
+* [Debug](#debug)
## Overview
@@ -264,3 +265,7 @@
To confirm which config files were loaded, use the following command on the BMC:
`journalctl -u phosphor-fan-control@0.service | grep Loading`
+
+## Debug
+Fan control maintains internal data structures that can be be dumped at
+runtime. Details [here](debug.md).
diff --git a/docs/control/debug.md b/docs/control/debug.md
new file mode 100644
index 0000000..827afab
--- /dev/null
+++ b/docs/control/debug.md
@@ -0,0 +1,86 @@
+# Fan Control Debug
+
+Fan control's internal data structures can be dumped at runtime using the
+`fanctl dump` command, which triggers fan control to write the structures to a
+`/tmp/fan_control_dump.json` file. That file is a normal JSON file that can be
+viewed, or the `fanctl query_dump` command can be used as a shortcut to just
+print portions of the file.
+
+[This page](fanctl/README.md) has additional information about the fanctl
+command.
+
+## Flight Recorder
+The flight recorder contains interesting events such as each time the zone
+target changes.
+
+It can be printed with:
+```
+fanctl query_dump -s flight_recorder
+```
+
+## Object Cache
+The object cache contains the most recent D-Bus properties of all of the groups
+from the groups.json files. If any of the D-Bus properties had a value of
+`NaN` (not a number), it is deleted from the cache so won't be present.
+
+It can be printed with:
+```
+fanctl query_dump -s objects
+```
+
+One can restrict the output to specific names with `-n` and properties with
+`-p`:
+
+The `-n` option will match on substrings.
+
+Print the full entries of all temp sensors in the cache:
+```
+fanctl query_dump -s objects -n sensors/temperature
+```
+
+Print just the Value properties of all temperature sensors in the cache:
+```
+fanctl query_dump -s objects -n sensors/temperature -p Value
+```
+
+This allows one to do something like find all Functional property values that
+are false:
+
+```
+fanctl query_dump -s objects -p Functional | grep -B 1 false
+```
+
+## Zone Config
+The zone configuration contains values like the current target, current
+floor, and any outstanding floor or target holds.
+
+It can be printed with:
+```
+fanctl query_dump -s zones
+```
+
+## Parameter Values
+Parameters are key/value pairs set and used by actions.
+
+They can be printed with:
+```
+fanctl query_dump -s parameters
+```
+
+## Service Cache
+Fan control maintains a map of objects paths of the group members to the
+services that own them.
+
+It can be printed with:
+```
+fanctl query_dump -s services
+```
+
+## Configured Events
+Fan control can dump a list of all of its configured event names along with
+their group names.
+
+It can be printed with:
+```
+fanctl query_dump -s events
+```