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