devmon

验证说明：本文档是 devmon 组件构建与测试的唯一指导文档，验证流程请严格按本文档执行。docs/ 目录下的文档为特性说明文档，不涉及构建流程。本组件仅支持 Ubuntu 24.04 LTS，openEuler、CentOS、Debian 等其他系统均不支持，不要尝试使用其他镜像替代。

devmon 是 openUBMC 的设备监控组件，提供硬件设备驱动基础框架和特定设备适配器实现（如 PCIe 网卡适配器），用于监控和管理各种硬件设备。

---

目录

• 仓库地址
• 系统要求
• 环境依赖
• 构建
  • 获取组件代码
  • 组件级构建
  • 构建参数说明
• 测试
• 开发者调试
• 客户定制 CSR
• 项目结构
• 许可证

---

仓库地址

https://gitcode.com/openUBMC/devmon

---

系统要求

项目	要求
操作系统	Ubuntu 24.04 LTS（仅支持此版本）
芯片架构	x86-64（amd64）
Python	>= 3.10（init.py 运行依赖）

bingo、Conan 等构建工具由 init.py 自动安装，无需手动准备。推荐使用 Docker 容器进行构建，可使用以下镜像快速启动开发环境：

docker pull swr.cn-north-4.myhuaweicloud.com/openubmc/ubuntu:24.04.2_26.06

---

环境依赖

构建 devmon 前需完成 openUBMC 开发环境初始化（安装 bingo、Conan、Node.js、配置 Conan 远程仓库等）。完整初始化步骤和常见问题排查请参阅 openUBMC 构建指导书，该文档包含容器环境搭建、init.py 执行、Conan 登录验证等全部操作说明。

禁止手动安装 bingo 和 Conan：手动安装（如 pip install conan）会导致 Conan 远程仓库认证失败，bingo build 无法拉取依赖包。所有构建工具必须通过 manifest 仓库的 init.py 流程一键安装。

---

构建

获取组件代码

前提：已完成 环境依赖 中的 init.py 初始化流程，bingo 和 conan 命令可用。

# 手动从 GitCode clone
cd /home/workspace
git clone https://gitcode.com/openUBMC/devmon.git

组件级构建

进入 devmon 组件目录后，使用 bingo 执行构建：

cd /home/workspace/devmon

# 默认 dev 阶段构建
bingo build --stage=dev

# 构建并发布到 stable 阶段
bingo build --stage=stable

# Release 类型构建
bingo build --stage=dev -bt release

构建参数说明

bingo build [-h] [-bt BUILD_TYPE] [--stage STAGE] [-u] [-r REMOTE] [--conan2] [-nc] [-o OPTIONS] [--user USER] [-wb] [--ccache]

参数	说明	默认值
-bt / --build_type	构建类型，可选 debug、release	debug
--stage	包发布阶段，可选 dev、pre、rc、stable	dev
-u / --upload	上传组件包到 Conan 仓库	—
-r / --remote	Conan 仓库别名	—
--conan2	强制使用 Conan2 构建组件	—
-nc / --no_cache	强制更新 Conan 缓存依赖	—
-o / --options	定义组件选项值	—
--user	指定 Conan 包的 user 字段	openubmc
-wb / --without_build	不强制源码构建组件自身	—
--ccache	使用 ccache 加速 C/C++ 编译	—

devmon 支持的组件选项（-o 参数）：

选项	说明	默认值
asan	启用 AddressSanitizer	False
gcov	启用代码覆盖率	False
enable_luajit	启用 LuaJIT	False
unidev	启用统一开发模式	False

---

测试

使用 bingo test 运行各类测试，需加 -jit 参数，否则测试会失败：

# 运行单元测试
bingo test -ut -jit

# 运行集成测试
bingo test -it -jit

# 运行 mock 测试
bingo test -mt -jit

# 运行 fuzz 测试
bingo test -ft -jit

# 运行单元测试并指定过滤
bingo test -ut -jit -f <filter>

# 运行单元测试并启用 ASAN
bingo test -ut -jit -as

# 运行 clang-tidy 静态检查
bingo test -ct -jit

常用测试参数：

参数	说明
-ut	启用单元测试
-it	启用集成测试
-mt	启用 mock 测试
-ft	启用 fuzz 测试
-f	测试过滤
-jit	需加此参数，否则测试会失败
-as	启用 AddressSanitizer
-ct	启用 clang-tidy 静态检查（详见 CONTRIBUTING.md）

---

开发者调试

