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
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
21## Data Format
22
23The config file is written using the [JSON (JavaScript Object
24Notation)](https://www.json.org/) data format and can be created using a text
25editor.
26
27
28## Example
29
30TBD
31
32
33## System Config Location
34
35The config file names are:
36* `manager.json`
37* `profiles.json`
38* `fans.json`
39* `zones.json`
40* `groups.json`
41* `events.json`
42
43### Supported Directory
44
45`/usr/share/phosphor-fan-presence/control/`
46
47The supported version of the config files are installed under this read-only
48directory location as part of the firmware image install. This is where the
49config files will be loaded from when no corresponding override config file
50exists.
51
52#### Default Location
53
54Where a single set of config files for 1-or-more system types can be used,
55the config files can be located at the base of the supported directory.
56
57i.e.)
58`/usr/share/phosphor-fan-presence/control/manager.json`
59`/usr/share/phosphor-fan-presence/control/profiles.json`
60`/usr/share/phosphor-fan-presence/control/fans.json`
61`/usr/share/phosphor-fan-presence/control/zones.json`
62`/usr/share/phosphor-fan-presence/control/groups.json`
63`/usr/share/phosphor-fan-presence/control/events.json`
64
65#### Compatible System Type Location
66
67The config files location can also be based on a system type. This is necessary
68where more than one type of machine is supported in a single BMC firmware image
69and those system types can not share any one common config file.
70
71A system type sub-directory can be obtained from the `IBMCompatibleSystem`
72D-Bus interface's `Names` property. The `Names` property contains a list of one
73or more compatible system types, ordered from most specific to the most general.
74
75Example:
76* `ibm,rainier-2u`
77* `ibm,rainier`
78
79The `phosphor-fan-control` application then traverses the supported
80directory, appending each compatible system type entry as a sub-directory from
81most specific to most general on each config file until it is found.
82
83Example: TBD
84
85
86If any required config file is not found and the machine is powered on,
87an error is logged and `phosphor-fan-control` application terminates preventing
88the machine 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
95into this writable directory location. This avoids the need to build and
96install a new firmware image on the BMC when changing any part of the
97configuration, such as for testing purposes.
98
99The override directory may not exist on the BMC, therefore to be able to use
100any number 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
108the directory locations in the following order:
1091. Override directory
1102. Supported directory
111   * Default location
112   * Compatible System Type location
113
114
115## Contents
116
117### Structure
118
119TBD
120
121### Syntax
122
123TBD
124
125### Comments
126
127TBD
128
129Fans can be queried and controlled manually using the fanctl utility. Full
130documentation can be found at https://github.com/openbmc/phosphor-fan-presence/blob/master/docs/control/fanctl/README.md
131
132## Validation
133
134TBD
135
136
137## Firmware Updates
138
139When a new firmware image is installed on the BMC, it will update the config
140file in the standard directory.
141
142The override directory will **not** be modified by a firmware update. If a
143config file exists in the override directory, it will continue to be used as
144the fan presence configuration instead of the config file located under the
145appropriate location within the supported directory.
146
147
148## Loading and Reloading
149
150The config files are loaded when the `phosphor-fan-control` application
151starts.
152
153To force the application to reload the config files, use the following command
154on the BMC:
155
156`systemctl kill -s HUP phosphor-fan-control@0.service`
157
158To confirm which config files were loaded, use the following command on the BMC:
159
160`journalctl -u phosphor-fan-control@0.service | grep Loading`
161