# lb_hwmon

**Repository Path**: litebmc/lb_hwmon

## Basic Information

- **Project Name**: lb_hwmon
- **Description**: litebmc hardware monitor
- **Primary Language**: C
- **License**: LGPL-2.1
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2024-12-04
- **Last Updated**: 2026-05-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## 说明

lb_hwmon 是 LiteBMC 的硬件监控服务，基于扁平化设备树（FDT）实现设备自动发现。服务通过解析 Linux 内核的设备树文件（`/sys/firmware/fdt`）自动发现硬件设备，并为每个设备创建对应的 DBus 对象，供上层业务查询和监控。

### 设备树与设备自发现

[Linux and the Devicetree](https://docs.kernel.org/devicetree/usage-model.html)

DeviceTree 用于描述 Linux 硬件拓扑和驱动配置，是设备驱动机制和驱动配置策略的解耦方案。设备树源文件（`.dts`）经 `dtc` 编译为二进制文件（`.dtb`），Linux 系统启动时读取 dtb 文件获取硬件拓扑结构。

DeviceTree 使用节点表示设备，每个设备通过 `compatible` 属性声明兼容的驱动，内核据此加载对应驱动。设备节点还包含驱动初始化所需的寄存器地址、中断、状态等关键信息。

如下是某个触摸屏 I2C 驱动芯片配置示例：

```
&i2c2 {
    status = "okay";

    ts@5a {
        compatible = "cst2xxse";
        reg = <0x5a>;
        irq-gpio = <&gpio0 RK_PB4 IRQ_TYPE_LEVEL_LOW>;
        status = "okay";
    };
};
```

lb_hwmon 正是基于这些 dtb 信息实现设备自发现。

## 功能实现

### 核心工作流程

1. 服务启动后，读取并解析 `/sys/firmware/fdt` 中的 dtb 二进制文件
2. 处理 `/aliases` 节点，建立别名与设备路径的映射关系
3. 递归遍历所有设备节点，提取属性信息（compatible、reg、status、自定义属性等）
4. 为每个已启用的设备创建 DBus 对象，对象路径映射设备树路径
5. 遍历所有已创建的 DBus 对象，通过 `FdtDiscovered` 信号通知业务驱动

### 设备状态处理

- `status = "okay"` 或无 `status` 属性的设备视为**启用**，正常创建 DBus 对象
- `status = "disabled"` 的设备视为**禁用**，`okay` 字段置为 `FALSE`，仍创建对象但标记状态
- `status` 属性类型不正确（如非字符串）时，默认视为启用

### 别名与总线 ID

对于 I2C、SPI 等总线设备，别名（alias）用于标识总线 ID。DeviceTree 通过 `/aliases` 节点记录别名映射：

```
aliases {
    i2c0 = &i2c0;
    i2c1 = &i2c1;
    serial0 = &uart0;
    spi0 = &spi0;
};
```

别名解析规则：
- `i2c0` 表示 ID 为 0 的 I2C 总线，对应设备 `/dev/i2c-0`
- `serial3` 表示 ID 为 3 的串口
- 别名解析逻辑与内核 `of_alias_scan` 函数一致

服务解析别名后，将其用于 DBus 对象路径的构建。例如 `/i2c@ff140000/eeprom@50` 在别名为 `i2c1` 时，映射为 `/com/litebmc/fdt/i2c1/eeprom_50`。I2C 多路复用器（mux）的子总线同样通过别名映射，如 `i2c36`、`i2c37` 等。

### 属性解析

服务从设备树节点提取以下属性：

| 属性 | 说明 |
|------|------|
| `compatible` | 兼容字符串数组，用于驱动匹配 |
| `status` | 设备状态，"okay"/"disabled" |
| `reg` | 寄存器地址，按大端序 32 位解析 |
| `#address-cells` | 子节点地址单元数 |
| `#size-cells` | 子节点大小单元数 |
| 自定义属性 | 作为原始字节数组传递 |

### DBus 对象

服务在 DBus 上以 `com.litebmc.hwmon` 为名创建对象，根路径为 `/com/litebmc/fdt`。每个设备树节点对应一个 DBus 对象，对象实现了 `com.litebmc.Fdt` 接口，包含以下设备信息：

- `path`: 设备树原始路径
- `compatible`: 兼容字符串列表
- `okay`: 设备启用状态
- `reg`: 寄存器地址数组
- `address_cells` / `size_cells`: 地址和大小单元数
- `alias`: 别名信息
- `nodes`: 子节点 DBus 路径列表
- `props`: 自定义属性列表（名称 + 原始值）

## 构建与安装

### 依赖

通过 Conan 2.x 管理依赖：

| 依赖 | 版本要求 | 说明 |
|------|----------|------|
| `libfdt` | 1.7.0 | 设备树解析库 |
| `lb_core` | >=0.7.0 <0.8.0 | LiteBMC 核心框架 |
| `lb_fdt-server` | >=1.0.4 <2.0.0 | DBus 服务端接口 |
| `dtc` | 1.7.0 | 设备树编译器（构建工具） |

### 常用构建命令

```bash
# 默认构建
lbk build

# 启用测试包构建
lbk build -o test=True

# 禁用 DBus 会话总线服务单元（仅安装系统总线）
lbk build -o enable_dbus_session=false

# 同时指定多个选项
lbk build -o test=True -o enable_dbus_session=false

# 运行测试
lbk test
```

### 构建选项

通过 `lbk build -o <选项>=<值>` 传递，定义在 `metadata/package.yml` 中：

| 选项 | 默认值 | 可选值 | 说明 |
|------|--------|--------|------|
| `test` | false | true/false | 启用测试包编译 |
| `gcov` | false | true/false | 启用覆盖率构建 |
| `enable_dbus_system` | true | true/false | 安装 DBus 系统总线服务单元 |
| `enable_dbus_session` | true | true/false | 安装 DBus 会话总线服务单元 |

### 安装布局

```
opt/litebmc/apps/lb_hwmon/
  └── lb_hwmon                           # 主可执行文件

usr/lib/systemd/system/
  └── lb_hwmon@.service                  # Systemd 模板单元（接受 system/session 参数）
```

服务以 systemd 服务运行，支持 `lb_hwmon@system` 和 `lb_hwmon@session` 两种实例。

## 测试

测试使用 `test_package/test.dts` 定义的设备树，覆盖以下场景：

- LM75A 温度传感器发现与属性验证
- EEPROM 设备发现与自定义属性（pagesize）验证
- I2C 多路复用器（mux）层级设备发现
- 多 compatible 设备处理
- disabled 设备状态验证
- status 属性格式异常处理
- reg 与 address-cells/size-cells 不匹配场景

## 许可证

GNU Lesser General Public License v2.1 (LGPL-2.1)