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 110TBD 111 112### Syntax 113 114TBD 115 116### Comments 117 118TBD 119 120 121## Validation 122 123TBD 124 125 126## Firmware Updates 127 128When a new firmware image is installed on the BMC, it will update the config 129file in the standard directory. 130 131The override directory will **not** be modified by a firmware update. If a 132config file exists in the override directory, it will continue to be used as 133the fan presence configuration instead of the config file located under the 134appropriate location within the supported directory. 135 136 137## Loading and Reloading 138 139The config file is loaded when the `phosphor-fan-presence-tach` application 140starts. 141 142To force the application to reload the config file, use the following command 143on the BMC: 144 145`systemctl kill -s HUP phosphor-fan-presence-tach@0.service` 146 147To confirm which config file was loaded, use the following command on the BMC: 148 149`journalctl -u phosphor-fan-presence-tach@0.service | grep Loading` 150