1# Config Files 2 3## Intent 4 5Configuration files are intended to represent the minimum amount of 6configuration required to describe a given piece of hardware. As such, they are 7intended to be simple, and are guided by the following principles. 8 91. Configuration files should be easy to write. If a tradeoff is to be made 10 between a config file being complex to write, and a reactor being complex to 11 write, the reactor will be the one to hold the complexity. Why? 12 - Configuration files will get replicated and built to support hundreds of 13 systems over time, and scale linearly with the number of systems. In 14 contrast, reactors tend to scale as a logarithm of system count, with each 15 new system supported adding fewer and fewer reactors. As such, pushing the 16 complexity to the reactors leads to fewer lines of code overall, even if 17 the reactor itself contains more complex actions. 18 - Reactor writers tend to be domain experts on their subsystem, and 19 intimately understand the constraints that are emplaced on that subsystem. 20 Config file writers are generally building support for a wide range of 21 reactors on a single piece of hardware, and will generally have less 22 knowledge of each individual reactors constraints. 23 242. Configuration files should trend toward one config file per physical piece of 25 hardware, and should avoid attempting to support multiple variations of a 26 given piece of hardware in a single file, even at the risk of duplicating 27 information. Why? 28 - Hardware constraints, bugs, and oddities are generally found over time. The 29 initial commit of a configuration file is far from the final time that 30 changes will be submitted. Having each individual piece of hardware in its 31 own file minimizes the change needed between different components when bugs 32 are found, or features are added. 33 - Having separate config files reduces the number of platforms that need to 34 be tested for any given config file change, thus limiting the "blast 35 radius" of particular kinds of changes, as well as making an explicit log 36 of what changed for a specific platform. 37 - Having one config file per piece of hardware makes it much easier and clear 38 for a user to determine if a piece of hardware is supported. 39 - Note: This is a "guideline" not a "rule". There are many cases of hardware 40 that despite having different part numbers, are actually physically 41 identical, and as such, the config files will never differ. 42 - Example: SAS modules and cards made by the same company, on the same 43 process, and branded with different manufacturers and part numbers. 44 - Non-Example: Power supplies. While all pmbus power supplies appear 45 similar, there tend to be significant differences in featuresets, bugs, 46 and OEM supported firmware features. As such, they require separate 47 config files. 48 493. Configuration files are not a long-term stable ABI. Why? 50 - Configuration files occasionally need to modify their schema in pursuit of 51 simplicity, or based on a greater understanding of the system level 52 constraints. 53 - The repo will ensure that all schema changes are enacted such that the 54 files in the repo will not be broken as a result of the schema change, and 55 will be carried forward. The recommended way to avoid merge problems is to 56 upstream your configurations. 57 - Note: This drives the requirement that config files shall not be checked 58 into OpenBMC meta layers. 59 604. Configurations should represent only the things that are _different_ and 61 undetectable between platforms. Why? 62 - There are many behaviors that the BMC has that are very easily detected at 63 runtime, or where the behavior can be identical between different 64 platforms. Things like timeouts, protocol versions, and communcation 65 channels can generally be represented with a default that works for all 66 platforms, and doesn't need to be an entity-configurable parameter. In 67 general, reducing the config files to _only_ the differences reduces 68 complexity, and explicitly bounds where dicsussion is needed for platform 69 differences, and where a difference is "supported" and "reasonable" to 70 maintain in the long run. 71 72## Configuration Syntax 73 74In most cases a server system is built with multiple hardware modules (circuit 75boards) such as baseboard, risers, and hot-swap backplanes. While it is 76perfectly legal to combine the JSON configuration information for all the 77hardware modules into a single file if desired, it is recommended to divide them 78into multiple configuration files. For example, there may be a baseboard JSON 79file (describes all devices on the baseboard) and a chassis JSON file (describes 80devices attached to the chassis). Other examples of entities might be removable 81power supplies, fans, and PCIe add in cards. 82 83Within a configuration file, there is a JSON object which consists of multiple 84"string : value" pairs. This Entity Manager defines the following strings. 85 86| String | Example Value | Description | 87| :------------ | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 88| "Name" | `"X1000 1U Chassis"` | Human readable name used for identification and sorting. | 89| "Probe" | `"xyz.openbmc_project.FruDevice({'BOARD_PRODUCT_NAME':'FFPANEL'})"` | Statement which attempts to read from d-bus. The result determines if a configuration record should be applied. The value for probe can be set to “TRUE” in the case the record should always be applied, or set to more complex lookups, for instance a field in a FRU file that is exposed by the frudevice | 90| "Exposes" | `[{"Name" : "CPU fan"}, ...]` | An array of JSON objects which are valid if the probe result is successful. These objects describe the devices BMC can interact. | 91| "Status" | `"disabled"` | An indicator that allows for some records to be disabled by default. | 92| "Bind\*" | `"2U System Fan connector 1"` | The record isn't complete and needs to be combined with another to be functional. The value is a unique reference to a record elsewhere. | 93| "DisableNode" | `"Fan 1"` | Sets the status of another Entity to disabled. | 94 95Template strings in the form of "$identifier" may be used in configuration 96files. The following table describes the template strings currently defined. 97 98| Template String | Description | 99| :-------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 100| "$bus" | During a I2C bus scan and when the "probe" command is successful, this template string is substituted with the bus number to which the device is connected. | 101| "$address" | When the "probe" is successful, this template string is substituted with the (7-bit) I2C address of the FRU device. | 102| "$index" | A run-tim enumeration. This template string is substituted with a unique index value when the "probe" command is successful. This allows multiple identical devices (e.g., HSBPs) to exist in a system but each with a unique name. | 103 104## Configuration HowTos 105 106If you're just getting started and your goal is to add sensors dynamically, 107check out [My First Sensors](docs/my_first_sensors.md) 108 109## When adding/moving/removing a configuration file 110 111Please run `scripts/generate_config_list.sh` from the root of the repository so 112that configuration files are correctly referenced by meson. 113 114## Configuration schema 115 116The config schema is documented in [README.md](schemas/README.md) 117 118## Configuration Records - Baseboard Example 119 120The configuration JSON files attempt to model the actual hardware modules which 121make up a complete system. An example baseboard JSON file shown below defines 122two fan connectors and two temperature sensors of TMP75 type. These objects are 123considered valid by BMC when the probe command (reads and compares the product 124name in FRU) is successful and this baseboard is named as "WFP baseboard". 125 126```json 127{ 128 "Exposes": [ 129 { 130 "Name": "1U System Fan connector 1", 131 "Pwm": 1, 132 "Status": "disabled", 133 "Tachs": [1, 2], 134 "Type": "IntelFanConnector" 135 }, 136 { 137 "Name": "2U System Fan connector 1", 138 "Pwm": 1, 139 "Status": "disabled", 140 "Tachs": [1], 141 "Type": "IntelFanConnector" 142 }, 143 { 144 "Address": "0x49", 145 "Bus": 6, 146 "Name": "Left Rear Temp", 147 "Thresholds": [ 148 { 149 "Direction": "greater than", 150 "Name": "upper critical", 151 "Severity": 1, 152 "Value": 115 153 }, 154 { 155 "Direction": "greater than", 156 "Name": "upper non critical", 157 "Severity": 0, 158 "Value": 110 159 }, 160 { 161 "Direction": "less than", 162 "Name": "lower non critical", 163 "Severity": 0, 164 "Value": 5 165 }, 166 { 167 "Direction": "less than", 168 "Name": "lower critical", 169 "Severity": 1, 170 "Value": 0 171 } 172 ], 173 "Type": "TMP75" 174 }, 175 { 176 "Address": "0x48", 177 "Bus": 6, 178 "Name": "Voltage Regulator 1 Temp", 179 "Thresholds": [ 180 { 181 "Direction": "greater than", 182 "Name": "upper critical", 183 "Severity": 1, 184 "Value": 115 185 }, 186 { 187 "Direction": "greater than", 188 "Name": "upper non critical", 189 "Severity": 0, 190 "Value": 110 191 }, 192 { 193 "Direction": "less than", 194 "Name": "lower non critical", 195 "Severity": 0, 196 "Value": 5 197 }, 198 { 199 "Direction": "less than", 200 "Name": "lower critical", 201 "Severity": 1, 202 "Value": 0 203 } 204 ], 205 "Type": "TMP75" 206 } 207 ], 208 "Name": "WFP Baseboard", 209 "Probe": "xyz.openbmc_project.FruDevice({'BOARD_PRODUCT_NAME' : '.*WFT'})" 210} 211``` 212 213[Full Configuration](https://github.com/openbmc/entity-manager/blob/master/configurations/WFT_Baseboard.json) 214 215## Configuration Records - Chassis Example 216 217Although fan connectors are considered a part of a baseboard, the physical fans 218themselves are considered as a part of a chassis. In order for a fan to be 219matched with a fan connector, the keyword "Bind" is used. The example below 220shows how a chassis fan named "Fan 1" is connected to the connector named "1U 221System Fan connector 1". When the probe command finds the correct product name 222in baseboard FRU, the fan and the connector are considered as being joined 223together. 224 225```json 226{ 227 "Exposes": [ 228 { 229 "BindConnector": "1U System Fan connector 1", 230 "Name": "Fan 1", 231 "Thresholds": [ 232 { 233 "Direction": "less than", 234 "Name": "lower critical", 235 "Severity": 1, 236 "Value": 1750 237 }, 238 { 239 "Direction": "less than", 240 "Name": "lower non critical", 241 "Severity": 0, 242 "Value": 2000 243 } 244 ], 245 "Type": "AspeedFan" 246 } 247 ] 248} 249``` 250 251## Enabling Sensors 252 253As daemons can trigger off of shared types, sometimes some handshaking will be 254needed to enable sensors. Using the TMP75 sensor as an example, when the sensor 255object is enabled, the device tree must be updated before scanning may begin. 256The entity-manager can key off of different types and export devices for 257specific configurations. Once this is done, the baseboard temperature sensor 258daemon can scan the sensors. 259 260## C-Style Comments Support 261 262The configuration JSON file supports c-style comments base on the rules as 263below: 264 265- Single-line style comments (//) can be on a new line or at the end of a line 266 with contents. 267 268```json5 269{ 270 // Single-line style comment (new line) 271 Key: "Value", // Single-line comment (end of content) 272} 273``` 274 275- Multi-line style comments (/\* \*/) use the must be free-standing. 276 277```json5 278{ 279 /* Multi-line style comment */ 280 /* 281 * Multi-line style comments 282 */ 283} 284``` 285 286- When running autojson.py on a configuration JSON file, the comments will be 287 removed first and then get inserted back into the file in the line they came 288 from. If keys are resorted or the number of lines change, all bets for 289 correctness are off. 290 291- No attempts to re-indent multi-line comments will be made. 292 293In light of this, it is highly recommended to use a JSON formatter such as 294prettier before using this script and planning to move multi-line comments 295around after key resorting. 296