OpenBMC：entity-manager 设备建模机制

OpenBMC：entity-manager 设备建模机制

1. 前言

在 OpenBMC 中，硬件设备通常不是直接由上层服务以固定代码的方式描述，而是通过配置文件完成设备建模。

entity-manager 就是 OpenBMC 中负责设备配置和运行时建模的重要组件。它通过 JSON 配置文件描述主板、处理器、内存、电源、风扇、温度传感器以及电压传感器等硬件资源，并将匹配到的设备信息发布到 D-Bus。

整体关系如下：

平台硬件
↓
设备树、I2C、GPIO、FRU 等底层信息
↓
entity-manager JSON 配置
↓
entity-manager 运行时对象
↓
dbus-sensors、风扇控制、功耗管理等服务
↓
D-Bus、Redfish、IPMI、WebUI

entity-manager 本身通常不负责周期性读取温度、电压或风扇转速，它更侧重于：

• 描述平台硬件
• 判断硬件是否存在
• 创建运行时配置对象
• 发布设备属性和关联关系
• 为其他 OpenBMC 服务提供统一的设备模型

2. entity-manager 的主要作用

2.1 描述平台硬件

不同服务器平台的硬件组成不同，例如：

• I2C 总线数量不同
• 温度传感器型号不同
• 电源模块数量不同
• 风扇数量和命名方式不同
• CPU、内存和主板结构不同
• 传感器阈值不同

如果将这些内容全部写入 C++ 代码，平台变化时需要重新修改和编译程序。

entity-manager 将平台差异放入 JSON 配置文件中，使硬件描述和业务代码分离。

2.2 进行硬件匹配

一个系统镜像可能支持多个硬件版本。entity-manager 启动后，会根据配置中的 Probe 条件判断当前设备是否存在。

例如：

当前设备是某型号主板
当前 I2C 总线上存在指定芯片
当前 FRU 信息符合指定条件

只有满足条件的配置才会被加载。

2.3 创建 D-Bus 配置对象

配置匹配成功后，entity-manager 会在 D-Bus 上发布对应的设备信息。

其他服务可以通过这些对象了解：

• 当前平台有哪些设备
• 每个设备的名称是什么
• 设备属于哪个硬件部件
• 传感器使用哪个总线和地址
• 传感器有哪些阈值
• 风扇控制需要使用哪些参数

2.4 支持动态设备模型

设备模型不是全部硬编码在系统启动流程中，而是由配置和运行时探测结果共同决定。

当设备被发现、移除或配置发生变化时，相关 D-Bus 对象也可以随之变化。这种方式适合支持：

• 可插拔电源模块
• 多种主板型号
• 不同数量的风扇
• 可选传感器
• 不同硬件版本

3. entity-manager 的整体架构

entity-manager 的工作流程可以分为几个阶段：

读取 JSON 配置
↓
解析 Probe 条件
↓
匹配当前硬件
↓
创建 Entity 对象
↓
创建 Exposes 配置对象
↓
发布设备属性和关联关系
↓
通知其他 D-Bus 服务

其中：

• Entity 表示一个较大的硬件实体，例如主板、电源或处理器。
• Exposes 表示该实体对外提供的具体功能，例如温度传感器、电压传感器或风扇。
• Probe 用于判断当前配置是否适用于当前硬件。

4. Entity 与 Exposes

4.1 Entity

Entity 通常表示一个硬件设备或硬件区域，例如：

Main Board
CPU Board
Power Supply
Fan Board
Chassis

一个简单的 Entity 配置如下：

{
"Name": "Main Board",
"Type": "Board",
"Probe": "TRUE",
"Exposes": []
}

其中：

4.2 Exposes

Exposes 用于描述 Entity 对外提供的具体功能。

例如主板上有一个温度传感器：

{
"Name": "Main Board",
"Type": "Board",
"Probe": "TRUE",
"Exposes": [
{
"Name": "Board Temp",
"Type": "TMP75",
"Bus": 3,
"Address": 72
}
]
}

这里表示：

实体：Main Board
功能：Board Temp
设备类型：TMP75
I2C 总线：3
I2C 地址：0x48

因为 JSON 中的十进制 72 等于十六进制 0x48。

一个 Entity 可以包含多个 Exposes：

{
"Name": "Main Board",
"Type": "Board",
"Probe": "TRUE",
"Exposes": [
{
"Name": "Board Temp",
"Type": "TMP75",
"Bus": 3,
"Address": 72
},
{
"Name": "12V Input",
"Type": "ADM1272",
"Bus": 4,
"Address": 64
},
{
"Name": "Fan0",
"Type": "Fan",
"Bus": 5,
"Address": 32
}
]
}

这表示一个主板实体同时包含：

• 一个温度传感器
• 一个电压或功率监控设备
• 一个风扇设备

5. Probe 硬件匹配机制

Probe 是 entity-manager 配置中的重要部分，用于确认硬件是否存在。

5.1 固定匹配

最简单的方式是：

"Probe": "TRUE"

