代码仓
中
component_drivers
更新时间: 2026/11/14
在AtomGit上查看源码

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)
驱动 ABIC 接口 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.*)是上层业务对象
DMCDevice Management Contract,dmc/intf(接口)+ dmc/path(对象路径与接口组合)
ABI v1 / v2CSR1(<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)、不同裁剪选项与不同驱动版本上可支持性不同,先确认驱动装没装、对象在不在,并把本节要用的对象路径赋给变量(后续各节的命令直接引用这些变量):

bash
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 输出形如(逐行一个对象路径,末段即对象名):

text
/bmc/dev/Systems/1/PCIeNicCard/PCIeNicCard_1_01
/bmc/dev/Systems/1/PCIeNicCard/PCIeNicCard_1_01/NicPort/1
/bmc/dev/Scanner/Scanner_Fan1_Presence_01

2.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_driverstatus_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 可省略
回调说明 ​
回调签名宿主调用时机说明
ctorhandle ctor(void* service, const char* object_name)创建对象壳必须 set_service + set_object_name,失败返回 nullptr
initstatus_t init(handle, void* csr_object, void* connector)上树前传 SR 对象属性字典与 connector 字典;解析配置、绑定内部件
start / stopstatus_t start(handle) / status_t stop(handle)主设备注册后 / 卸载回滚起停周期任务;子设备与通用对象只会有 init,不会被 start
dumpconst 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 版本"缓存,替换文件不等于重载。

调试示例 ​

命令行调试 ​
bash
# 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.csv

2.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
废弃状态正常可用

参数说明 ​

属性参数说明 ​
属性名类型读写说明取值范围
AddressU32RW器件地址(I2C 从地址等)I2C 0x00~0x7F
OffsetWidth / AddrWidthU8RW偏移 / 地址字节数OffsetWidth 0~4,AddrWidth 按手册
WriteTmout / ReadTmoutU32RW读写超时,单位 ms>0
RwBlockSizeU8RW单次块读写上限按总线能力
WriteInterval / ReadIntervalU8RW读写间隔,单位 ms0~255
WriteRetryTimes / ReadRetryTimes / DrvWriteDelayU8RW读写重试次数 / 写后延时(ms)0~255
HealthStatusU8RW健康状态0 访问正常、1 访问失败
HealthStatusValidityBooleanROHealthStatus 是否有效true、false
PowerStatus / SelfTestResultU8RO上电状态 / 自检结果器件定义
LockStatusU8RO锁状态0 未锁定、1 已锁定
ChipTypeStringRO器件类型名Chip、Pca9545、Smc 等
方法参数说明 ​
方法名D-Bus 签名入参出参说明取值范围
BitIOReaduyuOffset: U32、Length: U8、Mask: U32OutData: ay读后按 Mask 取值Length 仅 1/2/4
BitIOWriteuyuayOffset: U32、Length: U8、Mask: U32、InData: ay无读-改-写同上
BlockIOReaduuOffset: U32、Length: U32OutData: ay连续块读受 RwBlockSize 限制
BlockIOWriteuayOffset: U32、InData: ay无连续块写同上
BlockIOWriteReadayuInData: ay、ReadLength: U32OutData: ay写后读(扩展读)见器件实现
BlockIOComboWriteReaduayuuWriteOffset: U32、WriteBuffer: ay、ReadOffset/ReadLength: U32OutData: ay指定读写偏移的组合事务同块读/块写
RawAccessRead / RawAccessWritea{sv}Request: a{sv}OutData: ay / 无裸访问,按请求字典描述时序键含义见器件实现
SetAccessibilitybqStatus: Boolean、DisableDuration: U16无false 禁止该器件访问,到期自动恢复时长 1~1800 秒
SetLockStatusyuOpType: U8、LockTime: U32ResultCode: U80 解锁、1 加锁加锁 ≤ 30 分钟

说明

SetLockStatus 的上下文由框架从请求注入,表中列出的是业务参数;所有方法签名以 busctl --user introspect 输出为准。

衍生接口要点 ​
接口关键成员用途
bmc.kepler.Chip.BlockIOPluginRequest(Context, PluginName, Cmd, Params)、PluginRequestEx(...)、RawAccessRead/Write加载器件插件执行私有命令
bmc.dev.Chip.SelfDescriptionRecord / Chip.PowerMeter.InaFormatVersion/DataVersion/BoardId、GetSRData() → (status, sr) / PowerMultiplier/PowerDivisor/ChipModelEEPROM 回读自描述记录 / INA 功耗换算
bmc.dev.Chip.Pca9544 / Pca9545ChannelNumMux 通道数
bmc.dev.Chip.JtagTarget / bmc.kepler.Release.TraceChipGetChipIdcode、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 秒自动恢复,不要依赖它做长期禁用。

