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 16 the complexity to the reactors leads to fewer lines of code overall, even 17 if 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 25 of 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. 29 The 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 31 its own file minimizes the change needed between different components when 32 bugs 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 38 clear 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 40 hardware that despite having different part numbers, are actually 41 physically 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, 46 bugs, and OEM supported firmware features. As such, they require 47 separate 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 56 to 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 63 at 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 81removable power 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## Configuration schema 110 111The config schema is documented in [README.md](schemas/README.schema) 112 113## Configuration Records - Baseboard Example 114 115The configuration JSON files attempt to model the actual hardware modules which 116make up a complete system. An example baseboard JSON file shown below defines 117two fan connectors and two temperature sensors of TMP75 type. These objects are 118considered valid by BMC when the probe command (reads and compares the product 119name in FRU) is successful and this baseboard is named as "WFP baseboard". 120 121``` 122{ 123 "Exposes": [ 124 { 125 "Name": "1U System Fan connector 1", 126 "Pwm": 1, 127 "Status": "disabled", 128 "Tachs": [ 129 1, 130 2 131 ], 132 "Type": "IntelFanConnector" 133 }, 134 { 135 "Name": "2U System Fan connector 1", 136 "Pwm": 1, 137 "Status": "disabled", 138 "Tachs": [ 139 1 140 ], 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 216#### Configuration Records - Chassis Example 217 218Although fan connectors are considered a part of a baseboard, the physical fans 219themselves are considered as a part of a chassis. In order for a fan to be 220matched with a fan connector, the keyword "Bind" is used. The example below 221shows how a chassis fan named "Fan 1" is connected to the connector named "1U 222System Fan connector 1". When the probe command finds the correct product name 223in baseboard FRU, the fan and the connector are considered as being joined 224together. 225 226``` 227{ 228 "Exposes": [ 229 { 230 "BindConnector": "1U System Fan connector 1", 231 "Name": "Fan 1", 232 "Thresholds": [ 233 { 234 "Direction": "less than", 235 "Name": "lower critical", 236 "Severity": 1, 237 "Value": 1750 238 }, 239 { 240 "Direction": "less than", 241 "Name": "lower non critical", 242 "Severity": 0, 243 "Value": 2000 244 } 245 ], 246 "Type": "AspeedFan" 247 } 248 ] 249} 250``` 251 252## Enabling Sensors 253 254As daemons can trigger off of shared types, sometimes some handshaking will be 255needed to enable sensors. Using the TMP75 sensor as an example, when the sensor 256object is enabled, the device tree must be updated before scanning may begin. 257The entity-manager can key off of different types and export devices for 258specific configurations. Once this is done, the baseboard temperature sensor 259daemon can scan the sensors. 260 261