1# Fan Control 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- [Debug](#debug)
14
15## Overview
16
17The `phosphor-fan-control` application is comprised of as set of configuration
18files (config files) that constructs the algorithm in which fans are controlled
19within a machine.
20
21## Data Format
22
23The config file is written using the
24[JSON (JavaScript Object Notation)](https://www.json.org/) data format and can
25be created using a text editor.
26
27## System Config Location
28
29The config file names are:
30
31- `manager.json`
32- `profiles.json`
33- `fans.json`
34- `zones.json`
35- `groups.json`
36- `events.json`
37
38### Supported Directory
39
40`/usr/share/phosphor-fan-presence/control/`
41
42The supported version of the config files are installed under this read-only
43directory location as part of the firmware image install. This is where the
44config files will be loaded from when no corresponding override config file
45exists.
46
47#### Default Location
48
49Where a single set of config files for 1-or-more system types can be used, the
50config files can be located at the base of the supported directory.
51
52i.e.)
53`/usr/share/phosphor-fan-presence/control/manager.json`
54`/usr/share/phosphor-fan-presence/control/profiles.json`
55`/usr/share/phosphor-fan-presence/control/fans.json`
56`/usr/share/phosphor-fan-presence/control/zones.json`
57`/usr/share/phosphor-fan-presence/control/groups.json`
58`/usr/share/phosphor-fan-presence/control/events.json`
59
60#### Compatible System Type Location
61
62The config files location can also be based on a system type. This is necessary
63where more than one type of machine is supported in a single BMC firmware image
64and those system types can not share any one common config file.
65
66A system type sub-directory can be obtained from the `IBMCompatibleSystem` D-Bus
67interface's `Names` property. The `Names` property contains a list of one or
68more compatible system types, ordered from most specific to the most general.
69
70Example:
71
72- `ibm,rainier-2u`
73- `ibm,rainier`
74
75The `phosphor-fan-control` application then traverses the supported directory,
76appending each compatible system type entry as a sub-directory from most
77specific to most general on each config file until it is found.
78
79Example:
80
811. `/usr/share/phosphor-fan-presence/control/ibm,rainier-2u/`
82   - (directory/config file does not exist)
832. `/usr/share/phosphor-fan-presence/control/ibm,rainier/events.json`
84   - (config file found)
85
86If any required config file is not found and the machine is powered on, an error
87is logged and `phosphor-fan-control` application terminates preventing the
88machine from successfully powering on.
89
90### Override Directory
91
92`/etc/phosphor-fan-presence/control/`
93
94A different version of each of the config files can be loaded by placing it into
95this writable directory location. This avoids the need to build and install a
96new firmware image on the BMC when changing any part of the configuration, such
97as for testing purposes.
98
99The override directory may not exist on the BMC, therefore to be able to use any
100number of overriding config files it must be created using the following
101command:
102
103`mkdir -p /etc/phosphor-fan-presence/control`
104
105### Search Order
106
107The `phosphor-fan-control` application will search for each config file at the
108directory locations in the following order:
109
1101. Override directory
1112. Supported directory
112   - Default location
113   - Compatible System Type location
114
115## Contents
116
117### Structure
118
119#### fans.json
120
121This file consists of an array of fan objects representing the fan FRUs in the
122system.
123
124```
125[
126    {
127        "name": "fan0",
128        "zone": "0",
129        "sensors": ["fan0_0"],
130        "target_interface": "xyz.openbmc_project.Control.FanSpeed"
131    }
132    ...
133]
134```
135
136[Syntax](fans.md)
137
138#### zones.json
139
140This file contains parameters specific to the zone.
141
142```
143[
144    {
145        "name": "0",
146        "poweron_target": 18000,
147        "default_floor": 18000,
148        "increase_delay": 5,
149        "decrease_interval": 30
150    },
151    ...
152]
153```
154
155[Syntax](zones.md)
156
157#### groups.json
158
159This file defines the groups that events.json will use in its actions. Groups
160consist of one or more D-Bus object paths and a name.
161
162```
163[
164   {
165     "name": "fan inventory",
166     "members": [
167       "/xyz/openbmc_project/inventory/system/chassis/motherboard/fan0",
168       "/xyz/openbmc_project/inventory/system/chassis/motherboard/fan1",
169       "/xyz/openbmc_project/inventory/system/chassis/motherboard/fan2",
170       "/xyz/openbmc_project/inventory/system/chassis/motherboard/fan3",
171       "/xyz/openbmc_project/inventory/system/chassis/motherboard/fan4",
172       "/xyz/openbmc_project/inventory/system/chassis/motherboard/fan5"
173     ]
174   }
175 ...
176]
177```
178
179[Syntax](groups.md)
180
181#### events.json
182
183This file contains the fan control events, where each event can contain groups,
184trigger, and actions.
185
186```
187{
188  [
189    {
190      "name": ...
191      "groups": [
192        {
193           ...
194        },
195        ...
196      ],
197
198      "triggers": [
199        {
200            ...
201        },
202        ...
203      ],
204
205      "actions": [
206        {
207          ...
208        },
209        ...
210      ],
211      ...
212    },
213    ...
214  ]
215}
216```
217
218[Syntax](events.md)
219
220### Comments
221
222The JSON data format does not support comments. However, the library used by
223code to parse the JSON does support '//' as a comment:
224
225```
226// This is a comment.
227{
228   ...
229}
230```
231
232Alternatively, a comment attribute can be used:
233
234```
235{
236  "comment": "This is a comment."
237  ...
238}
239```
240
241Fans can be queried and controlled manually using the fanctl utility. Full
242documentation can be found at
243https://github.com/openbmc/phosphor-fan-presence/blob/master/docs/control/fanctl/README.md
244
245## Validation
246
247TBD
248
249## Firmware Updates
250
251When a new firmware image is installed on the BMC, it will update the config
252file in the standard directory.
253
254The override directory will **not** be modified by a firmware update. If a
255config file exists in the override directory, it will continue to be used as the
256fan presence configuration instead of the config file located under the
257appropriate location within the supported directory.
258
259## Loading and Reloading
260
261The config files are loaded when the `phosphor-fan-control` application starts.
262
263To force the application to reload the config files, use the following command
264on the BMC:
265
266`systemctl kill -s HUP phosphor-fan-control@0.service`
267
268To confirm which config files were loaded, use the following command on the BMC:
269
270`journalctl -u phosphor-fan-control@0.service | grep Loading`
271
272## Debug
273
274Fan control maintains internal data structures that can be be dumped at runtime.
275Details [here](debug.md).
276