component_drivers 部件驱动
版本信息
| 项目 | 内容 |
|---|---|
| 组件版本 | 1.2.595 |
| 首发版本 | 1.2.15(2026-01-25,组件 CHANGELOG 最早记录) |
| 文档作者 | openUBMC 社区 |
| 最后更新 | 2026-11-10 |
| 许可证 | Mulan PSL v2 |
| 组件类型 | application |
1. 组件概述
1.1 组件简介
component_drivers 是 openUBMC 的部件驱动插件仓:把"怎么访问一颗芯片、一条总线、一块 PCIe 卡"编译成一批 .so,由宿主进程(单层/CSR2 下是 devmon,unidev/CSR1 下是 hwproxy)按 SR 配置 dlopen 装载、创建对象并挂到设备树。组件本身不解析 SR、不含主程序、不含资源树服务。
对外提供两类接口:
| 接口类别 | 形式 | 说明 |
|---|---|---|
| 设备树接口 | bmc.dev.*(/bmc/dev/**) | 驱动对象注册到宿主服务后的 D-Bus 接口,上层组件与调试脚本访问的面(§2) |
| 驱动 ABI | C 接口 register_device_driver + device_driver_t | 宿主装载驱动用的二进制契约(§2.1) |
unidev(CSR1)构建下,同一批内部件还会被 Csr1* 系列驱动壳包装成 bmc.kepler.* 接口用于存量机型兼容(差异见 §2.7)。
1.2 解决什么问题
- 硬件差异收敛:时序、寄存器语义、厂商报文从业务组件剥离,业务组件只依赖
bmc.dev.*。 - 两代平台并存:CSR1(
bmc.kepler.*)与 CSR2(bmc.dev.*)共用同一套内部件(libInternal.so),迁移只换对象壳。 - 按单板裁剪:用构建选项把不需要的部件驱动、协议库、CSR1 兼容层裁出包。
- 可独立测试:每个驱动
.so都能单独dlopen做 ABI 测试,不依赖真硬件。
1.3 核心功能
| 序号 | 功能 | 说明 |
|---|---|---|
| 1 | 驱动插件 ABI | .so 导出 register_device_driver(),返回一张或多张 device_driver_t;宿主按 Unit.Type(主设备)或对象名前缀(通用对象)选表项,按 Unit.Compatible 选 .so |
| 2 | 内部总线与器件层 | drivers/internal/ 编成 libInternal.so:device_manager 单例 + 工厂表(19 类总线、17 类器件)+ 统一读写入口 |
| 3 | 通用对象驱动 | Chip/Bus/Accessor/Scanner/去抖/Connector,由 SR 直接配置 |
| 4 | 部件驱动 | PCIe 网卡(10 家)、GPU(6)、RAID(1)、NVMe(4)、PSU(5 个型号目录)、RS485 风扇、JBOG、SSU;一个 .so 通常注册 1~4 个 device_name(PSU 与 SMC 风扇当前未接入构建,见 §4.4) |
| 5 | 协议库 | SMBus/PMBus/MCTP/NCSI/PLDM/NVMe-MI/IPMB/IMU/LLDP/CAN/电机械/SSU OOB,编成 usr/lib64/libdev_*.so |
| 6 | 裁剪与契约 | 5 个裁剪选项(见 §4.4);契约以 dmc/*.json 为单一事实源,gen/ 为据此生成的接口与对象代码 |
1.4 关键术语表
| 术语 | 说明 |
|---|---|
| SR / CSR | 设备自描述记录,含 FormatVersion、Unit、ManagementTopology、Objects;宿主解析后按对象建驱动实例 |
Unit.Type / Unit.Compatible | 主设备的 device_name / 决定装载哪个 .so(["cx6"] → libcx6.so) |
| Position | 对象组位置,逐级拼接;最终对象名 = <SR 对象名>_<Position> |
| 内部件 | libInternal.so 里的 chip_base/bus_base,被对象壳(drivers/chip/**、drivers/bus/**)绑定使用 |
| 设备树 / 资源树 | 设备树(bmc.dev.*,/bmc/dev/**)是南向驱动对象;资源树(bmc.kepler.*)是上层业务对象 |
| DMC | Device Management Contract,dmc/intf(接口)+ dmc/path(对象路径与接口组合) |
| ABI v1 / v2 | CSR1(<5.00,libCsr1 前缀的 .so 优先)与 CSR2(>=5.00,lib<Name>.so)两套装载口径 |
1.5 外部交互边界图
说明
驱动 .so 装到 /opt/bmc/drivers,内部件与协议库装到 /usr/lib64;bmc.kepler.* 一路仅在 unidev=true(FormatVersion < 5.00)时存在,两代差异见 §2.7。
2. API 使用说明与示例
本节按对象类别组织。描述范围如下,未展开的部分按表内指引查阅契约,避免与 dmc/ 双份维护:
| 范围 | 内容 |
|---|---|
| 完整描述(属性 + 方法 + 签名 + 调试示例) | §2.2 bmc.dev.Chip、§2.3 bmc.dev.Bus、§2.4 Accessor/Scanner/去抖、§2.5 PCIeDevice/PCIeCard |
| 只给接口清单,不逐项展开 | §2.6 家族业务接口(网卡/光模块/GPU/内存/电源/风扇/NVMe/RAID/SSU):只列接口名与关键成员 |
| 本篇不涉及 | ABI 版本选择与装载策略(见《devmon》)、CSR1 资源树接口(见 devmon.md §2.5~§2.6)、协议报文格式(见 libraries/** 源码)、构建产物细节(见组件仓 README.md) |
对象路径形态与所属小节:
| 对象类别 | 路径形态 | 接口 | 小节 |
|---|---|---|---|
| 器件(Chip) | 相对路径,如 Complex/${object_name}、PowerMeter/${object_name} | bmc.dev.Chip 及衍生 | §2.2 |
| 总线(Bus) | 相对路径 ${object_name} | bmc.dev.Bus 及变体 | §2.3 |
| 采集(Accessor / Scanner / 去抖) | 绝对路径,如 /bmc/dev/Scanner/${object_name} | bmc.dev.Accessor、bmc.dev.Scanner、bmc.dev.Debounce.* | §2.4 |
| 部件(卡 / 电源 / 风扇 / 模组) | 主设备绝对路径 + 子设备相对路径 | bmc.dev.PCIeDevice/PCIeCard 及家族接口 | §2.5、§2.6 |
服务名固定为 bmc.kepler.devmon(CSR2,/bmc/dev/**);unidev 下同名对象出现在 bmc.kepler.hwproxy(/bmc/kepler/**),方法签名带 a{ss} 上下文首参。设备树(bmc.dev.*)方法一般不带 a{ss}。
注意
写硬件的命令(SetAccessibility、SetLockStatus、BitIOWrite/BlockIOWrite、RawAccessWrite、Fans.SetPWM 等)会直接作用到器件与总线,禁止访问或写错寄存器都可能中断采样、影响业务;仅限维护窗口或测试环境执行。
2.0 环境与能力确认
本节命令适用于 1.2.15 及之后的组件版本;接口层面的首发版本见各能力节的「功能说明」表。同一接口在不同架构(单层/unidev)、不同裁剪选项与不同驱动版本上可支持性不同,先确认驱动装没装、对象在不在,并把本节要用的对象路径赋给变量(后续各节的命令直接引用这些变量):
SVC=bmc.kepler.devmon
busctl --user tree $SVC | grep -E "Chip|Bus|Scanner|Accessor|PCIe|Fan|PowerSupply"
# 按上一步输出取对象(同类对象取第一个;取不到则变量为空,跳过相关命令)
CHIP=$(busctl --user tree $SVC | grep -m1 -E "/Chip_")
BUS=$(busctl --user tree $SVC | grep -m1 -E "/I2c_|/Hisport_")
SCAN=$(busctl --user tree $SVC | grep -m1 -E "/Scanner/")
CARD=$(busctl --user tree $SVC | grep -m1 -E "/PCIeNicCard/|/PCIeGpuCard/")
# 驱动目录与一键收集目录(收集包未生成时 DUMP 为空,先执行收集再取)
DRVDIR=/opt/bmc/drivers
DUMP=$(dirname "$(find / -maxdepth 6 -name drivers_load_info.csv 2>/dev/null | head -1)")
# 架构判定:0 = 单层包(无 CSR1 兼容驱动),非 0 = unidev
ls $DRVDIR | grep -c "^libCsr1"busctl --user tree 输出形如(逐行一个对象路径,末段即对象名):
/bmc/dev/Systems/1/PCIeNicCard/PCIeNicCard_1_01
/bmc/dev/Systems/1/PCIeNicCard/PCIeNicCard_1_01/NicPort/1
/bmc/dev/Scanner/Scanner_Fan1_Presence_012.1 驱动插件 ABI(C 接口)
功能说明
每个驱动 .so 导出唯一符号 register_device_driver,宿主 dlopen 后调用它拿到设备表,再按表项创建对象。这是"驱动插件"的对外契约,不是 D-Bus 接口,但排障时必须先确认它生效。
| 项 | 内容 |
|---|---|
| 接口名 | register_device_driver(导出符号,非 D-Bus 接口) |
| 头文件 | include/devmon/driver_abi.h(宿主侧另存一份,字段一致) |
| 装载方 | devmon(CSR2)/ hwproxy(unidev,libCsr1 前缀的 .so 优先) |
| 文件位置 | /opt/bmc/drivers/lib<Name>.so |
| 首发版本 | 1.2.15 |
| 废弃状态 | 正常可用 |
参数说明
符号与结构
| 符号 / 类型 | 声明 | 说明 |
|---|---|---|
register_device_driver | status_t register_device_driver(device_driver_t** device_driver, uint8_t* count) | 回填设备表与数量;返回非 0 视为装载失败 |
device_driver_t | { device_name, ctor, init, start, stop, dump } | device_name 必须与 SR 的 Unit.Type 或对象名前缀一致;dump 可省略 |
回调说明
| 回调 | 签名 | 宿主调用时机 | 说明 |
|---|---|---|---|
ctor | handle ctor(void* service, const char* object_name) | 创建对象壳 | 必须 set_service + set_object_name,失败返回 nullptr |
init | status_t init(handle, void* csr_object, void* connector) | 上树前 | 传 SR 对象属性字典与 connector 字典;解析配置、绑定内部件 |
start / stop | status_t start(handle) / status_t stop(handle) | 主设备注册后 / 卸载回滚 | 起停周期任务;子设备与通用对象只会有 init,不会被 start |
dump | const char* dump(handle) | 一键收集 | 返回诊断文本,可为 nullptr |
返回值与异常
| 返回值 / 错误 | 含义 | 触发条件 | 处理建议 |
|---|---|---|---|
0 STATUS_OK | 成功 | 正常 | 无 |
1 STATUS_ERROR | 通用失败 | init 解析失败、内部件绑定失败 | 查同段异常与 SR 字段 |
2 STATUS_NOT_FOUND | 依赖对象不存在 | 总线/器件/引用对象缺失 | 核对拓扑与对象名 |
3 STATUS_INVALID_ARG | 参数非法 | 空 CSR、缺必填字段 | 对照 §4.3 字段约定 |
4 STATUS_NOT_IMPLEMENTED | 能力未实现 | 该型号未适配或被裁剪 | 查驱动实现与 §4.4 |
5~7 | 超时 / 忙 / 无内存 | 硬件无响应、通道被锁、分配失败 | 见 §6.3 |
应用场景
现场确认驱动是否被装载、新增驱动后验证符号与表项、定界"对象不上树"时区分装载失败与 init 失败。
限制条件
- 一个
.so可注册多张表项,但device_name在同一.so内不能重复; - 回调里抛 C++ 异常不是契约行为,必须自己
catch后转成status_t; .so装载后被宿主按"驱动名 + abi 版本"缓存,替换文件不等于重载。
调试示例
命令行调试
# 1) 导出符号:能打印出 register_device_driver 即为合格驱动
nm -D $DRVDIR/libPca9545.so | grep register_device_driver # 输出:0000000000012345 T register_device_driver
# 2) 设备名:应与 SR 里的对象类名一致
strings $DRVDIR/libPca9545.so | grep -x "Pca9545" # 输出:Pca9545
# 3) 依赖是否齐全:无输出表示依赖齐;有 "not found" 则 dlopen 必失败
ldd $DRVDIR/libPca9545.so | grep "not found"
# 4) 宿主装载结果(CSV 表头 + 每驱动一行,失败行有 error 列)
cat $DUMP/drivers_load_info.csv2.2 器件对象(bmc.dev.Chip 及其衍生)
功能说明
所有器件壳都实现 bmc.dev.Chip:把 SR 里的地址、超时、重试参数同步到内部件,并暴露位/块读写与访问控制能力。器件对象使用相对路径,挂在父节点(总线或 Mux)下。
| 项 | 内容 |
|---|---|
| 接口名 | bmc.dev.Chip(衍生:bmc.kepler.Chip.BlockIO、bmc.dev.Chip.SelfDescriptionRecord、Chip.PowerMeter.Ina、Chip.Pca9544、Chip.Pca9545、Chip.JtagTarget) |
| 服务名 | bmc.kepler.devmon |
| 对象路径 | Complex/${object_name}(通用 Chip)、${object_name}(Pca954x/Cpld/Eeprom/Smc/Vrd 等)、PowerMeter/${object_name}(Ina) |
| 首发版本 | 1.2.15 |
| 废弃状态 | 正常可用 |
参数说明
属性参数说明
| 属性名 | 类型 | 读写 | 说明 | 取值范围 |
|---|---|---|---|---|
| Address | U32 | RW | 器件地址(I2C 从地址等) | I2C 0x00~0x7F |
| OffsetWidth / AddrWidth | U8 | RW | 偏移 / 地址字节数 | OffsetWidth 0~4,AddrWidth 按手册 |
| WriteTmout / ReadTmout | U32 | RW | 读写超时,单位 ms | >0 |
| RwBlockSize | U8 | RW | 单次块读写上限 | 按总线能力 |
| WriteInterval / ReadInterval | U8 | RW | 读写间隔,单位 ms | 0~255 |
| WriteRetryTimes / ReadRetryTimes / DrvWriteDelay | U8 | RW | 读写重试次数 / 写后延时(ms) | 0~255 |
| HealthStatus | U8 | RW | 健康状态 | 0 访问正常、1 访问失败 |
| HealthStatusValidity | Boolean | RO | HealthStatus 是否有效 | true、false |
| PowerStatus / SelfTestResult | U8 | RO | 上电状态 / 自检结果 | 器件定义 |
| LockStatus | U8 | RO | 锁状态 | 0 未锁定、1 已锁定 |
| ChipType | String | RO | 器件类型名 | Chip、Pca9545、Smc 等 |
方法参数说明
| 方法名 | D-Bus 签名 | 入参 | 出参 | 说明 | 取值范围 |
|---|---|---|---|---|---|
| BitIORead | uyu | Offset: U32、Length: U8、Mask: U32 | OutData: ay | 读后按 Mask 取值 | Length 仅 1/2/4 |
| BitIOWrite | uyuay | Offset: U32、Length: U8、Mask: U32、InData: ay | 无 | 读-改-写 | 同上 |
| BlockIORead | uu | Offset: U32、Length: U32 | OutData: ay | 连续块读 | 受 RwBlockSize 限制 |
| BlockIOWrite | uay | Offset: U32、InData: ay | 无 | 连续块写 | 同上 |
| BlockIOWriteRead | ayu | InData: ay、ReadLength: U32 | OutData: ay | 写后读(扩展读) | 见器件实现 |
| BlockIOComboWriteRead | uayuu | WriteOffset: U32、WriteBuffer: ay、ReadOffset/ReadLength: U32 | OutData: ay | 指定读写偏移的组合事务 | 同块读/块写 |
| RawAccessRead / RawAccessWrite | a{sv} | Request: a{sv} | OutData: ay / 无 | 裸访问,按请求字典描述时序 | 键含义见器件实现 |
| SetAccessibility | bq | Status: Boolean、DisableDuration: U16 | 无 | false 禁止该器件访问,到期自动恢复 | 时长 1~1800 秒 |
| SetLockStatus | yu | OpType: U8、LockTime: U32 | ResultCode: U8 | 0 解锁、1 加锁 | 加锁 ≤ 30 分钟 |
说明
SetLockStatus 的上下文由框架从请求注入,表中列出的是业务参数;所有方法签名以 busctl --user introspect 输出为准。
衍生接口要点
| 接口 | 关键成员 | 用途 |
|---|---|---|
bmc.kepler.Chip.BlockIO | PluginRequest(Context, PluginName, Cmd, Params)、PluginRequestEx(...)、RawAccessRead/Write | 加载器件插件执行私有命令 |
bmc.dev.Chip.SelfDescriptionRecord / Chip.PowerMeter.Ina | FormatVersion/DataVersion/BoardId、GetSRData() → (status, sr) / PowerMultiplier/PowerDivisor/ChipModel | EEPROM 回读自描述记录 / INA 功耗换算 |
bmc.dev.Chip.Pca9544 / Pca9545 | ChannelNum | Mux 通道数 |
bmc.dev.Chip.JtagTarget / bmc.kepler.Release.TraceChip | GetChipIdcode、SetTargetNumber、BypassChannelTest、Upgrade / TraceChip(Context, Action) | JTAG 操作 / 访问跟踪开关 |
返回值与异常
| 返回值 / 错误 | 含义 | 触发条件 | 处理建议 |
|---|---|---|---|
ay | 读成功 | 正常 | 无 |
Call failed: …(method_call_exception) | 访问失败 | 器件无响应、总线错误、通道未切 | 查 HealthStatus、总线 AccessEnabled、Mux 通道 |
Call failed: …(invalid_arg_exception) | 参数非法 | 空 buffer、非法 OffsetWidth、Length 非 1/2/4 | 按方法表取值范围改正 |
ResultCode = 1~5 | 加解锁失败 | 参数非法、请求者/器件/通道不匹配 | 见 §6.3 |
| 读写直接失败 | 处于禁止访问窗口 | 前序调过 SetAccessibility(false) | 等时长到期或显式恢复 |
应用场景
上层组件通过 Chip/RefChip 引用读取温度、电压、在位等板级量;升级或复位期间用 SetAccessibility、SetLockStatus 独占通道,避免与周期扫描抢总线;EEPROM 器件由 SelfDescriptionRecord 提供板卡身份。
限制条件
- 器件必须在同名总线/Mux 之后创建(由
ManagementTopology决定),否则create_chip返回空、对象不上树; - 经过 Mux 的器件必须先切通道;
SetLockStatus加锁与解锁的请求者必须一致; BitIORead/BitIOWrite的Length只支持 1/2/4,其它长度用BlockIORead自行掩码;SetAccessibility最长 1800 秒自动恢复,不要依赖它做长期禁用。
调试示例
命令行调试
# 查健康状态与类型:busctl 输出为"类型码 + 值"
busctl --user get-property $SVC $CHIP bmc.dev.Chip HealthStatus # 输出:y 0
busctl --user get-property $SVC $CHIP bmc.dev.Chip ChipType # 输出:s "Smc"
# 查方法签名(是否有 a{ss} 上下文首参以此为准)
busctl --user introspect $SVC $CHIP bmc.dev.Chip | grep -A3 BlockIORead # 输出:.BlockIORead method uu ay -
# 临时禁止访问 60 秒(升级窗口用):成功无输出,失败报 Call failed
busctl --user call $SVC $CHIP bmc.dev.Chip SetAccessibility bq false 602.3 总线对象(bmc.dev.Bus 及各变体)
功能说明
总线壳把内部 bus_base 实现包装成设备树对象,器件通过父节点关系找到"往哪条线上发"。总线对象同样使用相对路径。
| 项 | 内容 |
|---|---|
| 接口名 | bmc.dev.Bus(变体专有:Bus.I2c、Bus.Hisport、Bus.Jtag、Bus.UartBus、bmc.dev.Mux) |
| 服务名 | bmc.kepler.devmon |
| 对象路径 | 相对路径 ${object_name} |
| 首发版本 | 1.2.15 |
| 废弃状态 | 正常可用 |
常用变体与专有属性(Jtag/UartBus 的专有属性为 JlcTckRate 与 ChannelId/BaudRate;其余变体如 LocalBus/I2cOverHisport/SPIOverHisport/Can/Adc/Gpio/JtagOver* 只实现公共接口,专有属性见 gen/**):
| 总线类 | 专有接口 | 关键专有属性 |
|---|---|---|
I2c | bmc.dev.Bus.I2c | Id、Speed、Mode、SlaveAddr、UseSmbus |
Hisport | bmc.dev.Bus.Hisport | Id、BusNum、RegNum、FlagNum、SendRegAddr、RecvRegAddr、FlagRegAddr、MaxBatchLen、MaxDataLen、MaxOffsetWidth、MaxLengthWidth |
I2cMux | bmc.dev.Mux | ChannelId(当前通道,配合器件侧切通道) |
参数说明
属性参数说明(公共部分)
| 属性名 | 类型 | 读写 | 说明 | 取值范围 |
|---|---|---|---|---|
| AccessEnabled | Boolean | RW | 总线访问开关,与器件级开关做"与"判定 | true、false |
| Timeout | U16 | RW | 总线级超时,单位 ms | >0 |
方法参数说明
| 方法名 | D-Bus 签名 | 入参 | 出参 | 说明 | 取值范围 |
|---|---|---|---|---|---|
| SetAccessibility | bq | Status: Boolean、DisableDuration: U16 | 无 | 禁止/恢复整条总线访问 | 时长 1~1800 秒 |
返回值与异常
| 返回值 / 错误 | 含义 | 触发条件 | 处理建议 |
|---|---|---|---|
| 无返回 | 设置成功 | 正常 | 无 |
| Call failed | 设置失败 | 对象不存在、参数越界 | 查对象路径与时长范围 |
| 其上器件读写全部失败 | 总线级故障 | 总线禁用、线路异常、参数不匹配 | 查 AccessEnabled 与总线参数,必要时隔离 |
应用场景
排障时整条线隔离(怀疑线序或电平问题);升级期间冻结某条带内/带外通道。
限制条件
- 总线必须先于其下器件创建(SR 拓扑顺序);
I2cMux的通道切换由器件侧发起,总线对象不缓存当前通道;- 速率、时序参数改动后需重启宿主进程生效,不是热生效。
调试示例
命令行调试
busctl --user get-property $SVC $BUS bmc.dev.Bus AccessEnabled # 输出:b true
busctl --user get-property $SVC $BUS bmc.dev.Bus.I2c Speed # 输出:u 100
# 隔离整条总线 60 秒:成功无输出
busctl --user call $SVC $BUS bmc.dev.Bus SetAccessibility bq false 602.4 采集对象(Accessor / Scanner / 去抖)
功能说明
三个对象同属"从器件取值"这一类,差异在于触发方式与过滤方式:
| 接口 | 触发方式 | 用途 |
|---|---|---|
bmc.dev.Accessor | 每次访问属性都真读,不缓存 | 低频、维护窗口按需读 |
bmc.dev.Scanner | 按 Period 周期读并写回 Value,带防抖与聚合/合并读 | 温度、在位等周期量 |
bmc.dev.Debounce.* | 纯算法件,被 Scanner/Accessor 的 Debounce 属性引用后才生效 | 滤除瞬时毛刺 |
| 项 | 内容 |
|---|---|
| 接口名 | bmc.dev.Accessor、bmc.dev.Scanner(+Scanner.Aggregate)、bmc.dev.Debounce.{Median,Average,Continue,BinaryContinue} |
| 服务名 | bmc.kepler.devmon |
| 对象路径 | /bmc/dev/Accessor/${object_name}、/bmc/dev/Scanner/${object_name}、/bmc/dev/Debounce/<算法>/${object_name} |
| 首发版本 | 1.2.15 |
| 废弃状态 | 正常可用 |
参数说明
属性参数说明(Accessor)
| 属性名 | 类型 | 读写 | 说明 | 取值范围 |
|---|---|---|---|---|
| Chip | String | RW | 目标器件引用 | 对象引用(ref_object) |
| Offset | U32 | RW | 读偏移 | 按器件 |
| Size | U8 | RW | 读长度(字节) | 位读 1/2/4;块读按器件 |
| Mask | U32 | RW | 取值掩码 | 按位域 |
| Type | U8 | RW | 读方式 | 0 位读、其它值块读 |
| Value | U64 | RO | 最近一次读取值 | - |
属性参数说明(Scanner)
| 属性名 | 类型 | 读写 | 说明 | 取值范围 |
|---|---|---|---|---|
| Chip / Offset / Size / Mask / Type | 同上 | RW | 读参数 | 同上(Type:0 位读、1 块读) |
| Period | U32 | RW | 扫描周期,单位 ms | 0 视为默认 3000;最小 100 |
| Debounce | String | RW | 去抖对象引用或内联配置 | 引用/配置 |
| Value | U64 | RO | 当前值 | - |
| Status | U8 | RO | 状态码,默认 4 | 0 正常、1 失败、2 预失败、3 停止、4 初始 |
| NominalValue / ScanEnabled | U64 / U8 | RW | 正常值(比较判定用)/ 扫描使能,默认 1 | - / 0、1 |
| SuccessDebounceCount / FailureDebounceCount | U8 | RW | 成功/失败防抖门限,默认 10 | 0~255 |
属性参数说明(去抖对象)
| 接口 | 属性 | 说明 |
|---|---|---|
bmc.dev.Debounce.Median / .Average | WindowSize: U32、IsSigned: Boolean | 滤波窗口长度、是否按有符号处理 |
bmc.dev.Debounce.Continue / .BinaryContinue | Count: U8 / HighLevelCount: U8、LowLevelCount: U8 | 连续 N 次一致才更新 / 高、低电平各自需连续的次数 |
方法参数说明
Accessor、Scanner、去抖对象均无业务方法;bmc.dev.Scanner.Aggregate 提供两个只读属性:AggregateOffset(U32,汇聚数据偏移)、AggregateStatus(Boolean,是否来自汇聚读)。
返回值与异常
| 返回值 / 错误 | 含义 | 触发条件 | 处理建议 |
|---|---|---|---|
Value 正常返回、Status=0 | 读取正常 | 器件可访问且去抖通过 | 无 |
Status=1 | 扫描失败 | 器件不可访问、引用失效 | 查器件 HealthStatus 与总线 |
Status=2 | 预失败(防抖中) | 失败次数未达 FailureDebounceCount | 观察是否持续,偶发可忽略 |
Status=3 | 停止/禁用 | ScanEnabled=0 或被 SetAccessibility 暂停 | 恢复使能或等禁止窗口结束 |
Status=4 | 初始状态 | 尚未完成第一次扫描 | 等一个 Period |
应用场景
温度、在位、电源状态等周期量采集(Scanner);维护窗口按需读一次(Accessor);机械触点、光模块在位等需要去抖的点位(去抖对象 + Debounce 引用)。
限制条件
- 同一
(Chip, Offset, Size, Type)的多个 Scanner 会合并读:只有 master 真正发总线请求,follower 的SuccessDebounceCount增长会变慢; Chip是引用,SR 写错对象名init不报错,首次扫描才失败;Accessor每次访问都真读硬件,高频轮询会直接打到总线,需要周期采集请用Scanner;- 块读时
Mask无效;ScanEnabled可由表达式同步但不能成环;去抖对象单独创建不产生任何硬件动作。
调试示例
命令行调试
busctl --user get-property $SVC $SCAN bmc.dev.Scanner Value # 输出:t 0
busctl --user get-property $SVC $SCAN bmc.dev.Scanner Status # 输出:y 0
busctl --user get-property $SVC $SCAN bmc.dev.Scanner Debounce # 输出:s ""
# 暂停扫描:成功无输出
busctl --user set-property $SVC $SCAN bmc.dev.Scanner ScanEnabled y 02.5 PCIe 通用部件对象(PCIeDevice / PCIeCard)
功能说明
一块 PCIe 卡的主设备通常实现 bmc.dev.PCIeDevice + bmc.dev.PCIeCard 及若干子接口;卡上子设备以相对路径挂在主设备下。
| 项 | 内容 |
|---|---|
| 接口名 | bmc.dev.PCIeDevice(+.Status/.PCIeFunction/.HotSwap/.Bandwidth/.Oem)、bmc.dev.PCIeCard(+.Oem/.Metrics) |
| 服务名 | bmc.kepler.devmon |
| 对象路径 | 主设备绝对路径(如 /bmc/dev/Systems/1/PCIeNicCard/${object_name}),子设备相对路径(如 NicPort/${PortId}) |
| 首发版本 | 1.2.15 |
| 废弃状态 | 正常可用 |
| 对象 | 路径模板 | 接口组合(以网卡为例) |
|---|---|---|
主设备(PCIeNicCard/PCIeGpuCard) | /bmc/dev/Systems/1/<Unit.Type>/${object_name} | PCIeDevice + .Status/.PCIeFunction/.HotSwap/.Bandwidth/.Oem、PCIeCard + .Oem |
网口(NicPort) | NicPort/${PortId} | NetworkPort + .LinkInfo/.Metrics/.Oem |
光模块(OpticalTransceiver) | OpticalTransceiver | OpticalModule + .Status/.TemperatureCelsius/.Power/.Voltage/.Current/.Diagnose/.Channel/.Oem |
| GPU / 显存 | GraphicsController/${Id}、Memory/${DimmNum} | Processor + .Metrics、Gpu + .Power/.Status;Memory + .Metrics |
参数说明
属性参数说明(bmc.dev.PCIeDevice)
| 属性名 | 类型 | 读写 | 说明 | 取值范围 |
|---|---|---|---|---|
| DeviceName / Location | String | RW | 部件名称 / 位置字符串 | - |
| Slot / SocketId / SystemId | U8 | RW | 槽位号 / CPU Socket / 系统号 | Slot 1~255、SocketId 0/1、SystemId ≥1 |
| Bus / Device / Function | U8 | RW | BDF | 0~255 / 0~31 / 0~7 |
| SlotType / DeviceType | String | RW | 槽位类型 / 设备类型 | 枚举字符串 |
| Model / Manufacturer / PartNumber / SerialNumber / FirmwareVersion | String | RW | 资产信息(init 填或周期刷新) | - |
| MaxPCIeType / PCIeType | U8 | RW | 支持/当前链路代际 | 1~5 |
| MaxLanes / LaneInUse | U8 | RW | 最大/实际链路宽度 | 1、2、4、8、16 |
方法参数说明
| 方法名 | D-Bus 签名 | 入参 | 出参 | 说明 | 取值范围 |
|---|---|---|---|---|---|
| SetRootBDF | yyy | Bus: U8、Device: U8、Function: U8 | Result: Boolean | 设置根 BDF | 三者全 0 非法,返回 false |
衍生接口要点
| 接口 | 关键成员 | 说明 |
|---|---|---|
PCIeDevice.PCIeFunction | ClassCode: U32、VendorId/DeviceId/SubSystemVendorId/SubSystemDeviceId: String、BusNumber/DeviceNumber/FunctionNumber/SegmentNumber: U8;方法 SetDeviceBDF | 功能级标识 |
PCIeDevice.Status / .HotSwap | UCEByBios、BandwidthReduced、LinkSpeedReduced、DiagnosticFault、PredictiveFault、FirmwareAbnormal(U8) / HotPluggable: Boolean、ReadyToRemove: U8 | 故障位(位含义随厂商)/ 热插拔状态 |
PCIeDevice.Bandwidth | LinkWidthCapability/LinkWidth/LinkSpeedCapability/LinkSpeed: String、BandwidthThresholdPercent: U16 | 带宽占用与阈值 |
PCIeCard | Name/Description/PcbVersion/BoardName/FormFactor: String、BoardId: U16、Health/PcbId/CardPowerGood: U8 | 板卡身份与健康 |
返回值与异常
| 返回值 / 错误 | 含义 | 触发条件 | 处理建议 |
|---|---|---|---|
true / false | BDF 设置成功/失败 | 参数合法 / 三者全 0 | 换合法 BDF 重试 |
| 属性保持初值 | 资产读取失败 | 器件不可访问、厂商命令未适配 | 查 Chip.HealthStatus 与该型号是否实现 |
应用场景
上层组件按 PCIeDevice 判在位/资产、按 .Status 判故障;HotSwap.ReadyToRemove 用于免下电换卡;.Bandwidth 用于带宽占用率告警。
限制条件
- 一张卡的接口组合必须与
dmc/path一致,缺接口会导致上游取不到值; - 子设备是相对路径,父对象不存在则整棵子树不上树;
- 厂商私有命令走
*.Oem或协议库,不要往标准接口里加私有属性。
调试示例
命令行调试
busctl --user get-property $SVC $CARD bmc.dev.PCIeDevice Model # 输出:s "SP580"
busctl --user get-property $SVC $CARD bmc.dev.PCIeDevice.PCIeFunction VendorId # 输出:s "0x8086"
# 子设备:取主设备下的第一个网口
PORT=$(busctl --user tree $SVC | grep -m1 "^$CARD/NicPort/")
busctl --user get-property $SVC $PORT bmc.dev.NetworkPort.LinkInfo LinkStatus # 输出:y 12.6 部件家族接口清单
功能说明
各家族在 PCIeDevice/PCIeCard 之外还各自实现一组业务接口(资产、状态、度量、控制),接口组合由 dmc/path 声明。本节只列接口名与关键成员,不逐项展开:bmc.dev.* 共 152 个接口、上千条属性,完整属性表见 gen/include/device_tree/interface/** 与 dmc/intf/bmc/dev/**。
| 项 | 内容 |
|---|---|
| 接口名 | 见下表「接口」列(网卡/光模块/GPU/内存/电源/风扇/NVMe/RAID/SSU 各家族接口) |
| 服务名 | bmc.kepler.devmon |
| 对象路径 | 主设备绝对路径 + 子设备相对路径(见 §2.5 路径表) |
| 首发版本 | 1.2.15(各家族接口随对应驱动型号首发,早于该型号的机型无此对象) |
| 废弃状态 | 正常可用 |
参数说明
| 家族 | 接口 | 关键属性 / 方法 |
|---|---|---|
| 网卡 | bmc.dev.NetworkAdapter | ManufacturerId: U32、Manufacturer/ChipModel/ChipVendor: String、NetworkPortCount/Type: U8、RefChip: String |
bmc.dev.NetworkPort + .LinkInfo/.Metrics/.Oem | PortId: U8、MACAddress/BDF: String、NetDevFuncType: U8、LLDPEnabled: Boolean;LinkInfo 有 LinkStatus/SpeedMbps 与 SetSpeedGbps | |
bmc.dev.NetworkAdapter.LogCollection | DumpErrorLog、DumpRunningLog、DumpBlackBoxLog、CollectLogByNcsi、CollectLogBySmbus | |
| 光模块 | bmc.dev.OpticalModule + .Status/.TemperatureCelsius/.Power/.Voltage/.Current/.Diagnose/.Channel/.Oem | 资产(Manufacturer/PartNumber/WaveLengthNanometer 等 String、TransmissionDistance: U16、Presence/ChannelNum: U8);状态位与门限见子接口 |
| GPU / 处理器 | bmc.dev.Gpu + .Power/.Status;bmc.dev.Processor + .Metrics | InfoRomVersion/UUID: String、Utilization: U16、RefChip: String;PowerCapacityWatts: U32;TemperatureCelsius: Double、PowerWatts: U16 |
| 内存 | bmc.dev.Memory + .Metrics | TotalBytes/UsedBytes/FreeBytes: U64、Bandwidth: U32、TemperatureCelsius: Double |
| 电源(当前未接入构建,见 §4.4) | bmc.dev.PowerSupply + .Metrics/.Status/.Control/.DualInputs/.DualChannel/.Capacitor/.Upgrade/.LogCollection | 资产(Manufacturer/Model/PartNumber/SerialNumber/Protocol: String、SlotNumber: U32);Metrics 17 项输入输出/温度/转速;Status 14 个状态字节;Control 有 SetWorkMode/SetSleepMode/Reset/SetOutputPowerLimitWatts 等;Upgrade 有 Upgrade/Active |
| 风扇(SMC 型号未接入构建,见 §4.4) | bmc.dev.Fan + .Status/.Control;bmc.dev.Fans;bmc.dev.FanType | FanId/IdentifySpeedLevel: U16、FrontMaxSpeed/RearMaxSpeed/MaxSupportedPWM: U32;Status 前后转子在位/状态与 SpeedStable;Fans 有 SetPWM(PWM: ad)、DumpFanLogs;FanType 为型号识别区间 |
NVMe / RAID(均仅 unidev 构建) | NVMe:bmc.dev.NVMe + .Smart/.Status/.ProductInfo/.BasicManagement/.Management/.NVMeMI/.Oem;RAID:bmc.dev.Storage.Controller + .Settings/.Status/.Metrics/.Capability.*/.PHY/.OOB、.Drive + .Status/.Settings/.Metrics/.Led、.Volume/.DiskArray/.BBU/.Expander | NVMe:介质类型、磨损度、SMART,NVMeMI 有 GetSmartInfo/SendNvmeMICommand/GetTelemetryData/GetIdentifyData;RAID:Controller.Settings 有 CreateCommonLD/AddLD/DeleteLD/SetDriveWriteCachePolicy,Drive.Status 有定位灯与 GetSlowDiskCounters,Volume.Settings 有 SetBootPriority/StartFGI |
SSU(feature_ssu=true 才编) | bmc.dev.SSU;子对象 UBPort/GEPort/SSUDrive 复用 NetworkPort/LinkSwitch/NVMe/Temperature 等通用接口 | Id/PowerState: U8;子对象按其复用的通用接口取属性 |
返回值与异常
| 返回值 / 错误 | 含义 | 触发条件 | 处理建议 |
|---|---|---|---|
| 属性有值且状态位为 0 | 正常 | 驱动已实现该能力且器件可访问 | 无 |
| 属性长期为初值 | 未实现或读失败 | 接口组合未包含、厂商命令未适配 | 查该型号 interface/ 实现与 dmc/path 组合 |
ActionNotSupported 类错误 | 能力不支持 | 方法在该型号未实现 | 换支持型号或走私有命令 |
应用场景
上层组件按家族取数(网卡资产、光模块诊断、GPU 利用率、电源能耗、风扇状态、NVMe SMART、RAID 盘阵);现场按接口名定位"哪个能力由谁实现"。
限制条件
- 接口组合以
dmc/path/bmc/dev/**为准,未在契约声明的接口不要写进驱动; - 同一接口在不同型号支持度不同(如光模块
Diagnose仅部分型号实现); - 电源与 SMC 风扇虽在契约中有接口声明,但对应驱动目录当前未接入构建(见 §4.4),现网只会出现 RS485 风扇对象;
NVMe/RAID仅unidev=true的包里有,SSU仅feature_ssu=true的包里有。
调试示例
命令行调试
# 取 GPU 卡主设备下的 GPU 与显存子对象
GPU=$(busctl --user tree $SVC | grep -m1 -E "/PCIeGpuCard/.*/GraphicsController/")
MEM=$(busctl --user tree $SVC | grep -m1 -E "/PCIeGpuCard/.*/Memory/")
busctl --user introspect $SVC $GPU # 输出:.Utilization property q 0 emits-change
busctl --user get-property $SVC $GPU bmc.dev.Gpu Utilization # 输出:q 37
busctl --user get-property $SVC $MEM bmc.dev.Memory TotalBytes # 输出:t 257698037762.7 与上位组件、宿主的边界
| 角色 | 关系 |
|---|---|
devmon | CSR2(FormatVersion >= 5.00)宿主:装载本仓 .so、建 /bmc/dev/** 对象、导出 bmc.dev.* |
hwproxy | unidev(CSR1)宿主:装载 libCsr1 前缀的 .so,导出 /bmc/kepler/** 的 bmc.kepler.* |
hwdiscovery | 解析 SR、管理 Connector,把拓扑交给上述宿主 |
| 业务组件 | 消费 bmc.dev.*:读资产/状态、调控制方法;对外的资源协作接口见各自组件说明 |
本节涉及的 bmc.dev.* 接口首发版本均为 1.2.15;CSR1 兼容接口(bmc.kepler.*)的首发版本与版本演进见《devmon》与《hwproxy》。
CSR1 与 CSR2 的差异:
| 维度 | CSR2(本篇主描述) | unidev(CSR1 兼容) |
|---|---|---|
| 接口前缀 / 路径 | bmc.dev.* / /bmc/dev/** | bmc.kepler.* / /bmc/kepler/** |
| 服务名 | bmc.kepler.devmon | bmc.kepler.hwproxy(Connector 在 bmc.kepler.hwdiscovery) |
.so 命名 | lib<Name>.so | libCsr1 前缀优先,退回 lib<Name>.so |
| 方法签名 | 一般不带 a{ss} 上下文首参 | 带 a{ss},如 SetAccessibility a{ss}bq 0 false 60 |
| 拉取方法 | BitIORead/BlockIORead/BlockIOWriteRead | Chip.BlockIO 的 Read/Write/WriteRead/BatchWrite/PluginRequest |
| 驱动源码 | drivers/{chip,bus,accessor,scanner,debounce,pcie_*}/** | drivers/csr1/**(unidev=true 才编) |
2.8 CLI、IPMI 接口使用样例
不适用。component_drivers 只提供驱动插件与设备树对象,不注册 IPMI 命令、不提供 CLI 命令;IPMI/CLI 由实现该命令的业务组件(如 ipmi_core、network_adapter、thermal_mgmt)负责。硬件侧验证手段是 busctl 直接调 bmc.dev.*(见 §2.2~§2.6 的调试示例)。
3. 组件扩展案例
3.1 扩展能力概述
支持四类扩展:新增一颗器件、新增一条总线、适配一张新卡、新增接口/属性(需改契约与生成物)。四类都不支持"运行期热插拔新代码"——新增内容必须重新出包并由宿主重新装载。
3.2 扩展点说明
| 扩展点 | 入口 | 作用 | 需要改 gen/ |
|---|---|---|---|
| 器件 | drivers/internal/chip/chip_<name>/ + drivers/chip/<name>/ + device_manager 工厂表 | 新增一类芯片的时序与语义 | 否(复用 bmc.dev.Chip) |
| 总线 | drivers/internal/bus/bus_<name>/ + drivers/bus/<name>/ + 工厂表 | 新增一类物理/逻辑总线 | 否(复用 bmc.dev.Bus) |
| 卡型 | drivers/pcie_*_card/<vendor>/<model>/ + csr/*.sr、*.dds | 新增一张卡(主设备 + 子设备) | 否(接口组合已存在时) |
| 接口/属性 | dmc/ 的 intf 与 path → 重新生成 gen/ → 各驱动 interface/ | 新增对外能力 | 是 |
| 裁剪 | meson_options.txt + drivers/meson.build + mds/service.json | 把不需要的能力裁出包 | 否 |
3.3 二次开发指导
以下以"新增一颗 FooChip 器件"为主线;总线与卡型只换路径与注册点,步骤同构。
步骤一
新建内部件 drivers/internal/chip/chip_foo/{foo.h,foo.cpp,meson.build},继承 dev::chip_base,实现 init() 与所需的 bit_read/block_read,并在 drivers/internal/manager.cpp 的 init_factory_maps() 注册:
m_chip_factories["FooChip"] = [](mc::mutable_dict& csr_data) -> std::shared_ptr<chip_base> {
auto ptr = std::make_shared<chip_foo>();
return (ptr && ptr->init(csr_data)) ? ptr : nullptr;
};步骤二
新建对象壳 drivers/chip/foo/{foo.h,foo.cpp,foo_abi.cpp,meson.build}:MC_OBJECT 声明接口组合,init() 只做"绑定内部件 + 灌属性";ABI 层把 device_name 写成 FooChip。
MC_OBJECT(foo_object, "FooChip", "${object_name}", (Interface_Chip)(Interface_TraceChip))
bool foo_object::init(mc::mutable_dict& csr_object, const mc::dict& connector)
{
if (!bind_internal_chip(csr_object, m_chip_foo, "FooChip")) return false; // 绑定失败放弃注册
initialize_default_properties(m_interface_chip, csr_object);
from_variant(csr_object, *this);
return true;
}步骤三
接构建与测试,四处要同时改,漏一处就是"编进去了但装载不到":
drivers/internal/chip/meson.build:加subdir('chip_foo')并把chip_foo_sources加入chip_sources;drivers/internal/meson.build:install_headers('chip/chip_foo/foo.h', ...);drivers/chip/meson.build:加subdir('foo'),shared_library('FooChip', link_whole: [foo_core_lib], install_dir: drivers_install_dir);tests/drivers/chip/foo/:单测 + ABI 测试(dlopen("./opt/bmc/drivers/libFooChip.so")),并在该目录meson.build注册 suite。
示例代码
SR 侧只需一个对象(器件为相对路径,挂在父总线或 Mux 下):
{
"FooChip_0": {
"Address": 64, // 器件地址,与硬件一致
"AddrWidth": 1, // 地址字节数
"OffsetWidth": 2, // 偏移字节数
"WriteTmout": 100, // 写超时 ms
"ReadTmout": 100
}
}验证方法
meson compile -C builddir后ls builddir/opt/bmc/drivers/libFooChip.so存在,且nm -D有register_device_driver;- 装机后
busctl --user tree $SVC能列出FooChip_前缀对象,ChipType为FooChip; - 正常读写一次并对比硬件手册,确认
HealthStatus保持0;再换错地址,确认HealthStatus变1(异常路径)。
注意事项
device_manager对同名对象直接复用,改 SR 后不重建会沿用旧配置;bind_internal_chip内部有器件类型白名单,新类型要先登记,否则绑定失败;- 对象壳里不要起周期任务,周期任务放
start(),否则对象还没上树就开始写属性; - 新增导出符号必须带
MC_API,否则-fvisibility=hidden下符号不可见。
3.4 其它扩展路径
| 场景 | 关键差异 |
|---|---|
| 新增一条总线 | 实现 bus_base 的 read/write/bus_lock/bus_unlock;drivers/internal/bus/meson.build 与 drivers/internal/meson.build 各加一处;对象壳用 BusObjectBase::bind_internal_bus。CSR1 兼容需再建 drivers/csr1/bus/<name>/(libCsr1FooBus.so) |
| 适配一张新卡 | 复制同厂商型号目录;device_driver_t.device_name 保持 PCIeNicCard/NicPort 等类名,不要改型号名;.so 名由 SR 的 Unit.Compatible 决定;新卡 SR 放 csr/<型号>/*.sr + *.dds,FormatVersion 保持 "5.00" |
| 裁剪 | 改 meson_options.txt 与对应 subdir,同步 mds/service.json 的 options.default;恢复被裁目录时要连同依赖库一起加回(见 §4.4) |
4. 配置介绍
4.1 配置导入导出项
不适用。本组件无持久化业务数据,不参与配置导入导出;机型差异由 SR/CSR 承载(见 §4.3)。
4.2 装备定制化项
不适用。装备定制化由业务组件(如 power_mgmt、thermal_mgmt)实现;本组件只提供驱动能力。
4.3 CSR 配置
驱动对象由 SR 描述,四段结构决定一切:
{
"FormatVersion": "5.00", // <5.00 走 CSR1(abi_v1),>=5.00 走 CSR2(abi_v2)
"DataVersion": "5.00",
"Unit": {
"Type": "PCIeGpuCard", // 主设备 device_name
"Name": "PCIeGpuCard_1", // 主设备对象名(宿主拼成 <Name>_<Position>)
"Compatible": ["jm1100"] // 决定 .so 名:/opt/bmc/drivers/libjm1100.so
},
"ManagementTopology": {
"Anchor": { "Buses": ["I2cMux_Chan"] }, // 入口总线
"I2cMux_Chan": { "Chips": ["Chip_McuChip"] } // 该总线下的器件
},
"Objects": {
"Chip_McuChip": { "Address": 102, "AddrWidth": 1, "OffsetWidth": 1, "WriteTmout": 100 },
"Component_PCIeCard": { "Name": "<=/PCIeGpuCard_1.DeviceName", "FruId": 255 }
}
}字段与命名约定:
| 约定 | 说明 |
|---|---|
FormatVersion | 决定走哪代宿主与哪套 .so(<5.00 → CSR1/abi_v1) |
Unit.Type / Unit.Name | 主设备 device_name / 主设备对象名;Objects[Unit.Name] 不能缺 |
Unit.Compatible | .so 名来源,数组按顺序尝试,, 替换为 _ |
ManagementTopology | 先建总线/器件,再建业务对象;顺序错则父对象找不到 |
| 对象名前后缀 | 最终对象名 = <SR 对象名>_<Position>;首段等于某 device_name 时由该表项建对象 |
| 表达式 | <=/<对象名>.<属性> 初始化求值;#/<对象名> 为引用;$sync:/$ref:/$local: 由宿主提升为引用句柄 |
| 宿主注入字段 | SystemId 由宿主按 connector 注入到对象属性,SR 里不用写;需要不同系统号时靠 Position/Connector 配置区分 |
现网配置(网卡卡型示例,字段含义见注释):
{
"PCIeNicCard_1": {
"Slot": 1, // 槽位号
"DeviceName": "SP580", // 部件名
"BoardId": 65535, // 板 ID,未知填 65535
"RefChip": "#/Smc_CpuBrdSMC" // 管理芯片引用(SMbus/NCSI 通道);SystemId 由宿主注入
},
"NicPort_1": {
"PortId": 1, // 端口号,决定子对象路径 NicPort/1
"MACAddress": "<=/Smc_CpuBrdSMC.MacAddr1", // 表达式取值
"NetDevFuncType": 4 // 端口类型
},
"OpticalTransceiver_1": {
"Presence": "<=/Scanner_Optical1_Presence.Value"
}
}说明
SR/CSR 文件在仓内的位置是 drivers/<家族>/<厂商>/csr/**/*.sr(配套 .dds);本仓 meson 不安装这些文件,由整机打包流程送进目标机 /opt/bmc/sr,改了 SR 要确认它真的进了包。
限制条件:Unit.Type / Unit.Compatible / Objects[Unit.Name] 三者必须自洽;器件与总线对象必须排在引用它们的业务对象之前;同一 Position 下对象名不能重复。
4.4 构建选项与裁剪
| 选项 | 默认 | 打开后的影响 |
|---|---|---|
unidev | false | 编 drivers/csr1/**、drivers/connector、pcie_raid_card、pcie_nvme 及 CSR1 专有总线/器件 |
chipv2_enable | false | 编 hisport2、i2c_over_hisport、i2c_over_localbus、i3c_over_localbus、spi_over_hisport、jtag_over_hisport |
feature_ssu | false | 编 drivers/ssu_card 与 libraries/ssu_oob |
feature_rs485 | false | 编 drivers/fan(当前实际只含 rs485) |
feature_mellanox | true | 编 drivers/pcie_nic_card/mellanox |
jtag_sec_mode_bcal | false | JTAG 安全模式 BCAL 适配 |
当前未接入构建的目录(截至 1.2.595):drivers/psu/**、drivers/fan/huawei/**、libraries/pmbus/**、libraries/canbus/**、tests/drivers/psu/**、tests/drivers/fan/huawei/** 在提交 f704a8af("unidev裁剪风扇电源")后不再被 subdir,源码仍在仓内但不产生 .so。因此 §2.6 中电源与 SMC 风扇的接口在现网包里取不到对象,包内只会出现 RS485 风扇;取包时若发现没有 libpsu_pmbus.so、libfan_smc.so,属于当前裁剪状态,不是装载失败。
4.5 DMC 契约与设备描述文件
| 资产 | 位置 | 作用 |
|---|---|---|
| DMC 接口定义 | dmc/intf/bmc/dev/**/*.json | 接口属性/方法/类型/读写的单一事实源 |
| DMC 对象路径 | dmc/path/bmc/dev/**/*.json | 对象路径模板 + 该对象应挂的接口组合 |
| 生成物 | gen/include/device_tree/**、gen/src/device_tree/** | bmc.dev.* 的 C++ 接口与对象代码(入库,勿手改) |
| 设备描述文件 | drivers/**/csr/*.dds(Schema: dds-v1) | 单卡的对象路径与接口清单,用于与契约对齐;运行期不被解析 |
改动顺序:改 dmc/ → 重新生成 gen/ → 改各驱动 interface/ 实现 → 补测试。
5. 日志说明
5.1 日志路径
驱动运行在宿主进程内,日志与 dump 归属宿主,本仓不写独立日志文件。
| 路径 | 说明 | 定义位置 |
|---|---|---|
devmon 日志(模块名 devmon) | CSR2 下驱动日志落在这里,级别默认 notice | 宿主 config.single.json.in 的 Logging |
/var/log/framework/hwproxy.log | unidev 下驱动日志归属 hwproxy | 宿主 dist/config.cfg 的 logger |
/opt/bmc/drivers/lib*.so | 驱动插件本体,装载失败看该目录与 ldd 结果 | drivers/meson.build 的 drivers_install_dir |
/opt/bmc/sr/*.sr | 驱动输入(SR/CSR),本仓不安装 | 整机打包流程 |
5.2 一键日志收集
驱动无独立 dump 入口,由宿主在 Dump 回调里生成:
| 收集文件 | 生成位置 | 内容 |
|---|---|---|
$DUMP/drivers_load_info.csv | devmon Dump 回调 | 每个驱动 .so 的装载结果、设备表项数、耗时、失败原因 |
$DUMP/topology.txt | devmon / hwproxy Dump 回调 | 设备树/资源树拓扑,确认对象是否上树与父子关系 |
$DUMP/snapshot.csv | devmon / hwproxy Dump 回调 | Scanner / Accessor 的 dump 文本(值、成功失败计数、是否来自聚合读) |
$DUMP/chips_access_statistic.csv | devmon / hwproxy Dump 回调 | 芯片访问统计(Release 构建跳过) |
表中 $DUMP 指一键收集包根目录,其实际位置在 2.0 节已取到;重新取用命令:find / -maxdepth 6 -name drivers_load_info.csv 2>/dev/null | head -1。
5.3 关键日志信息
| 日志片段 | 级别 | 含义解读 | 建议处理动作 |
|---|---|---|---|
Driver not found: <name> | ERROR | Compatible 拼出的 .so 不存在或表项缺失 | 核对 .so 名与 device_name |
Failed to load driver: <error> | ERROR | dlopen 失败(缺依赖、架构不符) | ldd $DRVDIR/libX.so 查未解析符号 |
failed to create direct service device <obj> / cannot find parent for object <obj> | ERROR / WARN | 通用对象 init 失败 / 父对象不在同一 position 树上 | 看同段异常 error 字段(多为引用对象不存在);核对 ManagementTopology 顺序 |
Unsupported bus type: <class> | ERROR | 内部件工厂没有该 class_name | 是否被裁剪(如 chipv2_enable=false 用了 I2cOverHisport) |
csr_data is empty | ERROR | create_chip/create_bus 收到空配置 | 查 SR 中该对象的 Objects 段 |
device already exists, skip add device | WARN | 同一 Position 重复加载 | 先卸载再加载 |
6. 问题定界指南
6.1 典型问题定界
| 现象描述 | 是否为本组件问题 | 判断依据 | 关键证据收集方法 |
|---|---|---|---|
| 某部件对象完全不上树 | 通常是(驱动未装载或 SR 不匹配) | 无对应对象;日志有 Driver not found / failed to create | cat $DUMP/drivers_load_info.csv;ls $DRVDIR 看 .so 是否存在 |
| 部件对象在,但属性一直是初值 | 通常是(读失败或周期任务没起) | Scanner.Status != 0;Chip.HealthStatus = 1 | $DUMP/snapshot.csv;busctl --user get-property $SVC $CHIP bmc.dev.Chip HealthStatus |
| 某颗器件读写全失败,同总线其它器件正常 | 是(该器件配置或 Mux 通道) | 只有该器件 HealthStatus=1 | 同上;核对 SR 的 Address/OffsetWidth |
| 一条总线上所有器件都失败 / 升级后报"访问已关闭" | 是(总线配置或预期禁止窗口) | 整条线 AccessEnabled 正常但读失败;或前序调过 SetAccessibility(false) | 查 AccessEnabled,必要时 SetAccessibility(false) 隔离;禁止窗口等 DisableDuration 到期 |
包里缺某个 lib*.so / 换了 .so 现象没变 | 是(裁剪 / 宿主缓存) | 该目录未被 subdir;驱动按"驱动名 + abi 版本"缓存 | 对照 §4.4;重启宿主进程或整机复位后再验 |
| 资源树看不到某属性 / IPMI·CLI 命令失败 | 通常不是 | 属性在业务组件的 bmc.kepler.* 接口;本组件不注册 IPMI/CLI | busctl --user introspect 对比两个服务;IPMI/CLI 转对应业务组件 |
6.2 调试方法
6.2.1 查看对象与属性
busctl --user tree $SVC | grep -E "Chip|Bus|Scanner|PCIe"
busctl --user introspect $SVC $CHIP
# 输出示例(截取两行)
# .HealthStatus property y 0 emits-change
# .BlockIORead method uu ay -6.2.2 查看系统侧状态与读值链路
ls -l $DRVDIR | head # 驱动是否在包内
ldd $DRVDIR/libPca9545.so | grep "not found" # 依赖是否齐
busctl --user get-property $SVC $CHIP bmc.dev.Chip HealthStatus # 输出:y 0
busctl --user get-property $SVC $SCAN bmc.dev.Scanner Status # 输出:y 0
busctl --user get-property $SVC $CARD bmc.dev.PCIeDevice Model # 输出:s "SP580"6.2.3 打开更详细的日志
驱动调试日志走宿主 logger 的 module_name(devmon 默认 notice)。需要更详细时按宿主组件说明调整日志级别后复现(见《devmon》§4),不改驱动代码。
6.3 错误码速查表
| 错误码 / 返回值 | 含义 | 可能原因 | 排查建议 |
|---|---|---|---|
0 STATUS_OK | 装载/初始化成功 | 正常 | 无 |
1 STATUS_ERROR | 通用失败 | init 解析失败、内部件绑定失败 | 查同段异常与 SR 字段 |
2 STATUS_NOT_FOUND | 依赖对象不存在 | 总线/器件/引用对象缺失、拓扑顺序错 | 核对 ManagementTopology 与对象名 |
3 STATUS_INVALID_ARG | 参数非法 | 空 CSR、缺必填字段 | 对照 §4.3 字段约定 |
4 STATUS_NOT_IMPLEMENTED | 能力未实现 | 该型号未适配或被裁剪 | 查驱动实现与 §4.4 |
5~7 | 超时 / 忙 / 无内存 | 硬件无响应、通道被锁、分配失败 | 查 HealthStatus、总线锁、内存 |
ResultCode 1~5 | InvalidParameter / UnlockedError / 请求者·器件·通道不匹配 | 时长非法、未加锁即解锁、解锁方与锁定方不一致、同通道其它器件已锁 | 加锁 ≤ 30 分钟且同一调用方加解锁;释放冲突锁后重试 |
说明
本组件没有独立错误引擎,D-Bus 侧统一表现为 Call failed: <异常文本>;status_t 只用于 ABI 装载阶段,ResultCode 只在 SetLockStatus 出现。
6.4 最小化复现与证据收集
- 记录接口名、对象路径、方法名与参数、返回文本,以及组件版本(
grep -m1 '"version"' mds/service.json)。 - 固定前置条件:接口架构(单层还是 unidev)、对象是否上树、器件
HealthStatus是否为0、总线AccessEnabled是否为true。 - 最小操作步骤:一条
busctl命令(或一次 SR 加载),避免夹带无关读写。 - 保存证据:命令返回值、
$DUMP/下drivers_load_info.csv、snapshot.csv、topology.txt,以及宿主日志片段。 - 记录复现概率与环境差异(机型、单板、
.so版本、是否裁剪feature_*)。
7. 常见问题解答
Q1:包里找不到 libpsu_pmbus.so、libfan_smc.so,是编译失败吗?
- 问题描述:装机后
ls /opt/bmc/drivers看不到电源或 SMC 风扇驱动,对应bmc.dev.PowerSupply/bmc.dev.Fan对象也不存在。 - 一句话答案:不是编译失败,是当前版本把这两片目录裁出了构建。
- 根因说明:提交
f704a8af删除了drivers/meson.build的subdir('psu')、drivers/fan/meson.build的subdir('huawei'),以及libraries/meson.build的subdir('canbus')/subdir('pmbus')。 - 解决方案:把上述 4 处
subdir一起加回并重新出包(漏加libraries两处会因libpmbus_dep/libcanbus_dep未定义导致 meson 失败)。 - 规避方案:用支持该能力的版本,或在业务侧先关闭对应依赖。
- 适用版本:1.2.595 及之后。
Q2:同一颗芯片为什么在两个服务下都能看到?
- 问题描述:
bmc.kepler.devmon与bmc.kepler.hwproxy里都有这颗芯片,接口名不同。 - 一句话答案:这是 CSR1/CSR2 双路径,不是重复装载。
- 根因说明:unidev 构建同时编
libCsr1前缀与普通前缀的两套.so;CSR1 的 SR(FormatVersion < 5.00)由 hwproxy 装载并暴露bmc.kepler.Chip,CSR2 的 SR 由 devmon 装载并暴露bmc.dev.Chip。 - 解决方案:按 SR 的
FormatVersion判定该看哪个服务;单层包只有bmc.kepler.devmon一路。 - 规避方案:无(属于兼容设计),排查时固定用一个服务。
- 适用版本:
unidev=true的构建。
Q3:改了 SR 里的 Address,为什么设备读到的还是老地址?
- 问题描述:修改 SR 中器件的
Address后重新加载,读到的仍是旧地址的数据。 - 一句话答案:器件对象按对象名复用,同名对象不会按新 SR 重建。
- 根因说明:
device_manager::create_chip/create_bus遇到同名对象直接返回已有实例;驱动.so在宿主还要按"驱动名 + abi 版本"缓存。 - 解决方案:卸载该 position 后再加载或重启宿主进程,并确认新 SR 已进包(
ls -l /opt/bmc/sr/)。 - 规避方案:改 SR 时保持对象名不变但先卸载,避免"半新半旧"。
- 适用版本:全部版本。
私有命令(RawAccessRead/RawAccessWrite、PluginRequest)的验证方式见 §2.2 的衍生接口要点;更多部件适配问题见《部件驱动接入导读》与各家族适配指南。
附录
附录A 参考资料
- 《部件驱动接入导读》
- 《总线芯片驱动开发指南》
- 《网卡驱动规范》
- 《GPU 驱动规范》
- 《南向硬盘驱动适配指南》
- 《南向风扇电源驱动适配指南》
- 组件内文档:
docs/3-DeviceMgmtContract.md、docs/2.1-总线芯片驱动开发指南.md、docs/2.2-设备驱动开发指南.md、docs/2.3-部件驱动接口模型设计.md - 宿主侧说明:《devmon》《hwproxy》《hwdiscovery》
附录B 修订记录
| 版本 | 日期 | 修订人 | 修订内容 |
|---|---|---|---|
| v1.0 | 2026-11-10 | openUBMC 社区 | 首版:组件概述、驱动 ABI 与设备树接口说明、SR/CSR 与裁剪说明、排障与 FAQ |