docs: Initial config details for each fan app
Created initial README.md files for each fan app to outline the details
and the framework of their configuration file(s). This was placed in a
`docs` directory instead of each app's directory as the intention is to
have a `src` directory containing all the apps in the future. Additional
details to these READMEs will be added as each fan app solidifies on its
JSON configuration structure and usage.
*Note: A future commit will add all the details to fan presence's README
as the majority of its JSON configuration framework is complete.
*Note: A follow-on commit to this will create a fan monitor JSON
configuration example.
Signed-off-by: Matthew Barth <msbarth@us.ibm.com>
Change-Id: If80a7567fb7a121e8e7dfee3eb0842a6931ecb6b
diff --git a/.gitignore b/.gitignore
index 274e450..a3dc332 100644
--- a/.gitignore
+++ b/.gitignore
@@ -8,6 +8,7 @@
autom4te.cache*
compile
config.*
+!config.json
configure
depcomp
install-sh
diff --git a/docs/control/README.md b/docs/control/README.md
new file mode 100644
index 0000000..ad87c2e
--- /dev/null
+++ b/docs/control/README.md
@@ -0,0 +1,158 @@
+# Fan Control Configuration File
+
+## Table of Contents
+* [Overview](#overview)
+* [Data Format](#data-format)
+* [Example](#example)
+* [System Config Location](#system-config-location)
+* [Contents](#contents)
+* [Validation](#validation)
+* [Firmware Updates](#firmware-updates)
+* [Loading and Reloading](#loading-and-reloading)
+
+
+## Overview
+
+The `phosphor-fan-control` application is comprised of as set of configuration
+files (config files) that constructs the algorithm in which fans are controlled
+within a machine.
+
+
+## Data Format
+
+The config file is written using the [JSON (JavaScript Object
+Notation)](https://www.json.org/) data format and can be created using a text
+editor.
+
+
+## Example
+
+TBD
+
+
+## System Config Location
+
+The config file names are:
+* `manager.json`
+* `profiles.json`
+* `fans.json`
+* `zones.json`
+* `groups.json`
+* `events.json`
+
+### Supported Directory
+
+`/usr/share/phosphor-fan-presence/control/`
+
+The supported version of the config files are installed under this read-only
+directory location as part of the firmware image install. This is where the
+config files will be loaded from when no corresponding override config file
+exists.
+
+#### Default Location
+
+Where a single set of config files for 1-or-more system types can be used,
+the config files can be located at the base of the supported directory.
+
+i.e.)
+`/usr/share/phosphor-fan-presence/control/manager.json`
+`/usr/share/phosphor-fan-presence/control/profiles.json`
+`/usr/share/phosphor-fan-presence/control/fans.json`
+`/usr/share/phosphor-fan-presence/control/zones.json`
+`/usr/share/phosphor-fan-presence/control/groups.json`
+`/usr/share/phosphor-fan-presence/control/events.json`
+
+#### Compatible System Type Location
+
+The config files location can also be based on a system type. This is necessary
+where more than one type of machine is supported in a single BMC firmware image
+and those system types can not share any one common config file.
+
+A system type sub-directory can be obtained from the `IBMCompatibleSystem`
+D-Bus interface's `Names` property. The `Names` property contains a list of one
+or more compatible system types, ordered from most specific to the most general.
+
+Example:
+* `ibm,rainier-2u`
+* `ibm,rainier`
+
+The `phosphor-fan-control` application then traverses the supported
+directory, appending each compatible system type entry as a sub-directory from
+most specific to most general on each config file until it is found.
+
+Example: TBD
+
+
+If any required config file is not found and the machine is powered on,
+an error is logged and `phosphor-fan-control` application terminates preventing
+the machine from successfully powering on.
+
+### Override Directory
+
+`/etc/phosphor-fan-presence/control/`
+
+A different version of each of the config files can be loaded by placing it
+into this writable directory location. This avoids the need to build and
+install a new firmware image on the BMC when changing any part of the
+configuration, such as for testing purposes.
+
+The override directory may not exist on the BMC, therefore to be able to use
+any number of overriding config files it must be created using the following
+command:
+
+`mkdir -p /etc/phosphor-fan-presence/control`
+
+### Search Order
+
+The `phosphor-fan-control` application will search for each config file at
+the directory locations in the following order:
+1. Override directory
+2. Supported directory
+ * Default location
+ * Compatible System Type location
+
+
+## Contents
+
+### Structure
+
+TBD
+
+### Syntax
+
+TBD
+
+### Comments
+
+TBD
+
+
+## Validation
+
+TBD
+
+
+## Firmware Updates
+
+When a new firmware image is installed on the BMC, it will update the config
+file in the standard directory.
+
+The override directory will **not** be modified by a firmware update. If a
+config file exists in the override directory, it will continue to be used as
+the fan presence configuration instead of the config file located under the
+appropriate location within the supported directory.
+
+
+## Loading and Reloading
+
+The config files are loaded when the `phosphor-fan-control` application
+starts.
+
+To force the application to reload the config files, use the following command
+on the BMC:
+
+`systemctl kill -s HUP phosphor-fan-control@0.service`
+
+To confirm which config files were loaded, use the following command on the BMC:
+
+`journalctl -u phosphor-fan-control@0.service | grep Loading`
diff --git a/docs/monitor/README.md b/docs/monitor/README.md
new file mode 100644
index 0000000..acd3015
--- /dev/null
+++ b/docs/monitor/README.md
@@ -0,0 +1,151 @@
+# Fan Monitor Configuration File
+
+## Table of Contents
+* [Overview](#overview)
+* [Data Format](#data-format)
+* [Example](#example)
+* [System Config Location](#system-config-location)
+* [Contents](#contents)
+* [Validation](#validation)
+* [Firmware Updates](#firmware-updates)
+* [Loading and Reloading](#loading-and-reloading)
+
+
+## Overview
+
+The `phosphor-fan-monitor` application is controlled by a configuration
+file (config file) to manage the `Functional` property's state on the
+`xyz.openbmc_project.State.Decorator.OperationalStatus` interface for fan
+inventory objects. The config file defines the method to use in determining the
+functional state and the logging of errors for each fan within a machine. It
+also provides the ability to adjust the determination of a fan being
+non-functional due to fan hardware limitations.
+
+
+## Data Format
+
+The config file is written using the [JSON (JavaScript Object
+Notation)](https://www.json.org/) data format and can be created using a text
+editor.
+
+
+## Example
+
+See [config.json](../../monitor/example/config.json).
+
+
+## System Config Location
+
+The config file name is `config.json`.
+
+### Supported Directory
+
+`/usr/share/phosphor-fan-presence/monitor/`
+
+The supported version of the config file is installed under this read-only
+directory location as part of the firmware image install. This is where the
+config file will be loaded from when no overriding config file exists.
+
+#### Default Location
+
+Where a single config file for 1-or-more system types can be used,
+the config file can be located at the base of the supported directory.
+
+i.e.) `/usr/share/phosphor-fan-presence/monitor/config.json`
+
+#### Compatible System Type Location
+
+The config file location can also be based on a system type. This is necessary
+where more than one type of machine is supported in a single BMC firmware image
+and those system types can not share a common config file.
+
+A system type sub-directory can be obtained from the `IBMCompatibleSystem`
+D-Bus interface's `Names` property. The `Names` property contains a list of one
+or more compatible system types, ordered from most specific to the most general.
+
+Example:
+* `ibm,rainier-2u`
+* `ibm,rainier`
+
+The `phosphor-fan-monitor` application then traverses the supported
+directory, appending each compatible system type entry as a sub-directory from
+most specific to most general until the config file is found.
+
+Example:
+1. `/usr/share/phosphor-fan-presence/monitor/ibm,rainier-2u/`
+ * (directory/config file does not exist)
+2. `/usr/share/phosphor-fan-presence/monitor/ibm,rainier/config.json`
+ * (config file found)
+
+If a config file is not found and the machine is powered on, an error is logged
+and `phosphor-fan-monitor` application terminates preventing the machine
+from successfully powering on.
+
+### Override Directory
+
+`/etc/phosphor-fan-presence/monitor/`
+
+A different version of the config file can be loaded by placing it into this
+writable directory location. This avoids the need to build and install a new
+firmware image on the BMC when changing the configuration, such as for testing
+purposes.
+
+The override directory may not exist on the BMC, therefore to be able to use
+an overriding config file it must be created using the following command:
+
+`mkdir -p /etc/phosphor-fan-presence/monitor`
+
+### Search Order
+
+The `phosphor-fan-monitor` application will search for the config file at
+the directory locations in the following order:
+1. Override directory
+2. Supported directory
+ * Default location
+ * Compatible System Type location
+
+
+## Contents
+
+### Structure
+
+TBD
+
+### Syntax
+
+TBD
+
+### Comments
+
+TBD
+
+
+## Validation
+
+TBD
+
+
+## Firmware Updates
+
+When a new firmware image is installed on the BMC, it will update the config
+file in the standard directory.
+
+The override directory will **not** be modified by a firmware update. If a
+config file exists in the override directory, it will continue to be used as
+the fan presence configuration instead of the config file located under the
+appropriate location within the supported directory.
+
+
+## Loading and Reloading
+
+The config file is loaded when the `phosphor-fan-monitor` application
+starts.
+
+To force the application to reload the config file, use the following command
+on the BMC:
+
+`systemctl kill -s HUP phosphor-fan-monitor@0.service`
+
+To confirm which config file was loaded, use the following command on the BMC:
+
+`journalctl -u phosphor-fan-monitor@0.service | grep Loading`
diff --git a/docs/presence/README.md b/docs/presence/README.md
new file mode 100644
index 0000000..96a71d5
--- /dev/null
+++ b/docs/presence/README.md
@@ -0,0 +1,149 @@
+# Fan Presence Configuration File
+
+## Table of Contents
+* [Overview](#overview)
+* [Data Format](#data-format)
+* [Example](#example)
+* [System Config Location](#system-config-location)
+* [Contents](#contents)
+* [Validation](#validation)
+* [Firmware Updates](#firmware-updates)
+* [Loading and Reloading](#loading-and-reloading)
+
+
+## Overview
+
+The `phosphor-fan-presence-tach` application is controlled by a configuration
+file (config file) to manage the `Present` property's state on the
+`xyz.openbmc_project.Inventory.Item` interface for fan inventory objects.
+The config file defines the method(s) and policy(s) to use in determining the
+presence of each fan within a machine.
+
+
+## Data Format
+
+The config file is written using the [JSON (JavaScript Object
+Notation)](https://www.json.org/) data format and can be created using a text
+editor.
+
+
+## Example
+
+See [config.json](../../presence/example/config.json).
+
+
+## System Config Location
+
+The config file name is `config.json`.
+
+### Supported Directory
+
+`/usr/share/phosphor-fan-presence/presence/`
+
+The supported version of the config file is installed under this read-only
+directory location as part of the firmware image install. This is where the
+config file will be loaded from when no overriding config file exists.
+
+#### Default Location
+
+Where a single config file for 1-or-more system types can be used,
+the config file can be located at the base of the supported directory.
+
+i.e.) `/usr/share/phosphor-fan-presence/presence/config.json`
+
+#### Compatible System Type Location
+
+The config file location can also be based on a system type. This is necessary
+where more than one type of machine is supported in a single BMC firmware image
+and those system types can not share a common config file.
+
+A system type sub-directory can be obtained from the `IBMCompatibleSystem`
+D-Bus interface's `Names` property. The `Names` property contains a list of one
+or more compatible system types, ordered from most specific to the most general.
+
+Example:
+* `ibm,rainier-2u`
+* `ibm,rainier`
+
+The `phosphor-fan-presence-tach` application then traverses the supported
+directory, appending each compatible system type entry as a sub-directory from
+most specific to most general until the config file is found.
+
+Example:
+1. `/usr/share/phosphor-fan-presence/presence/ibm,rainier-2u/`
+ * (directory/config file does not exist)
+2. `/usr/share/phosphor-fan-presence/presence/ibm,rainier/config.json`
+ * (config file found)
+
+If a config file is not found and the machine is powered on, an error is logged
+and `phosphor-fan-presence-tach` application terminates preventing the machine
+from successfully powering on.
+
+### Override Directory
+
+`/etc/phosphor-fan-presence/presence/`
+
+A different version of the config file can be loaded by placing it into this
+writable directory location. This avoids the need to build and install a new
+firmware image on the BMC when changing the configuration, such as for testing
+purposes.
+
+The override directory may not exist on the BMC, therefore to be able to use
+an overriding config file it must be created using the following command:
+
+`mkdir -p /etc/phosphor-fan-presence/presence`
+
+### Search Order
+
+The `phosphor-fan-presence-tach` application will search for the config file at
+the directory locations in the following order:
+1. Override directory
+2. Supported directory
+ * Default location
+ * Compatible System Type location
+
+
+## Contents
+
+### Structure
+
+TBD
+
+### Syntax
+
+TBD
+
+### Comments
+
+TBD
+
+
+## Validation
+
+TBD
+
+
+## Firmware Updates
+
+When a new firmware image is installed on the BMC, it will update the config
+file in the standard directory.
+
+The override directory will **not** be modified by a firmware update. If a
+config file exists in the override directory, it will continue to be used as
+the fan presence configuration instead of the config file located under the
+appropriate location within the supported directory.
+
+
+## Loading and Reloading
+
+The config file is loaded when the `phosphor-fan-presence-tach` application
+starts.
+
+To force the application to reload the config file, use the following command
+on the BMC:
+
+`systemctl kill -s HUP phosphor-fan-presence-tach@0.service`
+
+To confirm which config file was loaded, use the following command on the BMC:
+
+`journalctl -u phosphor-fan-presence-tach@0.service | grep Loading`
diff --git a/presence/example/example.json b/presence/example/config.json
similarity index 100%
rename from presence/example/example.json
rename to presence/example/config.json