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