1# Entity Manager 2 3Entity manager is a runtime configuration application which parses configuration 4files (in JSON format) and attempts to detect the devices described by the 5configuration files. It also can, based on the configuration, attempt to load 6install devices into sysfs. It takes these configurations and produces a best 7representation of the files on dbus using the xyz.openbmc_project.Configuration 8namespace. It also produces a system.json file for persistence. 9 10## Configuration Syntax 11 12In most cases a server system is built with multiple hardware modules (circuit 13boards) such as baseboard, risers, and hot-swap backplanes. While it is 14perfectly legal to combine the JSON configuration information for all the 15hardware modules into a single file if desired, it is also possible to divide 16them into multiple configuration files. For example, there may be a baseboard 17JSON file (describes all devices on the baseboard) and a chassis JSON file 18(describes devices attached to the chassis). When one of the hardware modules 19needs to be upgraded (e.g., a new temperature sensor), only such JSON 20configuration file needs to be be updated. 21 22Within a configuration file, there is a JSON object which consists of multiple 23"string : value" pairs. This Entity Manager defines the following strings. 24 25| String | Example Value | Description | 26| :-------- | ---------------------------------------- | ---------------------------------------- | 27| "Name" | "X1000 1U Chassis" | Human readable name used for identification and sorting. | 28| "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 | 29| "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. | 30| "Status" | "disabled" | An indicator that allows for some records to be disabled by default. | 31| "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. | 32| "DisableNode| "Fan 1" | Sets the status of another Entity to disabled. | 33 34Template strings in the form of "$identifier" may be used in configuration 35files. The following table describes the template strings currently defined. 36 37| Template String | Description | 38| :-------------- | :--------------------------------------- | 39| "$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. | 40| "$address" | When the "probe" is successful, this template string is substituted with the (7-bit) I2C address of the FRU device. | 41| "$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. | 42 43 44 45## Configuration HowTos 46 47If you're just getting started and your goal is to add sensors dynamically, 48check out [My First Sensors](docs/my_first_sensors.md) 49 50 51## Configuration Records - Baseboard Example 52 53Required fields are name, probe and exposes. 54 55The configuration JSON files attempt to model the actual hardware modules 56which make up a complete system. An example baseboard JSON file shown below 57defines two fan connectors and two temperature sensors of TMP75 type. These 58objects are considered valid by BMC when the probe command (reads and compares 59the product name in FRU) is successful and this baseboard is named as "WFP 60baseboard". 61 62``` 63{ 64 "Exposes": [ 65 { 66 "Name": "1U System Fan connector 1", 67 "Pwm": 1, 68 "Status": "disabled", 69 "Tachs": [ 70 1, 71 2 72 ], 73 "Type": "IntelFanConnector" 74 }, 75 { 76 "Name": "2U System Fan connector 1", 77 "Pwm": 1, 78 "Status": "disabled", 79 "Tachs": [ 80 1 81 ], 82 "Type": "IntelFanConnector" 83 }, 84 { 85 "Address": "0x49", 86 "Bus": 6, 87 "Name": "Left Rear Temp", 88 "Thresholds": [ 89 { 90 "Direction": "greater than", 91 "Name": "upper critical", 92 "Severity": 1, 93 "Value": 115 94 }, 95 { 96 "Direction": "greater than", 97 "Name": "upper non critical", 98 "Severity": 0, 99 "Value": 110 100 }, 101 { 102 "Direction": "less than", 103 "Name": "lower non critical", 104 "Severity": 0, 105 "Value": 5 106 }, 107 { 108 "Direction": "less than", 109 "Name": "lower critical", 110 "Severity": 1, 111 "Value": 0 112 } 113 ], 114 "Type": "TMP75" 115 }, 116 { 117 "Address": "0x48", 118 "Bus": 6, 119 "Name": "Voltage Regulator 1 Temp", 120 "Thresholds": [ 121 { 122 "Direction": "greater than", 123 "Name": "upper critical", 124 "Severity": 1, 125 "Value": 115 126 }, 127 { 128 "Direction": "greater than", 129 "Name": "upper non critical", 130 "Severity": 0, 131 "Value": 110 132 }, 133 { 134 "Direction": "less than", 135 "Name": "lower non critical", 136 "Severity": 0, 137 "Value": 5 138 }, 139 { 140 "Direction": "less than", 141 "Name": "lower critical", 142 "Severity": 1, 143 "Value": 0 144 } 145 ], 146 "Type": "TMP75" 147 } 148 ], 149 "Name": "WFP Baseboard", 150 "Probe": "xyz.openbmc_project.FruDevice({'BOARD_PRODUCT_NAME' : '.*WFT'})" 151} 152``` 153 154[Full Configuration](https://github.com/openbmc/entity-manager/blob/master/configurations/WFT%20Baseboard.json) 155 156 157#### Configuration Records - Chassis Example 158 159Although fan connectors are considered a part of a baseboard, the physical fans 160themselves are considered as a part of a chassis. In order for a fan to be 161matched with a fan connector, the keyword "Bind" is used. The example below 162shows how a chassis fan named "Fan 1" is connected to the connector named "1U 163System Fan connector 1". When the probe command finds the correct product name 164in baseboard FRU, the fan and the connector are considered as being joined 165together. 166 167``` 168{ 169 "Exposes": [ 170 { 171 "BindConnector": "1U System Fan connector 1", 172 "Name": "Fan 1", 173 "Thresholds": [ 174 { 175 "Direction": "less than", 176 "Name": "lower critical", 177 "Severity": 1, 178 "Value": 1750 179 }, 180 { 181 "Direction": "less than", 182 "Name": "lower non critical", 183 "Severity": 0, 184 "Value": 2000 185 } 186 ], 187 "Type": "AspeedFan" 188 } 189 ] 190} 191``` 192 193## Enabling Sensors 194 195As daemons can trigger off of shared types, sometimes some handshaking will be 196needed to enable sensors. Using the TMP75 sensor as an example, when the sensor 197object is enabled, the device tree must be updated before scanning may begin. 198The entity-manager can key off of different types and export devices for 199specific configurations. Once this is done, the baseboard temperature sensor 200daemon can scan the sensors. 201 202