xref: /openbmc/entity-manager/README.md (revision ca3eec8e) 
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
6device tree overlays to add sensors to the device tree. The output is also a
7JSON file which includes all devices in the system such as fans and temperature
8sensors.
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 multilple 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
23multiple "string : value" pairs. This Entity Manager defines the following
24strings.
25
26| String    | Example Value                            | Description                              |
27| :-------- | ---------------------------------------- | ---------------------------------------- |
28| "Name"    | "X1000 1U Chassis"                       | Human readable name used for identification and sorting. |
29| "probe"   | "xyz.openbmc_project.FruDevice({'BOARD_PRODUCT_NAME':'FFPANEL'})" | Statement which attempts to read from the hardware. 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. |
30| "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. |
31| "status"  | "disabled"                               | An indicator that allows for some records to be disabled by default. |
32| "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. |
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 Records - Baseboard Example
46
47Required fields are name, probe and exposes.
48
49The configuration JSON files attempt to model after actual hardware modules
50which made up a complete system. An example baseboard JSON file shown below
51defines two fan connectors and two temperature sensors of TMP75 type. These
52objects are considered valid by BMC when the probe command (reads and
53compares the product name in FRU) is successful and this baseboard is named
54as "WFP baseboard".
55
56```
57{
58    "exposes": [
59        {
60            "Name": "1U System Fan connector 1",
61            "pwm": 1,
62            "status": "disabled",
63            "tachs": [
64                1,
65                2
66            ],
67            "Type": "IntelFanConnector"
68        },
69        {
70            "Name": "2U System Fan connector 1",
71            "pwm": 1,
72            "status": "disabled",
73            "tachs": [
74                1
75            ],
76            "Type": "IntelFanConnector"
77        },
78        {
79            "address": "0x49",
80            "bus": 6,
81            "Name": "Left Rear Temp",
82            "thresholds": [
83                [
84                    {
85                        "direction": "greater than",
86                        "Name": "upper critical",
87                        "severity": 1,
88                        "value": 115
89                    },
90                    {
91                        "direction": "greater than",
92                        "Name": "upper non critical",
93                        "severity": 0,
94                        "value": 110
95                    },
96                    {
97                        "direction": "less than",
98                        "Name": "lower non critical",
99                        "severity": 0,
100                        "value": 5
101                    },
102                    {
103                        "direction": "less than",
104                        "Name": "lower critical",
105                        "severity": 1,
106                        "value": 0
107                    }
108                ]
109            ],
110            "Type": "TMP75"
111        },
112        {
113            "address": "0x48",
114            "bus": 6,
115            "Name": "Voltage Regulator 1 Temp",
116            "thresholds": [
117                [
118                    {
119                        "direction": "greater than",
120                        "Name": "upper critical",
121                        "severity": 1,
122                        "value": 115
123                    },
124                    {
125                        "direction": "greater than",
126                        "Name": "upper non critical",
127                        "severity": 0,
128                        "value": 110
129                    },
130                    {
131                        "direction": "less than",
132                        "Name": "lower non critical",
133                        "severity": 0,
134                        "value": 5
135                    },
136                    {
137                        "direction": "less than",
138                        "Name": "lower critical",
139                        "severity": 1,
140                        "value": 0
141                    }
142                ]
143            ],
144            "Type": "TMP75"
145        }
146    ],
147    "Name": "WFP Baseboard",
148    "probe": "xyz.openbmc_project.FruDevice({'BOARD_PRODUCT_NAME' : '.*WFT'})"
149}
150```
151
152#### Configuration Records - Chassis Example
153
154Although fan connectors are considered a part of a baseboard, the physical
155fans themselves are considered as a part of a chassis. In order for a fan to
156be matched with a fan connector, the keyword "Bind" is used. The
157example below shows how a chassis fan named "Fan 1" is connected to the
158connector named "1U System Fan connector 1". When the probe command finds the
159correct product name in baseboard FRU, the fan and the connector are
160considered as being joined together.
161
162```
163{
164    "exposes": [
165        {
166            "BindConnector": "1U System Fan connector 1",
167            "Name": "Fan 1",
168            "thresholds": [
169                [
170                    {
171                        "direction": "less than",
172                        "Name": "lower critical",
173                        "severity": 1,
174                        "value": 1750
175                    },
176                    {
177                        "direction": "less than",
178                        "Name": "lower non critical",
179                        "severity": 0,
180                        "value": 2000
181                    }
182                ]
183            ],
184            "Type": "AspeedFan"
185        }
186    ]
187}
188```
189
190## Enabling Sensors
191
192As demons can trigger off of shared types, sometimes some handshaking will be
193needed to enable sensors. Using the TMP75 sensor as an example, when the
194sensor object is enabled, the device tree must be updated before scanning may
195begin. The device tree overlay generator has the ability to key off of
196different types and create device tree overlays for specific offsets. Once
197this is done, the baseboard temperature sensor demon can scan the sensors.
198
199## Run Unit Tests
200
201The following environment variables need to be set to run unit tests:
202
203* TEST: 1, this disables the fru parser from scanning on init and changes the
204work directories.
205