README.md
1# Entity Manager
2
3Entity manager is a design for managing physical system components, and mapping
4them to software resources within the BMC. Said resources are designed to allow
5the flexible adjustment of the system at runtime, as well as the reduction in
6the number of independent system configurations one needs to create.
7
8## Definitions
9
10### Entity
11
12A server component that is physically separate, detectable through some means,
13and can be added or removed from a given OpenBMC system. Said component can, and
14likely does contain multiple sub-components, but the component itself as a whole
15is referred to as an entity.
16
17Note, this term is needed because most other terms that could've been used
18(Component, Field Replaceable Unit, or Assembly) are already overloaded in the
19industry, and have a distinct definition already, which is a subset of what an
20entity encompasses.
21
22### Exposes
23
24A particular feature of an Entity. An Entity generally will have multiple
25Exposes records for the various features that component supports. Some examples
26of features include, LM75 sensors, PID control parameters, or CPU information.
27
28### Probe
29
30A set of rules for detecting a given entity. Said rules generally take the form
31of a D-Bus interface definition.
32
33## Goals
34
35Entity manager has the following goals (unless you can think of better ones):
36
371. Minimize the time and debugging required to "port" OpenBMC to new systems
382. Reduce the amount of code that is different between platforms
393. Create system level maintainability in the long term, across hundreds of
40 platforms and components, such that components interoperate as much as
41 physically possible.
42
43## Implementation
44
45A full BMC setup using Entity Manager consists of a few parts:
46
471. **A detection daemon** This is something that can be used to detect
48 components at runtime. The most common of these, fru-device, is included in
49 the Entity-Manager repo, and scans all available I2C buses for IPMI FRU
50 EEPROM devices. Other examples of detection daemons include:
51 **[peci-pcie](https://github.com/openbmc/peci-pcie):** A daemon that utilizes
52 the CPU bus to read in a list of PCIe devices from the processor.
53 **[smbios-mdr](https://github.com/openbmc/smbios-mdr):** A daemon that
54 utilizes the x86 SMBIOS table specification to detect the available systems
55 dependencies from BIOS.
56
57 In many cases, the existing detection daemons are sufficient for a single
58 system, but in cases where there is a superseding inventory control system in
59 place (such as in a large datacenter) they can be replaced with application
60 specific daemons that speak the protocol information of their controller, and
61 expose the inventory information, such that failing devices can be detected
62 more readily, and system configurations can be "verified" rather than
63 detected.
64
652. **An entity manager configuration file** Entity manager configuration files
66 are located in the ./configurations directory in the entity manager
67 repository, and include one file per device supported. Entities are detected
68 based on the "Probe" key in the json file. The intention is that this folder
69 contains all hardware configurations that OpenBMC supports, to allows an easy
70 answer to "Is X device supported". An EM configuration contains a number of
71 Exposes records that specify the specific features that this Entity supports.
72 Once a component is detected, entity manager will publish these Exposes
73 records to D-Bus.
74
753. **A reactor** The reactors are things that take the entity manager
76 configurations, and use them to execute and enable the features that they
77 describe. One example of this is dbus-sensors, which contains a suite of
78 applications that input the Exposes records for sensor devices, then connect
79 to the filesystem to create the sensors and scan loops to scan sensors for
80 those devices. Other examples of reactors could include: CPU management
81 daemons and Hot swap backplane management daemons, or drive daemons.
82
83**note:** In some cases, a given daemon could be both a detection daemon and a
84reactor when architectures are multi-tiered. An example of this might include a
85hot swap backplane daemon, which both reacts to the hot swap being detected, and
86also creates detection records of what drives are present.
87
88### Associations
89
90Entity Manager will automatically create associations between its entities in
91certain cases. For details see [here](docs/associations.md).
92
93## Requirements
94
951. Entity manager shall support the dynamic discovery of hardware at runtime,
96 using inventory interfaces. The types of devices include, but are not limited
97 to hard drives, hot swap backplanes, baseboards, power supplies, CPUs, and
98 PCIe Add-in-cards.
99
1002. Entity manager shall support the ability to add or remove support for
101 particular devices in a given binary image. By default, entity manager will
102 support all available and known working devices for all platforms.
103
1043. Entity manager shall provide data to D-Bus about a particular device such
105 that other daemons can create instances of the features being exposed.
106
1074. Entity manager shall support multiple detection runs, and shall do the
108 minimal number of changes necessary when new components are detected or no
109 longer detected. Some examples of re-detection events might include host
110 power on, drive plug/unplug, PSU plug/unplug.
111
1125. Entity manager shall have exactly one configuration file per supported device
113 model. In some cases this will cause duplicated information between files,
114 but the ability to list and see all supported device models in a single
115 place, as well as maintenance when devices do differ in the future is
116 determined to be more important than duplication of configuration files.
117
118### Explicitly out of scope
119
1201. Entity manager shall not directly participate in the detection of devices,
121 and instead will rely on other D-Bus applications to publish interfaces that
122 can be detected.
1232. Entity manager shall not directly participate in management of any specific
124 device. This is requirement is intended to intentionally limit the size and
125 feature set of entity manager, to ensure it remains small, and effective to
126 all users.
127
128### Entity Manager Compatible Software
129
130**bmcweb** A webserver implementation that uses the inventory information from
131entity-manager to produce a Redfish compliant REST API. **intel-ipmi-oem** An
132implementation of the IPMI SDR, FRU, and Storage commands that utilize Entity
133Manager as the source of information.
134
135## Additional Documentation
136
1371. **[Entity Manager DBus API](https://github.com/openbmc/entity-manager/blob/master/docs/entity_manager_dbus_api.md)**
1382. **[My First Sensor Example](https://github.com/openbmc/entity-manager/blob/master/docs/my_first_sensors.md)**
1393. **[Configuration File Schema](https://github.com/openbmc/entity-manager/tree/master/schemas)**
140