docs:presence: Configuration content and syntax
Fill in fan presence JSON configuration content and syntax documentation
for each attribute available in configuring how a fan is detected to be
present or not.
Signed-off-by: Matthew Barth <msbarth@us.ibm.com>
Change-Id: Ie137031b76d956a352967339cd5553d1179bcfa5
diff --git a/docs/presence/README.md b/docs/presence/README.md
index 96a71d5..279041b 100644
--- a/docs/presence/README.md
+++ b/docs/presence/README.md
@@ -107,16 +107,86 @@
### Structure
-TBD
+The config file consists of an array of fan objects that define how their
+presence is detected and the policy used to update its present state within
+inventory.
+```
+[
+ {
+ "name": "fan0",
+ "path": "/system/chassis/motherboard/fan0",
+ "methods": [
+ {
+ "type": ...
+ },
+ .
+ .
+ .
+ ],
+ "rpolicy": {
+ "type": ...
+ }
+ },
+ .
+ .
+ .
+]
+```
### Syntax
-TBD
+Fan object attributes: **(Required unless otherwise noted)**
+* [name](name.md)
+* [path](path.md)
+* [methods](methods.md)
+* [rpolicy](rpolicy.md)
### Comments
-TBD
+The JSON data format does not support comments. However, an optional `comments`
+attribute name can be used to annotate any specific entry of the JSON
+configuration. It is suggested that the value of this `comments` attribute be
+an array of strings for comments containing line breaks. All `comments` objects
+are ignored when the JSON configuration is processed.
+***Note: Only 1 `comments` object can exist at any given 'layer' of the
+configuration hierarchy***
+
+Example:
+```
+[
+ {
+ "comments": [
+ "First fan in the system",
+ "Uses two methods of presence detection"
+ ],
+ "name": "fan0",
+ "path": "/system/chassis/motherboard/fan0",
+ "methods": [
+ {
+ "comments": "Use GPIO for presence detection",
+ "type": "gpio",
+ .
+ .
+ .
+ },
+ {
+ "comments": "Also use the tach for presence detection",
+ "type": "tach",
+ .
+ .
+ .
+ }
+ ],
+ "rpolicy": {
+ "type": ...
+ }
+ },
+ .
+ .
+ .
+]
+```
## Validation
diff --git a/docs/presence/methods.md b/docs/presence/methods.md
new file mode 100644
index 0000000..529279d
--- /dev/null
+++ b/docs/presence/methods.md
@@ -0,0 +1,56 @@
+# methods
+
+## Description
+An array of method objects used to detect the fan's present state. Each
+supported method requires its own set of attributes to be provided.
+
+## Attribute Value(s)
+Method `type`:
+* ["tach"](#tach)
+* ["gpio"](#gpio)
+
+### "tach"
+Requires an array of `sensors` of each fan tach D-Bus sensor name to be used to
+determine fan presence. This is the name of the fan tach sensor located under
+the `/xyz/openbmc_project/sensors/fan_tach/` D-Bus path.
+
+```
+"type": "tach",
+"sensors": [
+ "fan0_0"
+]
+```
+
+### "gpio"
+Detects fans with dedicated GPIOs using Linux
+[gpio-keys](https://www.kernel.org/doc/Documentation/devicetree/bindings/input/gpio-keys.txt)
+device tree bindings, where the event number is provided via the `key`
+attribute.
+
+```
+"type": "gpio",
+"key": 1,
+"physpath": "/sys/devices/platform/ahb/ahb:apb/ahb:apb:bus@1e78a000/1e78a000.i2c-bus/i2c-1/1-0001",
+"devpath": "/dev/input/by-path/platform-gpio-keys-polled-event"
+```
+
+## Example
+<pre><code>
+[
+ {
+ "name": "fan0",
+ "path": "/system/chassis/motherboard/fan0",
+ <b><i>"methods": [
+ {
+ "type": "tach",
+ "sensors": [
+ "fan0_0"
+ ]
+ }
+ ]</i></b>,
+ "rpolicy": {
+ "type": "anyof"
+ }"
+ }
+]
+</code></pre>
diff --git a/docs/presence/name.md b/docs/presence/name.md
new file mode 100644
index 0000000..b09b4b1
--- /dev/null
+++ b/docs/presence/name.md
@@ -0,0 +1,28 @@
+# name
+
+## Description
+A unique identifying name for the fan.
+
+## Attribute Value(s)
+string
+
+## Example
+<pre><code>
+[
+ {
+ <b><i>"name": "fan0"</i></b>,
+ "path": "/system/chassis/motherboard/fan0",
+ "methods": [
+ {
+ "type": "tach",
+ "sensors": [
+ "fan0_0"
+ ]
+ }
+ ],
+ "rpolicy": {
+ "type": "anyof"
+ }"
+ }
+]
+</code></pre>
diff --git a/docs/presence/path.md b/docs/presence/path.md
new file mode 100644
index 0000000..9012c87
--- /dev/null
+++ b/docs/presence/path.md
@@ -0,0 +1,31 @@
+# path
+
+## Description
+The relative path under inventory where the fan's inventory object exists on
+D-Bus. Inventory's base path is `/xyz/openbmc_project/inventory` resulting in
+the fan's inventory object path being the base path plus what's given here.
+i.e.) `/xyz/openbmc_project/inventory/system/chassis/motherboard/fan0`
+
+## Attribute Value(s)
+string
+
+## Example
+<pre><code>
+[
+ {
+ "name": "fan0",
+ <b><i>"path": "/system/chassis/motherboard/fan0"</i></b>,
+ "methods": [
+ {
+ "type": "tach",
+ "sensors": [
+ "fan0_0"
+ ]
+ }
+ ],
+ "rpolicy": {
+ "type": "anyof"
+ }"
+ }
+]
+</code></pre>
diff --git a/docs/presence/rpolicy.md b/docs/presence/rpolicy.md
new file mode 100644
index 0000000..47fd9af
--- /dev/null
+++ b/docs/presence/rpolicy.md
@@ -0,0 +1,49 @@
+# rpolicy
+
+## Description
+The type of redundancy policy to use against the methods of presence detection.
+When there are more than one method of detecting a fan, the policy in which to
+use those methods can be configured based on system expectations.
+
+## Attribute Value(s)
+Policy `type`:
+* ["anyof"](#anyof)
+* ["fallback"](#fallback)
+
+### "anyof"
+A policy where if any method of fan presence detection denotes the fan is
+present, results in the fan being marked present. All methods of detection must
+denote the fan as missing to have a fan be not present.
+
+```
+"type": "anyof"
+```
+
+### "fallback"
+A policy to use the first method of fan presence detection and then use the
+next method only when the first method denotes the fan is missing.
+
+```
+"type": "fallback"
+```
+
+## Example
+<pre><code>
+[
+ {
+ "name": "fan0",
+ "path": "/system/chassis/motherboard/fan0",
+ "methods": [
+ {
+ "type": "tach",
+ "sensors": [
+ "fan0_0"
+ ]
+ }
+ ],
+ <b><i>"rpolicy": {
+ "type": "anyof"
+ }"</i></b>
+ }
+]
+</code></pre>