这表示配置始终有效，适用于平台硬件固定、无需额外探测的场景。

5.2 I2C 设备匹配

可以根据 I2C 总线和地址匹配设备：

{
"Name": "Board Sensor",
"Type": "Board",
"Probe": "xyz.openbmc_project.FruDevice({'BOARD_PRODUCT_NAME': 'ExampleBoard'})",
"Exposes": [
{
"Name": "Board Temp",
"Type": "TMP75",
"Bus": 3,
"Address": 72
}
]
}

具体 Probe 语法会随 OpenBMC 版本和平台配置方式有所差异，实际使用时需要与当前分支中的 entity-manager 解析规则保持一致。

5.3 FRU 信息匹配

很多平台会通过 FRU 信息区分硬件版本，例如：

BOARD_PRODUCT_NAME
BOARD_PART_NUMBER
PRODUCT_PRODUCT_NAME
PRODUCT_SERIAL_NUMBER

配置可以根据 FRU 属性进行匹配：

主板产品名称为 Board-A
电源型号为 PSU-1200
硬件版本为 Rev2

这样，同一个镜像就可以根据当前硬件自动选择不同配置。

5.4 组合匹配

复杂平台可能同时使用多个条件：

主板型号匹配
并且指定 I2C 设备存在
并且 FRU 版本正确

组合条件可以避免错误加载其他平台的传感器和设备配置。

6. 传感器建模

entity-manager 可以描述温度、电压、电流、功率和风扇转速等设备。

6.1 温度传感器

{
"Name": "CPU0 Temp",
"Type": "TMP75",
"Bus": 3,
"Address": 72
}

传感器服务根据该配置找到对应的硬件设备，然后创建 D-Bus 对象：

/xyz/openbmc_project/sensors/temperature/CPU0_Temp

6.2 电压传感器

{
"Name": "P12V",
"Type": "Voltage",
"Bus": 4,
"Address": 64,
"Channel": 0
}

对应的 D-Bus 路径可能为：

/xyz/openbmc_project/sensors/voltage/P12V

6.3 风扇传感器

{
"Name": "Fan0",
"Type": "Fan",
"Bus": 5,
"Address": 32,
"SensorNumber": 0
}

风扇相关数据可能包括：

• 当前转速
• 目标转速
• PWM 占空比
• 风扇存在状态
• 风扇故障状态

6.4 电源设备

电源模块通常不只提供一个传感器，而是同时提供：

• 输入电压
• 输出电压
• 输入电流
• 输出电流
• 输入功率
• 输出功率
• 温度
• 风扇转速
• 电源在位状态

因此，电源设备的建模通常比普通温度传感器复杂。

7. 阈值配置

传感器通常需要设置 Warning 和 Critical 阈值。

一个温度传感器配置示例如下：

{
"Name": "CPU0 Temp",
"Type": "TMP75",
"Bus": 3,
"Address": 72,
"Thresholds": [
{
"Direction": "greater than",
"Name": "upper warning",
"Severity": 0,
"Value": 70
},
{
"Direction": "greater than",
"Name": "upper critical",
"Severity": 1,
"Value": 85
}
]
}

配置含义如下：

当温度超过 70℃ 时，可以产生 Warning 告警；超过 85℃ 时，可以产生 Critical 告警。

阈值配置最终会映射到 D-Bus 接口，例如：

xyz.openbmc_project.Sensor.Threshold.Warning
xyz.openbmc_project.Sensor.Threshold.Critical

上层服务可以根据这些接口判断设备是否处于告警状态。

8. entity-manager 与 dbus-sensors 的关系

两者职责不同。

数据流可以表示为：

JSON 配置
↓
entity-manager
↓
D-Bus Entity / Configuration 对象
↓
dbus-sensors 读取配置
↓
访问 hwmon、I2C、PMBus 等接口
↓
创建 Sensor.Value 对象
↓
bmcweb、IPMI、风扇控制读取

因此，entity-manager 本身通常不会直接执行以下操作：

• 周期性读取 temp1_input
• 读取风扇转速
• 计算 PID 控制输出
• 提供 Redfish HTTP 接口
• 生成完整的 Web 页面

这些工作由其他服务完成。

9. entity-manager 与 D-Bus

entity-manager 启动后，会在 D-Bus 上提供设备模型。

在 D-Bus 中，设备配置对象通常位于类似路径：

/xyz/openbmc_project/inventory/system/board/Main_Board

或者：

/xyz/openbmc_project/configurations/Main_Board

具体路径取决于 OpenBMC 版本和平台实现。

可以通过以下命令查看 entity-manager 服务：

busctl list | grep -i entity

查看 D-Bus 对象树：

busctl tree xyz.openbmc_project.EntityManager

其他服务通常通过 ObjectMapper 查询对象，而不是直接假设某个固定服务名：

ObjectMapper
↓
根据对象路径查询提供者
↓
获得服务名称和接口列表

这种机制让上层服务不需要硬编码底层服务名称，提高了平台适配能力。

10. 设备关联关系

