1# Fan Presence Configuration File
2
3## Table of Contents
4
5- [Overview](#overview)
6- [Data Format](#data-format)
7- [Example](#example)
8- [System Config Location](#system-config-location)
9- [Contents](#contents)
10- [Validation](#validation)
11- [Firmware Updates](#firmware-updates)
12- [Loading and Reloading](#loading-and-reloading)
13
14## Overview
15
16The `phosphor-fan-presence-tach` application is controlled by a configuration
17file (config file) to manage the `Present` property's state on the
18`xyz.openbmc_project.Inventory.Item` interface for fan inventory objects. The
19config file defines the method(s) and policy(s) to use in determining the
20presence of each fan within a machine.
21
22## Data Format
23
24The config file is written using the
25[JSON (JavaScript Object Notation)](https://www.json.org/) data format and can
26be created using a text editor.
27
28## Example
29
30See [config.json](../../presence/example/config.json).
31
32## System Config Location
33
34The config file name is `config.json`.
35
36### Supported Directory
37
38`/usr/share/phosphor-fan-presence/presence/`
39
40The supported version of the config file is installed under this read-only
41directory location as part of the firmware image install. This is where the
42config file will be loaded from when no overriding config file exists.
43
44#### Default Location
45
46Where a single config file for 1-or-more system types can be used, the config
47file can be located at the base of the supported directory.
48
49i.e.) `/usr/share/phosphor-fan-presence/presence/config.json`
50
51#### Compatible System Type Location
52
53The config file location can also be based on a system type. This is necessary
54where more than one type of machine is supported in a single BMC firmware image
55and those system types can not share a common config file.
56
57A system type sub-directory can be obtained from the `IBMCompatibleSystem` D-Bus
58interface's `Names` property. The `Names` property contains a list of one or
59more compatible system types, ordered from most specific to the most general.
60
61Example:
62
63- `ibm,rainier-2u`
64- `ibm,rainier`
65
66The `phosphor-fan-presence-tach` application then traverses the supported
67directory, appending each compatible system type entry as a sub-directory from
68most specific to most general until the config file is found.
69
70Example:
71
721. `/usr/share/phosphor-fan-presence/presence/ibm,rainier-2u/`
73   - (directory/config file does not exist)
742. `/usr/share/phosphor-fan-presence/presence/ibm,rainier/config.json`
75   - (config file found)
76
77If a config file is not found and the machine is powered on, an error is logged
78and `phosphor-fan-presence-tach` application terminates preventing the machine
79from successfully powering on.
80
81### Override Directory
82
83`/etc/phosphor-fan-presence/presence/`
84
85A different version of the config file can be loaded by placing it into this
86writable directory location. This avoids the need to build and install a new
87firmware image on the BMC when changing the configuration, such as for testing
88purposes.
89
90The override directory may not exist on the BMC, therefore to be able to use an
91overriding config file it must be created using the following command:
92
93`mkdir -p /etc/phosphor-fan-presence/presence`
94
95### Search Order
96
97The `phosphor-fan-presence-tach` application will search for the config file at
98the directory locations in the following order:
99
1001. Override directory
1012. Supported directory
102   - Default location
103   - Compatible System Type location
104
105## Contents
106
107### Structure
108
109The config file consists of an array of fan objects that define how their
110presence is detected and the policy used to update its present state within
111inventory.
112
113```
114[
115  {
116    "name": "fan0",
117    "path": "/system/chassis/motherboard/fan0",
118    "methods": [
119      {
120        "type": ...
121      },
122      .
123      .
124      .
125    ],
126    "rpolicy": {
127        "type": ...
128    }
129  },
130  .
131  .
132  .
133]
134```
135
136### Syntax
137
138Fan object attributes: **(Required unless otherwise noted)**
139
140- [name](name.md)
141- [path](path.md)
142- [methods](methods.md)
143- [rpolicy](rpolicy.md)
144- [eeprom](eeprom.md) _optional_
145
146### Comments
147
148The JSON data format does not support comments. However, an optional `comments`
149attribute name can be used to annotate any specific entry of the JSON
150configuration. It is suggested that the value of this `comments` attribute be an
151array of strings for comments containing line breaks. All `comments` objects are
152ignored when the JSON configuration is processed.
153
154**_Note: Only 1 `comments` object can exist at any given 'layer' of the
155configuration hierarchy_**
156
157Example:
158
159```
160[
161  {
162    "comments": [
163      "First fan in the system",
164      "Uses two methods of presence detection"
165    ],
166    "name": "fan0",
167    "path": "/system/chassis/motherboard/fan0",
168    "methods": [
169      {
170        "comments": "Use GPIO for presence detection",
171        "type": "gpio",
172        .
173        .
174        .
175      },
176      {
177        "comments": "Also use the tach for presence detection",
178        "type": "tach",
179        .
180        .
181        .
182      }
183    ],
184    "rpolicy": {
185        "type": ...
186    }
187  },
188  .
189  .
190  .
191]
192```
193
194## Validation
195
196TBD
197
198## Firmware Updates
199
200When a new firmware image is installed on the BMC, it will update the config
201file in the standard directory.
202
203The override directory will **not** be modified by a firmware update. If a
204config file exists in the override directory, it will continue to be used as the
205fan presence configuration instead of the config file located under the
206appropriate location within the supported directory.
207
208## Loading and Reloading
209
210The config file is loaded when the `phosphor-fan-presence-tach` application
211starts.
212
213To force the application to reload the config file, use the following command on
214the BMC:
215
216`systemctl kill -s HUP phosphor-fan-presence-tach@0.service`
217
218To confirm which config file was loaded, use the following command on the BMC:
219
220`journalctl -u phosphor-fan-presence-tach@0.service | grep Loading`
221