调试示例 ​

命令行调试 ​
bash
# 查健康状态与类型: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 60

2.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/**):

总线类专有接口关键专有属性
I2cbmc.dev.Bus.I2cId、Speed、Mode、SlaveAddr、UseSmbus
Hisportbmc.dev.Bus.HisportId、BusNum、RegNum、FlagNum、SendRegAddr、RecvRegAddr、FlagRegAddr、MaxBatchLen、MaxDataLen、MaxOffsetWidth、MaxLengthWidth
I2cMuxbmc.dev.MuxChannelId(当前通道,配合器件侧切通道)

参数说明 ​

属性参数说明(公共部分) ​
属性名类型读写说明取值范围
AccessEnabledBooleanRW总线访问开关,与器件级开关做"与"判定true、false
TimeoutU16RW总线级超时,单位 ms>0
方法参数说明 ​
方法名D-Bus 签名入参出参说明取值范围
SetAccessibilitybqStatus: Boolean、DisableDuration: U16无禁止/恢复整条总线访问时长 1~1800 秒

返回值与异常 ​

返回值 / 错误含义触发条件处理建议
无返回设置成功正常无
Call failed设置失败对象不存在、参数越界查对象路径与时长范围
其上器件读写全部失败总线级故障总线禁用、线路异常、参数不匹配查 AccessEnabled 与总线参数,必要时隔离

应用场景 ​

排障时整条线隔离(怀疑线序或电平问题);升级期间冻结某条带内/带外通道。

限制条件 ​

  • 总线必须先于其下器件创建(SR 拓扑顺序);
  • I2cMux 的通道切换由器件侧发起,总线对象不缓存当前通道;
  • 速率、时序参数改动后需重启宿主进程生效,不是热生效。

调试示例 ​

命令行调试 ​
bash
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 60

2.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) ​
属性名类型读写说明取值范围
ChipStringRW目标器件引用对象引用(ref_object)
OffsetU32RW读偏移按器件
SizeU8RW读长度(字节)位读 1/2/4;块读按器件
MaskU32RW取值掩码按位域
TypeU8RW读方式0 位读、其它值块读
ValueU64RO最近一次读取值-
属性参数说明(Scanner) ​
属性名类型读写说明取值范围
Chip / Offset / Size / Mask / Type同上RW读参数同上(Type:0 位读、1 块读)
PeriodU32RW扫描周期,单位 ms0 视为默认 3000;最小 100
DebounceStringRW去抖对象引用或内联配置引用/配置
ValueU64RO当前值-
StatusU8RO状态码,默认 40 正常、1 失败、2 预失败、3 停止、4 初始
NominalValue / ScanEnabledU64 / U8RW正常值(比较判定用)/ 扫描使能,默认 1- / 0、1
SuccessDebounceCount / FailureDebounceCountU8RW成功/失败防抖门限,默认 100~255
属性参数说明(去抖对象) ​
接口属性说明
bmc.dev.Debounce.Median / .AverageWindowSize: U32、IsSigned: Boolean滤波窗口长度、是否按有符号处理
bmc.dev.Debounce.Continue / .BinaryContinueCount: 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 可由表达式同步但不能成环;去抖对象单独创建不产生任何硬件动作。

调试示例 ​

命令行调试 ​
bash
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 0

2.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)OpticalTransceiverOpticalModule + .Status/.TemperatureCelsius/.Power/.Voltage/.Current/.Diagnose/.Channel/.Oem
GPU / 显存GraphicsController/${Id}、Memory/${DimmNum}Processor + .Metrics、Gpu + .Power/.Status;Memory + .Metrics

参数说明 ​

属性参数说明(bmc.dev.PCIeDevice) ​
属性名类型读写说明取值范围
DeviceName / LocationStringRW部件名称 / 位置字符串-
Slot / SocketId / SystemIdU8RW槽位号 / CPU Socket / 系统号Slot 1~255、SocketId 0/1、SystemId ≥1
Bus / Device / FunctionU8RWBDF0~255 / 0~31 / 0~7
SlotType / DeviceTypeStringRW槽位类型 / 设备类型枚举字符串
Model / Manufacturer / PartNumber / SerialNumber / FirmwareVersionStringRW资产信息(init 填或周期刷新)-
MaxPCIeType / PCIeTypeU8RW支持/当前链路代际1~5
MaxLanes / LaneInUseU8RW最大/实际链路宽度1、2、4、8、16
方法参数说明 ​
方法名D-Bus 签名入参出参说明取值范围
SetRootBDFyyyBus: U8、Device: U8、Function: U8Result: Boolean设置根 BDF三者全 0 非法,返回 false
衍生接口要点 ​
接口关键成员说明
PCIeDevice.PCIeFunctionClassCode: U32、VendorId/DeviceId/SubSystemVendorId/SubSystemDeviceId: String、BusNumber/DeviceNumber/FunctionNumber/SegmentNumber: U8;方法 SetDeviceBDF功能级标识
PCIeDevice.Status / .HotSwapUCEByBios、BandwidthReduced、LinkSpeedReduced、DiagnosticFault、PredictiveFault、FirmwareAbnormal(U8) / HotPluggable: Boolean、ReadyToRemove: U8故障位(位含义随厂商)/ 热插拔状态
PCIeDevice.BandwidthLinkWidthCapability/LinkWidth/LinkSpeedCapability/LinkSpeed: String、BandwidthThresholdPercent: U16带宽占用与阈值
PCIeCardName/Description/PcbVersion/BoardName/FormFactor: String、BoardId: U16、Health/PcbId/CardPowerGood: U8板卡身份与健康

返回值与异常 ​

返回值 / 错误含义触发条件处理建议
true / falseBDF 设置成功/失败参数合法 / 三者全 0换合法 BDF 重试
属性保持初值资产读取失败器件不可访问、厂商命令未适配查 Chip.HealthStatus 与该型号是否实现

应用场景 ​

上层组件按 PCIeDevice 判在位/资产、按 .Status 判故障;HotSwap.ReadyToRemove 用于免下电换卡;.Bandwidth 用于带宽占用率告警。

限制条件 ​

  • 一张卡的接口组合必须与 dmc/path 一致,缺接口会导致上游取不到值;
  • 子设备是相对路径,父对象不存在则整棵子树不上树;
  • 厂商私有命令走 *.Oem 或协议库,不要往标准接口里加私有属性。

调试示例 ​

命令行调试 ​
bash
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 1

2.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.NetworkAdapterManufacturerId: U32、Manufacturer/ChipModel/ChipVendor: String、NetworkPortCount/Type: U8、RefChip: String
bmc.dev.NetworkPort + .LinkInfo/.Metrics/.OemPortId: U8、MACAddress/BDF: String、NetDevFuncType: U8、LLDPEnabled: Boolean;LinkInfo 有 LinkStatus/SpeedMbps 与 SetSpeedGbps
bmc.dev.NetworkAdapter.LogCollectionDumpErrorLog、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 + .MetricsInfoRomVersion/UUID: String、Utilization: U16、RefChip: String;PowerCapacityWatts: U32;TemperatureCelsius: Double、PowerWatts: U16
内存bmc.dev.Memory + .MetricsTotalBytes/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.FanTypeFanId/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/.ExpanderNVMe:介质类型、磨损度、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 的包里有。

调试示例 ​

命令行调试 ​
bash
# 取 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 25769803776

2.7 与上位组件、宿主的边界 ​

角色关系
devmonCSR2(FormatVersion >= 5.00)宿主:装载本仓 .so、建 /bmc/dev/** 对象、导出 bmc.dev.*
hwproxyunidev(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.devmonbmc.kepler.hwproxy(Connector 在 bmc.kepler.hwdiscovery)
.so 命名lib<Name>.solibCsr1 前缀优先,退回 lib<Name>.so
方法签名一般不带 a{ss} 上下文首参带 a{ss},如 SetAccessibility a{ss}bq 0 false 60
拉取方法BitIORead/BlockIORead/BlockIOWriteReadChip.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() 注册:

cpp
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。

cpp
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;
}

步骤三 ​

接构建与测试,四处要同时改,漏一处就是"编进去了但装载不到":

  1. drivers/internal/chip/meson.build:加 subdir('chip_foo') 并把 chip_foo_sources 加入 chip_sources;
  2. drivers/internal/meson.build:install_headers('chip/chip_foo/foo.h', ...);
  3. drivers/chip/meson.build:加 subdir('foo'),shared_library('FooChip', link_whole: [foo_core_lib], install_dir: drivers_install_dir);
  4. tests/drivers/chip/foo/:单测 + ABI 测试(dlopen("./opt/bmc/drivers/libFooChip.so")),并在该目录 meson.build 注册 suite。

示例代码 ​

SR 侧只需一个对象(器件为相对路径,挂在父总线或 Mux 下):

json
{
  "FooChip_0": {
    "Address": 64,              // 器件地址,与硬件一致
    "AddrWidth": 1,             // 地址字节数
    "OffsetWidth": 2,           // 偏移字节数
    "WriteTmout": 100,          // 写超时 ms
    "ReadTmout": 100
  }
}

验证方法 ​

  1. meson compile -C builddir 后 ls builddir/opt/bmc/drivers/libFooChip.so 存在,且 nm -D 有 register_device_driver;
  2. 装机后 busctl --user tree $SVC 能列出 FooChip_ 前缀对象,ChipType 为 FooChip;
  3. 正常读写一次并对比硬件手册,确认 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 描述,四段结构决定一切:

json
{
  "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 配置区分

现网配置(网卡卡型示例,字段含义见注释):

json
{
  "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 构建选项与裁剪 ​

选项默认打开后的影响
unidevfalse编 drivers/csr1/**、drivers/connector、pcie_raid_card、pcie_nvme 及 CSR1 专有总线/器件
chipv2_enablefalse编 hisport2、i2c_over_hisport、i2c_over_localbus、i3c_over_localbus、spi_over_hisport、jtag_over_hisport
feature_ssufalse编 drivers/ssu_card 与 libraries/ssu_oob
feature_rs485false编 drivers/fan(当前实际只含 rs485)
feature_mellanoxtrue编 drivers/pcie_nic_card/mellanox
jtag_sec_mode_bcalfalseJTAG 安全模式 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.logunidev 下驱动日志归属 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.csvdevmon Dump 回调每个驱动 .so 的装载结果、设备表项数、耗时、失败原因
$DUMP/topology.txtdevmon / hwproxy Dump 回调设备树/资源树拓扑,确认对象是否上树与父子关系
$DUMP/snapshot.csvdevmon / hwproxy Dump 回调Scanner / Accessor 的 dump 文本(值、成功失败计数、是否来自聚合读)
$DUMP/chips_access_statistic.csvdevmon / 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>ERRORCompatible 拼出的 .so 不存在或表项缺失核对 .so 名与 device_name
Failed to load driver: <error>ERRORdlopen 失败(缺依赖、架构不符)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 emptyERRORcreate_chip/create_bus 收到空配置查 SR 中该对象的 Objects 段
device already exists, skip add deviceWARN同一 Position 重复加载先卸载再加载

6. 问题定界指南 ​

6.1 典型问题定界 ​

现象描述是否为本组件问题判断依据关键证据收集方法
某部件对象完全不上树通常是(驱动未装载或 SR 不匹配)无对应对象;日志有 Driver not found / failed to createcat $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/CLIbusctl --user introspect 对比两个服务;IPMI/CLI 转对应业务组件

6.2 调试方法 ​

6.2.1 查看对象与属性 ​

bash
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 查看系统侧状态与读值链路 ​

bash
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~5InvalidParameter / UnlockedError / 请求者·器件·通道不匹配时长非法、未加锁即解锁、解锁方与锁定方不一致、同通道其它器件已锁加锁 ≤ 30 分钟且同一调用方加解锁;释放冲突锁后重试

说明

本组件没有独立错误引擎,D-Bus 侧统一表现为 Call failed: <异常文本>;status_t 只用于 ABI 装载阶段,ResultCode 只在 SetLockStatus 出现。

6.4 最小化复现与证据收集 ​

  1. 记录接口名、对象路径、方法名与参数、返回文本,以及组件版本(grep -m1 '"version"' mds/service.json)。
  2. 固定前置条件:接口架构(单层还是 unidev)、对象是否上树、器件 HealthStatus 是否为 0、总线 AccessEnabled 是否为 true。
  3. 最小操作步骤:一条 busctl 命令(或一次 SR 加载),避免夹带无关读写。
  4. 保存证据:命令返回值、$DUMP/ 下 drivers_load_info.csv、snapshot.csv、topology.txt,以及宿主日志片段。
  5. 记录复现概率与环境差异(机型、单板、.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 参考资料 ​

附录B 修订记录 ​

版本日期修订人修订内容
v1.02026-11-10openUBMC 社区首版:组件概述、驱动 ABI 与设备树接口说明、SR/CSR 与裁剪说明、排障与 FAQ