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