| <!--* |
| # Document freshness: For more information, see go/fresh-source. |
| freshness: { owner: 'tlbmc-dev' reviewed: '2026-08-17' } |
| *--> |
| |
| # Entity Configuration System |
| |
| The Entity Configuration System in tlBMC is responsible for parsing platform |
| configurations (modeled on standard OpenBMC Entity Manager JSON files) and |
| translating them into C++ config objects and schemas that drive the discovery, |
| topological mapping, and telemetry polling in tlBMC. |
| |
| The core implementation resides in the |
| `third_party/milotic/external/cc/tlbmc/configs/` directory. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## Overview |
| |
| The Entity Configuration system: |
| |
| - Loads and parses JSON files representing platform hardware components and |
| virtual devices. |
| - Validates the JSON fields against defined schemas. |
| - Maps physical devices to their respective driver configurations. |
| - Constructs the machine's topological tree (`TopologyConfig`), linking parent |
| and child chassis, slots, sensors, and cables. |
| - Populates the local inventory table (`FruTable`). |
| |
| -------------------------------------------------------------------------------- |
| |
| ## Configuration Parsing and Probe Rules |
| |
| The C++ entry point `EntityConfigJsonImpl` parses files under |
| `/usr/share/entity-manager/configurations/` (or designated directory) and |
| evaluates probes to determine if a hardware component is present. |
| |
| ### Probe Types |
| |
| A configuration is only loaded if its `"ProbeV2"` rules evaluate to `true`. |
| Supported probes include: |
| |
| | Probe Type | Key | Description | |
| | :-------------------- | :------------------------ | :----------------------- | |
| | **IPMI FRU Probe** | `"IpmiFru"` | Evaluates the presence | |
| : : : of an EEPROM FRU based : |
| : : : on its bus, address, and : |
| : : : product name. : |
| | **GPIO Probe** | `"Gpio"` | Evaluates one or more | |
| : : : GPIO pin values. A match : |
| : : : occurs if the actual pin : |
| : : : values equal the : |
| : : : expected boolean states. : |
| | **Offline Node Entity | `"OfflineNodeEntityInfo"` | Matches | |
| : Probe** : : platform-specific : |
| : : : offline hardware : |
| : : : contexts. : |
| | **Standard Boolean | `"TRUE"` / `"FALSE"` | Statically forces the | |
| : Probe** : : probe to match or fail. : |
| | **Dependency Probe** | `FOUND('ConfigName')` | Evaluates to true if | |
| : : : another named config has : |
| : : : already been : |
| : : : successfully probed : |
| : : : (using topological BFS : |
| : : : evaluation). : |
| |
| -------------------------------------------------------------------------------- |
| |
| ## Supported Configuration Schemas |
| |
| `EntityConfigJsonImpl` parses specific JSON sections into dedicated |
| configurations depending on the `"Type"` of exposed elements. |
| |
| ### Sensor Configuration Types |
| |
| | Exposure `"Type"` | Internal Protobuf Config | Description | |
| | :------------------ | :------------------------------ | :------------------- | |
| | **HWMon Temp** | `HwmonTempSensorConfig` | Polled via Linux | |
| : : : sysfs hwmon : |
| : : : interfaces. : |
| | **PSU Sensors** | `PsuSensorConfig` | Polled via PMBus or | |
| : : : custom PSU : |
| : : : monitoring ICs. : |
| | **ADC Sensors** | `AdcSensorConfig` | Polled via | |
| : : : analog-to-digital : |
| : : : converter chips. : |
| | **Fan Controllers** | `FanControllerConfig` | Driver configuration | |
| : : : for fan controller : |
| : : : chips. : |
| | **Fan PWM** | `FanPwmConfig` | Individual PWM | |
| : : : control : |
| : : : configurations. : |
| | **Fan Tach** | `FanTachConfig` | Individual | |
| : : : tachometer speed : |
| : : : sensors. : |
| | **Shared Memory** | `SharedMemSensorConfig` | Telemetry shared via | |
| : : : a shared memory : |
| : : : buffer. : |
| | **Intel CPU** | `IntelCpuSensorConfig` | Polled via Intel CPU | |
| : : : hardware interfaces. : |
| | **GPIO Sensor** | `GpioSensorConfig` | Exposes pin voltage | |
| : : : levels as discrete : |
| : : : sensors. : |
| | **Virtual Sensor** | `VirtualSensorConfig` | Evaluates | |
| : : : mathematical : |
| : : : expressions using : |
| : : : other sensors. : |
| | **NIC Telemetry** | `NicTelemetryConfig` | Exposes metrics | |
| : : : parsed from Network : |
| : : : Interface Cards. : |
| | **Redfish | `RedfishAggregatedSensorConfig` | Configures sensors | |
| : Aggregated** : : aggregated from : |
| : : : satellite : |
| : : : controllers. : |
| | **Redfish | `RedfishAggregatedBatchConfig` | Combines satellite | |
| : Aggregated : : collection rules. : |
| : Telemetry** : : : |
| | **Bulk Sensor | `BulkDeviceConfig` | Configures bulk | |
| : Device** : : telemetry registers. : |
| |
| -------------------------------------------------------------------------------- |
| |
| ## Protobuf Configuration Schemas |
| |
| The Entity Configuration System parses Entity Manager JSON configurations into |
| structured protobuf messages. These messages are used by different collectors to |
| initialize the corresponding services. |
| |
| ### Core Inventory & Topology Schemas |
| |
| - **`FruTable`** (defined in |
| [`fru.proto`](http://google3/third_party/milotic/external/cc/tlbmc/resource/fru.proto)): |
| Holds the list of all probed FRUs (field replaceable units) and inventory |
| metrics. |
| - **`TopologyConfig`** (defined in |
| [`topology_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/topology_config.proto)): |
| Maps the physical hierarchy of chassis, cards, slots, and cables. |
| - **`AdHocFruConfig`** (defined in |
| [`ad_hoc_fru_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/ad_hoc_fru_config.proto)): |
| Defines fallback inventory keys when EEPROMs are missing or unreadable. |
| - **`GpioFruConfig`** (defined in |
| [`gpio_fru_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/gpio_fru_config.proto)): |
| Maps FRU presence checks to discrete GPIO pins. |
| |
| ### Common Device & Attribute Schemas |
| |
| - **`EntityCommonConfig`** (defined in |
| [`entity_common_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/entity_common_config.proto)): |
| Declares parameters common to all devices (polling rate, host power |
| requirements, queues). |
| - **`SensorInstanceProperties`** (defined in |
| [`sensor_instance_properties.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/sensor_instance_properties.proto)): |
| Properties for a single channel (bounds, related Redfish resource, etc.). |
| - **`ThresholdConfigs`** (defined in |
| [`threshold_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/threshold_config.proto)): |
| Defines warning and critical temperature/voltage bounds. |
| - **`ReadingRangeConfigs`** (defined in |
| [`reading_range_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/reading_range_config.proto)): |
| Hardware constraints (minimum and maximum raw ranges). |
| - **`ReadingTransformConfig`** (defined in |
| [`reading_transform_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/reading_transform_config.proto)): |
| Math multipliers/offsets applied to scale raw registers. |
| - **`HalCommonConfig`** (defined in |
| [`hal_common_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/hal_common_config.proto)): |
| Hardware location context (bus, hex address, devpath). |
| |
| ### Sensor Driver & Subsystem Schemas |
| |
| - **`HwmonTempSensorConfig`** (defined in |
| [`hwmon_temp_sensor_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/hwmon_temp_sensor_config.proto)): |
| Configures standard temp chips (TMP75, TMP461, SA56004). |
| - **`PsuSensorConfig`** (defined in |
| [`psu_sensor_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/psu_sensor_config.proto)): |
| Maps PMBus power chips (ADM1272, INA226, etc.). |
| - **`AdcSensorConfig`** (defined in |
| [`adc_sensor_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/adc_sensor_config.proto)): |
| Maps analog inputs (ADS1015, TLA2024). |
| - **`FanControllerConfig`** (defined in |
| [`fan_controller_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/fan_controller_config.proto)): |
| Configures I2C fan controller chips (MAX31790). |
| - **`FanPwmConfig`** (defined in |
| [`fan_pwm_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/fan_pwm_config.proto)): |
| Declares speed-modulation outputs. |
| - **`FanTachConfig`** (defined in |
| [`fan_tach_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/fan_tach_config.proto)): |
| Declares fan speed feedback sensors. |
| - **`GpioSensorConfig`** (defined in |
| [`gpio_sensor_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/gpio_sensor_config.proto)): |
| Maps discrete input/output level sensors. |
| - **`IntelCpuSensorConfig`** (defined in |
| [`intel_cpu_sensor_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/intel_cpu_sensor_config.proto)): |
| Configures Xeon CPU APML telemetry. |
| - **`SharedMemSensorConfig`** (defined in |
| [`shared_mem_sensor_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/shared_mem_sensor_config.proto)): |
| Links memory-mapped telemetry buffers. |
| - **`VirtualSensorConfig`** (defined in |
| [`virtual_sensor_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/virtual_sensor_config.proto)): |
| Evaluates mathematical/logical formulas based on other sensors. |
| - **`BulkDeviceConfig`** (defined in |
| [`bulk_device_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/bulk_device_config.proto)): |
| Configures bulk telemetry registers. |
| - **`NicTelemetryConfig`** (defined in |
| [`nic_telemetry_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/nic_telemetry_config.proto)): |
| Maps EEPROM logs and metrics for Network Interface Cards. |
| - **`RedfishAggregatedSensorConfig`** (defined in |
| [`redfish_aggregated_sensor_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/redfish_aggregated_sensor_config.proto)): |
| Maps satellite controllers. |
| - **`RedfishAggregatedBatchConfig`** (defined in |
| [`redfish_aggregated_batch_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/redfish_aggregated_batch_config.proto)): |
| Combines satellite collection rules. |
| - **`PcieConfig`** (defined in |
| [`pcie_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/pcie_config.proto)): |
| Describes PCIe controller scanning and links. |
| - **`GpioConfig`** (defined in |
| [`gpio_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/gpio_config.proto)): |
| Describes low-level platform GPIO mappings. |
| - **`ThermalConfig`** (defined in |
| [`thermal_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/thermal_config.proto)): |
| Configures dynamic steps/PID fan speed tables. |
| - **`ThermalControllerSpecification`** (defined in |
| [`thermal_controller_specification.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/thermal_controller_specification.proto)): |
| Low-level cooling loops logic. |
| - **`SelConfig`** (defined in |
| [`sel_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/sel_config.proto)): |
| Directs System Event Log writing. |
| - **`PowerControl`** (defined in |
| [`power_control.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/power_control.proto)): |
| Details chassis power sequencing lines. |
| - **`PowerFaultLogConfig`** (defined in |
| [`power_fault_log_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/power_fault_log_config.proto)): |
| Directs power signal fault recording. |
| - **`PowerFaultDetectorConfig`** (defined in |
| [`power_fault_detector_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/power_fault_detector_config.proto)): |
| Configures individual detector lines. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## Examples |
| |
| ### 1. GPIO Probed Board Config |
| |
| Shows a board configuration that is only loaded if GPIO pin `SYS_PWROK` is |
| `true`. |
| |
| ```json |
| { |
| "Name": "Platform_Mobo", |
| "Probe": { |
| "Gpio": { |
| "SYS_PWROK": true |
| } |
| }, |
| "Exposes": [ |
| { |
| "Name": "Board_Temp", |
| "Type": "tmp75", |
| "Bus": 8, |
| "Address": "0x48", |
| "TlbmcOwned": true |
| } |
| ] |
| } |
| ``` |
| |
| ### 2. Dependency Probe (FOUND) Config |
| |
| Shows a child riser card config that is only loaded if the parent |
| `"Platform_Mobo"` is successfully probed. |
| |
| ```json |
| { |
| "Name": "Riser_Card", |
| "Probe": "FOUND('Platform_Mobo')", |
| "Exposes": [ |
| { |
| "Name": "Riser_Temp", |
| "Type": "tmp461", |
| "Bus": 9, |
| "Address": "0x4c", |
| "TlbmcOwned": true |
| } |
| ] |
| } |
| ``` |
| |
| -------------------------------------------------------------------------------- |
| |
| ## Blocklist Configuration (`blocklist_parser.cc`) |
| |
| To prevent tlBMC from scanning or interacting with unstable or reserved devices, |
| a JSON blocklist configuration can be defined. |
| |
| ### JSON Format |
| |
| ```json |
| { |
| "buses": [ |
| 5, |
| { |
| "bus": 12, |
| "addresses": ["0x50", "0x51"] |
| } |
| ] |
| } |
| ``` |
| |
| *In this example, I2C bus 5 is blocked entirely. On bus 12, only addresses |
| `0x50` and `0x51` are blocked.* |
| |
| -------------------------------------------------------------------------------- |
| |
| ## Code References |
| |
| ### Config Protos |
| |
| - [`fru.proto`](http://google3/third_party/milotic/external/cc/tlbmc/resource/fru.proto) |
| - [`topology_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/topology_config.proto) |
| - [`ad_hoc_fru_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/ad_hoc_fru_config.proto) |
| - [`gpio_fru_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/gpio_fru_config.proto) |
| - [`entity_common_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/entity_common_config.proto) |
| - [`sensor_instance_properties.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/sensor_instance_properties.proto) |
| - [`threshold_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/threshold_config.proto) |
| - [`reading_range_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/reading_range_config.proto) |
| - [`reading_transform_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/reading_transform_config.proto) |
| - [`hal_common_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/hal_common_config.proto) |
| - [`hwmon_temp_sensor_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/hwmon_temp_sensor_config.proto) |
| - [`psu_sensor_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/psu_sensor_config.proto) |
| - [`adc_sensor_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/adc_sensor_config.proto) |
| - [`fan_controller_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/fan_controller_config.proto) |
| - [`fan_pwm_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/fan_pwm_config.proto) |
| - [`fan_tach_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/fan_tach_config.proto) |
| - [`gpio_sensor_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/gpio_sensor_config.proto) |
| - [`intel_cpu_sensor_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/intel_cpu_sensor_config.proto) |
| - [`shared_mem_sensor_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/shared_mem_sensor_config.proto) |
| - [`virtual_sensor_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/virtual_sensor_config.proto) |
| - [`bulk_device_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/bulk_device_config.proto) |
| - [`nic_telemetry_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/nic_telemetry_config.proto) |
| - [`redfish_aggregated_sensor_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/redfish_aggregated_sensor_config.proto) |
| - [`redfish_aggregated_batch_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/redfish_aggregated_batch_config.proto) |
| - [`pcie_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/pcie_config.proto) |
| - [`gpio_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/gpio_config.proto) |
| - [`thermal_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/thermal_config.proto) |
| - [`thermal_controller_specification.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/thermal_controller_specification.proto) |
| - [`sel_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/sel_config.proto) |
| - [`power_control.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/power_control.proto) |
| - [`power_fault_log_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/power_fault_log_config.proto) |
| - [`power_fault_detector_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/power_fault_detector_config.proto) |
| |
| ### Core Code |
| |
| - [`entity_config.h`](http://google3/third_party/milotic/external/cc/tlbmc/configs/entity_config.h) |
| - [`entity_config_json_impl.h`](http://google3/third_party/milotic/external/cc/tlbmc/configs/entity_config_json_impl.h) |
| - [`entity_config_json_impl.cc`](http://google3/third_party/milotic/external/cc/tlbmc/configs/entity_config_json_impl.cc) |
| - [`blocklist_parser.h`](http://google3/third_party/milotic/external/cc/tlbmc/configs/blocklist_parser.h) |
