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