• 添加网卡：

  busctl --user call bmc.kepler.devmon /bmc/dev bmc.dev AddDevice sa{sv} "../tests/tests_data/csr/14140130_19e50222_19e500a1.sr" 3 Position i 2 SystemId i 1 Slot i 2
  

---

客户定制 CSR

将定制文件放到 /opt/bmc/extend/{customer}/sr/，文件名与部件身份对应并带 _cust.sr 后缀（例如 14140130_19e50222_19e500a1_cust.sr）。加载时会与基础 CSR 的 Objects 合并：同名对象合并属性，新对象直接加入。

删除软件对象时，在定制 CSR 顶层增加 Customization dict，其中 DeletedObjects 为要删除的对象名数组：

{
  "Objects": {
    "PCIeNicCard_1": {
      "bmc.dev.PCIeDevice": {
        "DeviceName": "hisi_1822"
      }
    }
  },
  "Customization": {
    "DeletedObjects": ["OpticalModule_0"]
  }
}

表示合并或覆盖 PCIeNicCard_1，并删除 OpticalModule_0。

仅支持删除软件对象，例如 PCIeNicCard_1、NetworkPort_0、OpticalModule_0、SRUpgrade_1。不要用于删除硬件或拓扑对象，例如 I2c_8、Eeprom_1、Connector_1、Scanner_SerdesLom1Pres。

定制索引 index.json

上面的文件名全匹配要求每个部件都有一个同名定制文件。当一批部件共用同一份定制时，可以在 /opt/bmc/extend/{customer}/sr/index.json 里按文件名前缀或后缀把它们指向同一个定制文件。

顶层 object 的 Rules 是规则数组，每条规则由 Rule、Pattern 和 MatchedFile 组成：

{
  "Rules": [
    { "Rule": "Prefix", "Pattern": "14100513", "MatchedFile": "14100513_common_cust.sr" },
    { "Rule": "Suffix", "Pattern": "_19e500a1", "MatchedFile": "nic_tail_cust.sr" },
    { "Rule": "Prefix", "Pattern": "1414", "MatchedFile": "legacy" }
  ]
}

• 被匹配的是部件身份名，即不含扩展名的 {Bom}_{Id}_{AuxId}（无 Bom 时为 {Id}[_{AuxId}]）， 例如 14100513_19e50222_19e500a1。先用带 Bom 的名称查一次，未命中再用不带 Bom 的名称查。
• Rule 只支持 Prefix 和 Suffix，大小写不敏感。文件名全匹配不需要登记到索引，直接放 {name}_cust.sr 即可。
• MatchedFile 是同目录下的定制文件名，不以 .sr 结尾时补 _cust.sr，上例 legacy 实际指向 legacy_cust.sr。不能含 /、\ 或 ..。多条规则可以指向同一个 MatchedFile。
• 缺字段、Pattern 为空、Rule 取值不支持的条目会被跳过并打告警日志，不影响其余规则。

命中优先级是全序的，一次定制处理只会命中一条规则：

1. Prefix 优先于 Suffix
2. 同类别内 Pattern 更长者胜，例如 abcd_ 胜过 abc_
3. 同类别同 Pattern 指向不同 MatchedFile 属配置错误，取字典序小者并打告警日志

索引只对客户定制层生效，机型定制层（/opt/bmc/extend/{platform_id}_{board_id}/sr/）不读索引。 index.json 缺失、解析失败、缺少 Rules 数组、无规则命中，或命中的定制文件读取失败时， 都会退化为上面的文件名全匹配，并打印可定位的日志。索引按目录只加载一次并缓存，匹配复杂度为 O(名称长度)，与规则条数无关。

---

项目结构

devmon/
├ include/              # 公共头文件
├ src/                  # 源码实现
├ libs/                 # 内部库
├ mds/                  # MDS 模型定义（model.json, service.json）
├ test/                 # 测试相关
├ tests/                # 测试数据与用例
├ scripts/              # 构建与辅助脚本
├ stub/                 # Stub 文件
├ subprojects/          # Meson 子项目
├ dist/                 # 分发配置
├ docs/                 # 特性说明文档（不涉及构建流程）
├ conanfile.py          # Conan 构建定义
├ conanbase.py          # Conan 基类
├ meson.build           # Meson 构建定义
├ meson_options.txt     # Meson 构建选项
├ config.json           # 配置文件
├ whitelist.json        # 白名单配置
├ LICENSE               # Mulan PSL v2 许可证
├ CHANGELOG             # 变更日志
└ README.md             # 本文件

---

许可证

本项目基于 Mulan PSL v2 许可证开源。详情请参阅：http://license.coscl.org.cn/MulanPSL2