设备建模不仅要描述设备本身，还需要建立设备之间的关系。

例如：

温度传感器 → CPU0
风扇 → 风扇区域
电源传感器 → PSU0
主板 → Chassis

OpenBMC 通过 Association 接口表示这些关系。

示意结构如下：

/xyz/openbmc_project/sensors/temperature/CPU0_Temp
│
└── related_to
│
▼
/xyz/openbmc_project/inventory/system/chassis/motherboard/cpu0

关联关系会影响：

• Redfish 资源组织
• 传感器在 WebUI 中的归属
• 日志中故障设备的定位
• 风扇区域和温度传感器的绑定
• 电源模块状态展示

如果传感器数值能够正常读取，但 Redfish 中没有出现在预期的设备下，通常与设备关联关系有关。

11. 从 Entity 到 Redfish

用户访问 Redfish 接口时，bmcweb 不会直接读取 entity-manager 的 JSON 文件，而是通过 D-Bus 查询已经创建的对象。

完整流程如下：

entity-manager JSON
↓
创建 Entity 配置对象
↓
dbus-sensors 创建 Sensor 对象
↓
ObjectMapper 提供对象查询
↓
bmcweb 查询 Sensor.Value
↓
转换为 Redfish 属性

例如：

D-Bus:
/xyz/openbmc_project/sensors/temperature/CPU0_Temp
Value = 52.0
Unit = xyz.openbmc_project.Sensor.Value.Unit.DegreesC

Redfish:
Reading = 52.0
ReadingUnits = "Cel"

因此，Redfish 数据的来源通常可以追溯到 D-Bus Sensor 对象，而 D-Bus Sensor 对象又可以追溯到 entity-manager 的硬件建模配置。

12. 配置文件与 Yocto 集成

平台配置通常位于对应的 OpenBMC layer 中，例如：

meta-xxx/recipes-phosphor/configuration/
meta-xxx/recipes-phosphor/entity-manager/

配置文件需要通过 BitBake 配方安装到目标镜像中。

一个简化的配方片段如下：

SRC_URI += "file://config.json"

do_install:append() {
install -d ${D}${datadir}/entity-manager/configurations
install -m 0644 ${WORKDIR}/config.json \\
${D}${datadir}/entity-manager/configurations/
}

实际路径会根据 OpenBMC 分支和配方实现有所不同。

除了 JSON 文件，还需要确认：

• entity-manager 已加入镜像
• 对应的 dbus-sensors 服务已加入镜像
• 相关 Linux 内核驱动已启用
• 设备树包含硬件节点
• systemd 服务能够在启动时运行
• 配置文件没有被其他 layer 覆盖

13. entity-manager 的设计特点

13.1 配置与代码分离

硬件差异主要通过配置文件表达，减少了平台定制时的代码修改。

13.2 支持多平台复用

同一套传感器服务可以处理多个平台，只需要提供不同的硬件配置。

13.3 便于动态建模

硬件是否存在由运行时探测结果决定，适合电源模块、风扇和扩展设备等场景。

13.4 依赖统一 D-Bus 接口

底层硬件类型不同，但上层可以通过统一的 D-Bus Sensor 接口访问。

13.5 适合复杂硬件关系

通过 Entity、Exposes 和 Association，可以表达主板、CPU、电源、风扇和传感器之间的层次关系。

14. 添加一个传感器的整体流程

以新增一个 I2C 温度传感器为例，整体过程如下：

1. 确认硬件连接
↓
2. 添加设备树节点
↓
3. 启用 Linux 内核驱动
↓
4. 确认 hwmon 节点生成
↓
5. 编写 entity-manager JSON
↓
6. 配置传感器名称和阈值
↓
7. 配置 Entity 与 Inventory 关系
↓
8. 启用对应 dbus-sensors 服务
↓
9. 创建 D-Bus Sensor 对象
↓
10. 由 bmcweb 和其他服务使用

这一流程体现了 OpenBMC 的分层设计：

内核负责访问硬件
entity-manager 负责描述硬件
dbus-sensors 负责发布数据
上层服务负责使用数据

15. 总结

entity-manager 是 OpenBMC 设备建模体系中的核心组件之一。它不直接替代 Linux 驱动，也不负责提供 Web 接口，而是通过 JSON 配置文件把平台硬件描述为统一的运行时对象。

其核心结构可以概括为：

Entity
├── Name
├── Type
├── Probe
└── Exposes
├── Sensor
├── Threshold
├── Bus
├── Address
└── Association

在完整的 OpenBMC 架构中：

• Linux 内核负责提供底层硬件访问能力。
• entity-manager 负责识别和描述平台设备。
• dbus-sensors 负责读取数据并创建标准 Sensor 对象。
• D-Bus 负责在各组件之间传递设备信息。
• bmcweb、IPMI、风扇控制和日志服务负责使用这些数据。

掌握 entity-manager 的配置结构和运行机制，是理解 OpenBMC 传感器、风扇、电源和 Redfish 设备管理的基础。