Hwproxy 硬件代理
版本信息
| 项目 |
内容 |
| 组件版本 |
1.130.9 |
| 文档作者 |
openUBMC |
| 最后更新 |
2026-08-20 |
1. 组件概述
1.1 组件简介
Hwproxy(硬件代理)归属基础框架子系统,属于南向硬件管理的一部分。它通过SR(Self-Description Resource)数据与硬件自发现(hwdiscovery)获取自身对象配置与硬件拓扑关系,直接与用户态驱动进行交互,完成对硬件的访问。
Hwproxy采用主-工作服务架构:主服务(hwproxy_app)负责D-Bus对象注册与信号处理,每条总线创建独立的工作服务(hwproxy_work_app)进行硬件访问,监控服务(monitor)负责工作服务健康看护。
1.2 解决什么问题
在没有统一硬件访问层的情况下,业务组件直接与各类总线(I2C、JTAG、LocalBus、GPIO、SPI等)和芯片驱动交互,导致:
- 效率低:各组件重复实现硬件轮询逻辑
- 易出错:协议细节分散在各组件中,难以统一维护
- 扩展性差:新增硬件设备需改动多个组件
Hwproxy提供统一的硬件访问接口,屏蔽底层总线差异和协议细节,使业务组件仅需通过D-Bus属性同步/引用即可获取硬件数据或控制硬件,大幅简化开发适配。
1.3 核心功能
- 硬件拓扑管理:从SR数据和hwdiscovery获取对象配置与拓扑关系,构建内存中的总线→Mux→芯片拓扑树
- Scanner周期扫描:对配置的Scanner对象按指定周期轮询硬件,经防抖算法处理后更新到D-Bus资源树,适用于温度、在位状态等周期性采集场景
- Accessor按需访问:监听D-Bus属性读写信号,实时读取或写入硬件值,适用于非周期性的硬件读写场景
- 防抖算法:支持MidAvg(中值平均)、Median(中位数)、Cont(连续值防抖)、ContBin(连续值二值防抖)、None(无防抖)五种防抖策略
- CPLD固件升级:通过JTAG接口支持CPLD固件的收集(Collect)、升级(Upgrade)、验证(Verify)
- 制造自检(DFT):支持制造场景下的硬件自检功能,提供Start/Stop/GetResult接口
- 芯片访问保护:提供芯片级可访问性控制(SetAccessibility)和锁定控制(SetLockStatus),支持请求队列溢出保护
- 可观测性:通过OpenTelemetry暴露芯片I/O、Scanner扫描、Accessor访问三类指标,支持分布式追踪
1.4 支持的总线与芯片类型
总线类型
| 总线类型 |
说明 |
特殊配置 |
| I2c |
标准I2C总线 |
支持总线级BlockIO |
| I2cOverLocalBus |
基于LocalBus的I2C总线 |
-- |
| I3cOverLocalBus |
基于LocalBus的I3C总线 |
-- |
| Hisport |
Hisport总线 |
scan_interval=100ms,支持合并(多条Hisport共享工作服务) |
| Hisport2 |
Hisport扩展总线 |
类型为ExpansionBus |
| LocalBus |
LocalBus总线 |
-- |
| Jtag |
JTAG总线 |
-- |
| JtagOverLocalBus |
基于LocalBus的JTAG总线 |
-- |
| JtagOverGpio |
基于GPIO的JTAG总线 |
-- |
| Gpio |
GPIO总线 |
-- |
| Adc |
ADC总线 |
-- |
| Can |
CAN总线 |
-- |
| I2cOverHisport |
基于Hisport的I2C总线 |
-- |
| SPIOverHisport |
基于Hisport的SPI总线 |
-- |
| JtagOverHisport |
基于Hisport的JTAG总线 |
-- |
| InnerBus |
内部总线 |
-- |
芯片类型
| 芯片类型 |
支持的接口能力 |
说明 |
| Chip |
BlockIO, WriteRead, ComboWriteRead, WriteReadByProtocol, Trace |
通用芯片 |
| Smc |
BlockIO, BitIO, Trace |
SMC管理芯片 |
| Eeprom |
BlockIO, Trace |
EEPROM存储芯片 |
| Rtc |
BlockIO, Trace |
RTC时钟芯片 |
| Pca9545 |
Trace |
I2C Mux(PCA9545) |
| Pca9544 |
Trace |
I2C Mux(PCA9544) |
| Pca9555 |
BlockIO, BitIO, Trace |
I2C GPIO扩展器 |
| Lm75 |
BlockIO, BitIO, Trace |
温度传感器 |
| Vrd |
BlockIO, BitIO, Trace |
电压调节器 |
| Ina |
BlockIO, BitIO, Trace |
功率计(支持Ina238/Ina226/Ina220子型号) |
| Ads78 |
Trace |
ADC芯片 |
| Cpld |
BlockIO, Trace |
CPLD芯片(request_timeout=-1,不设超时) |
| CpldRegister |
Trace |
CPLD寄存器 |
| CpldChip |
BlockIO, BitIO, Trace |
CPLD芯片(扩展版) |
| SPIFlash |
BlockIO, FlashIO, Trace |
SPI Flash芯片 |
| CanbusChip |
BlockIO, BitIO, WriteRead, Trace |
CAN总线芯片 |
| JtagSwitch |
-- |
JTAG切换芯片 |
| JtagMux |
-- |
JTAG Mux |
1.5 关键术语表
| 术语 |
解释 |
| SR(Self-Description Resource) |
自描述资源,定义硬件拓扑关系和对象配置的数据文件,存储在天池组件Eeprom或BMC Flash中 |
| Scanner |
周期扫描器,按配置的Period周期轮询硬件,值自动更新到D-Bus资源树,属性只读 |
| Accessor |
按需访问器,当业务组件读取或写入D-Bus属性时实时访问硬件,属性可读写 |
| CSR(Component Resource Configuration) |
组件资源配置格式,定义Scanner/Accessor等对象的具体参数(偏移、长度、掩码等) |
| Debounce(防抖) |
对Scanner读取的原始值进行滤波处理的算法,消除硬件信号抖动导致的误判 |
| Mux(多路复用器) |
I2C/JTAG总线上的通道切换器件(如PCA9545),用于在同一条总线上挂载多个设备 |
| Stream |
总线访问抽象层,封装不同总线类型(I2C、LocalBus、Hisport等)的读写操作 |
| 拓扑链路 |
从Bus到Mux到Chip的完整访问路径,hwproxy据此确定硬件访问的先后顺序 |
| 同步语法(<=/) |
CSR中Scanner.Value的关联方式,业务属性自动同步Scanner扫描值,只读 |
| 引用语法(#/) |
CSR中Accessor.Value的关联方式,业务属性触发实时硬件访问,可读写 |
| DFT(Design For Test) |
制造自检对象,支持产线测试时对I2C、GPIO等器件进行检测 |
1.6 外部交互边界图
┌─────────────────────────────────────────────────────────────────┐
│ 业务组件层 │
│ (fru_mgmt, sensor_mgmt, psu_mgmt, cpld_upgrade, ...) │
└────────────┬──────────────────────────────────┬─────────────────┘
│ D-Bus 属性同步/引用 │ D-Bus 方法调用
│ (Scanner.Value / Accessor.Value) │ (BlockIO/BitIO/FlashIO/JtagTarget)
▼ ▼
┌─────────────────────────────────────────────────────────────────┐
│ D-Bus 资源树 (sd_bus) │
│ bmc.kepler.hwproxy 服务 │
└────────────┬──────────────────────────────────┬─────────────────┘
│ 对象注册 & 信号回调 │ 硬件读写请求
▼ ▼
┌─────────────────────────────────────────────────────────────────┐
│ Hwproxy │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
│ │ 主服务 │ │ 工作服务 │ │ 监控服务 │ │
│ │ (hwproxy_app) │──│(work_app)×N │──│ (monitor) │ │
│ │ 对象管理/注册 │ │ 扫描/读写 │ │ 心跳检测/自动重启 │ │
│ └──────────────┘ └──────┬───────┘ └──────────────────────┘ │
└────────────────────────────┼────────────────────────────────────┘
│ Stream 读写
▼
┌─────────────────────────────────────────────────────────────────┐
│ 用户态驱动层 │
│ I2C Driver │ LocalBus Driver │ JTAG Driver │ GPIO Driver │ ... │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 硬件设备 │
│ Sensor │ EEPROM │ CPLD │ Mux │ VRD │ INA │ SPI Flash │ ... │
└─────────────────────────────────────────────────────────────────┘
外部依赖服务:
- hwdiscovery: 提供硬件对象数据与拓扑关系
- mdb_mgmt: MDB管理与D-Bus服务基础设施
- persistence: 状态持久化
2. API 使用说明与示例
CSR配置参考
Scanner和Accessor通过CSR格式定义,关键参数如下:
Scanner参数:Chip(挂载芯片,#/ChipName)、Offset(偏移)、Size(长度)、Mask(掩码,位读有效)、Type(0=位读,1=块读)、Period(扫描周期ms,默认3000,最小100)、Debounce(防抖对象名,默认None)、ScanEnabled(0=禁用,1=启用)、NominalValue(标称值)、FailureDebounceCount/SuccessDebounceCount(失败/成功防抖次数)
Accessor参数:Chip、Offset、Size、Mask、Type、WriteOffset(写入偏移,默认与Offset相同)、FailureDebounceCount/SuccessDebounceCount
防抖算法:None(无防抖)、MidAvg(窗口取平均,参数:WindowSize/DefaultValue/IsSigned)、Median(窗口取中位数,参数同MidAvg)、Cont(连续变化N次后更新,参数:Num/DefaultValue)、ContBin(二值连续防抖,参数:NumH/NumL/DefaultValue)
CSR关联语法:<=/Scanner_X.Value(同步,只读)、#/Accessor_X.Value(引用,可读写)
2.1 bmc.kepler.Chip.BlockIO 块读写接口
功能说明
提供对芯片的块级读写操作,是访问I2C/LocalBus等总线上芯片的标准接口。支持普通读写、扩展读(WriteRead)、原子写后读(ComboWriteRead)、批量写(BatchWrite)和插件请求(PluginRequest)。
| 属性 |
内容 |
| 接口名 |
bmc.kepler.Chip.BlockIO |
| 首发版本 |
1.120.0 |
| 废弃状态 |
正常可用 |
参数说明
Read 方法
| 参数名 |
方向 |
类型 |
描述 |
取值范围 |
| Offset |
输入 |
a{ss}uu |
读取偏移地址 |
0 ~ 0xFFFFFFFF |
| Length |
输入 |
a{ss}uu |
读取数据长度(字节) |
1 ~ 芯片支持的最大长度 |
| OutData |
输出 |
ay |
读取到的数据 |
字节数组 |
Write 方法
| 参数名 |
方向 |
类型 |
描述 |
取值范围 |
| Offset |
输入 |
a{ss}uay |
写入偏移地址 |
0 ~ 0xFFFFFFFF |
| InData |
输入 |
a{ss}uay |
写入数据 |
字节数组 |
WriteRead 方法(扩展读,适用于Offset超长或读数据时除Offset外还有其他数据的场景)
| 参数名 |
方向 |
类型 |
描述 |
取值范围 |
| InData |
输入 |
a{ss}ayu |
写入数据(含Offset等信息) |
字节数组 |
| ReadLength |
输入 |
a{ss}ayu |
读取数据长度 |
1 ~ 芯片支持的最大长度 |
| OutData |
输出 |
ay |
读取到的数据 |
字节数组 |
ComboWriteRead 方法(原子写后读,避免写与读之间被其他写请求干扰)
| 参数名 |
方向 |
类型 |
描述 |
取值范围 |
| WriteOffset |
输入 |
a{ss}uayuu |
写入偏移地址 |
0 ~ 0xFFFFFFFF |
| InData |
输入 |
a{ss}uayuu |
写入数据 |
字节数组 |
| ReadOffset |
输入 |
a{ss}uayuu |
读取偏移地址 |
0 ~ 0xFFFFFFFF |
| ReadLength |
输入 |
a{ss}uayuu |
读取数据长度 |
1 ~ 芯片支持的最大长度 |
| OutData |
输出 |
ay |
读取到的数据 |
字节数组 |
BatchWrite 方法(批量写,适用于升级等多帧数据场景)
| 参数名 |
方向 |
类型 |
描述 |
取值范围 |
| a(Offset,InData) |
输入 |
a{ss}a(uay) |
多组{偏移+数据} |
每组偏移0~0xFFFFFFFF |
PluginRequest 方法(插件请求,用于芯片特定的自定义操作)
| 参数名 |
方向 |
类型 |
描述 |
取值范围 |
| PluginName |
输入 |
a{ss}ssay |
插件名称 |
已注册的插件名 |
| Cmd |
输入 |
a{ss}ssay |
命令字 |
插件定义的合法命令 |
| Params |
输入 |
a{ss}ssay |
参数 |
字节数组 |
| OutData |
输出 |
ay |
返回数据 |
字节数组 |
返回值与异常
| 返回值 |
含义 |
触发条件 |
处理建议 |
| 0 |
成功 |
正常执行完成 |
无 |
| kepler.hwproxy.IOError |
I/O错误 |
硬件通信失败(总线超时、NACK等) |
检查硬件连接和总线状态 |
| kepler.hwproxy.ChipNotExistError |
芯片不存在 |
在拓扑链路中找不到目标芯片 |
检查SR配置中的Chip引用是否正确 |
| kepler.hwproxy.RequestTimeout |
请求超时 |
硬件访问超时 |
检查总线是否被占用或芯片响应是否正常 |
| ChipRequestLimitExceeded |
请求队列溢出 |
同一芯片请求队列超过上限(默认500) |
减少并发请求量,检查是否有请求堆积 |
应用场景
- 读取EEPROM中的VPD信息(Read)
- 写入配置数据到芯片寄存器(Write)
- 读取SMC芯片扩展寄存器(WriteRead)
- CPLD升级中原子写后读操作(ComboWriteRead)
- 批量写入升级固件数据(BatchWrite)
- 芯片特定功能的自定义操作(PluginRequest)
限制条件
- 不同芯片类型支持的方法子集不同,由
object_defs.lua中的support_block_io、support_block_write_read、support_block_combo_write_read等标志决定
- 每个芯片有独立的请求队列,队列长度上限由环境变量
CHIP_REQUEST_QUEUE_MAX_LEN控制(默认500,范围100~1000)
- 芯片被SetAccessibility关闭或SetLockStatus锁定后,访问请求将返回错误
- WriteRead/ComboWriteRead仅在支持该能力的芯片类型上可用(如Chip、CpldChip等)
调试示例
命令行调试
# 读取EEPROM从偏移0开始24字节(a{ss}为D-Bus字典参数,通常传0)
~ # busctl --user call bmc.kepler.hwproxy /bmc/kepler/Chip/Eeprom/Eeprom_BCU_010101 bmc.kepler.Chip.BlockIO Read a{ss}uu 0 24
ay 24 48 48 48 48 48 48 48 49 48 50 48 51 48 50 48 51 49 56 50 53 0 0 0 0
# 写入数据到EEPROM(a{ss}uay中ay为写入的字节数组)
~ # busctl --user call bmc.kepler.hwproxy /bmc/kepler/Chip/Eeprom/Eeprom_BCU_010101 bmc.kepler.Chip.BlockIO Write a{ss}uay 0 0 10 0 0 0 0 0 0 0 0 90 165
2.2 bmc.kepler.Chip.BitIO 位读写接口
功能说明
提供对芯片的位级读写操作,适用于需要对寄存器中特定位进行读取或修改的场景。位操作由对应芯片的用户态驱动实现,I2C总线上的数据实际以字节为单位进行块操作。
| 属性 |
内容 |
| 接口名 |
bmc.kepler.Chip.BitIO |
| 首发版本 |
1.120.0 |
| 废弃状态 |
正常可用 |
参数说明
Read 方法
| 参数名 |
方向 |
类型 |
描述 |
取值范围 |
| Offset |
输入 |
a{ss}uyu |
寄存器偏移地址 |
0 ~ 0xFFFFFFFF |
| Length |
输入 |
a{ss}uyu |
读取长度(字节) |
1 ~ 芯片支持的最大长度 |
| Mask |
输入 |
a{ss}uyu |
位掩码 |
0 ~ 0xFFFFFFFF,按位与操作 |
| OutData |
输出 |
ay |
读取到的数据 |
字节数组 |
Write 方法
| 参数名 |
方向 |
类型 |
描述 |
取值范围 |
| Offset |
输入 |
a{ss}uyuay |
寄存器偏移地址 |
0 ~ 0xFFFFFFFF |
| Length |
输入 |
a{ss}uyuay |
读取长度(字节) |
1 ~ 芯片支持的最大长度 |
| Mask |
输入 |
a{ss}uyuay |
位掩码 |
0 ~ 0xFFFFFFFF |
| InData |
输入 |
a{ss}uyuay |
写入数据 |
字节数组 |
返回值与异常
| 返回值 |
含义 |
触发条件 |
处理建议 |
| 0 |
成功 |
正常执行完成 |
无 |
| kepler.hwproxy.IOError |
I/O错误 |
硬件通信失败 |
检查硬件连接和总线状态 |
| kepler.hwproxy.ChipNotExistError |
芯片不存在 |
拓扑链路中找不到目标芯片 |
检查SR配置 |
应用场景
- 读取SMC芯片状态寄存器中的特定位(如电源状态位)
- 修改GPIO扩展器(如PCA9555)的特定引脚状态
- 读取VRD芯片的告警标志位
限制条件
- 仅支持配置了
support_bit_io标志的芯片类型(如Smc、Pca9555、Lm75、Vrd、Ina、CpldChip)
- 写入时先读取当前值,按掩码修改后再写回,非原子操作
调试示例
命令行调试
# 位读:读取SMC芯片偏移0x2100处1字节,掩码0x0f
~ # busctl --user call bmc.kepler.hwproxy /bmc/kepler/Chip/Smc/Smc_CpuBrdSMC_010101 bmc.kepler.Chip.BitIO Read a{ss}uyu 0 0x2100 1 0x0f
ay 1 10
# 位写:向SMC芯片偏移0x2200处写入1字节,掩码0x0f,数据0x02
~ # busctl --user call bmc.kepler.hwproxy /bmc/kepler/Chip/Smc/Smc_CpuBrdSMC_010101 bmc.kepler.Chip.BitIO Write a{ss}uyuay 0 0x2200 1 0x0f 1 0x02
# 回读验证
~ # busctl --user call bmc.kepler.hwproxy /bmc/kepler/Chip/Smc/Smc_CpuBrdSMC_010101 bmc.kepler.Chip.BitIO Read a{ss}uyu 0 0x2100 1 0x0f
ay 1 2
2.3 bmc.kepler.Chip.FlashIO Flash读写接口
功能说明
提供对SPI Flash芯片的专用操作接口,包括原始读写(RawRead/RawWrite)和擦除(Erase),以及标准读写(Read/Write,与BlockIO的读写功能一致)。
| 属性 |
内容 |
| 接口名 |
bmc.kepler.Chip.FlashIO |
| 首发版本 |
1.120.0 |
| 废弃状态 |
正常可用 |
参数说明
| 方法 |
参数签名In |
参数签名Out |
描述 |
| RawRead |
a{ss}uu (Offset, Length) |
ay (OutData) |
原始读,用户自定义格式帧 |
| RawWrite |
a{ss}uay (Offset, InData) |
-- |
原始写,用户自定义格式帧 |
| Erase |
a{ss}uu (Offset, Length) |
-- |
Flash擦除 |
| Read |
a{ss}uu (Offset, Length) |
ay (OutData) |
标准读(等同BlockIO.Read) |
| Write |
a{ss}uay (Offset, InData) |
-- |
标准写(等同BlockIO.Write) |
应用场景
- SPI Flash固件升级场景:先Erase,再RawWrite或Write写入新固件
- 自定义Flash命令交互(RawRead/RawWrite支持用户自定义格式帧)
限制条件
- 仅SPIFlash类型芯片支持此接口
- Flash擦除操作不可逆,需谨慎调用
调试示例
# 读取SPI Flash偏移0处256字节
~ # busctl --user call bmc.kepler.hwproxy /bmc/kepler/Chip/SPIFlash/SPIFlash_010101 bmc.kepler.Chip.FlashIO Read a{ss}uu 0 256
# 擦除SPI Flash偏移0开始65536字节
~ # busctl --user call bmc.kepler.hwproxy /bmc/kepler/Chip/SPIFlash/SPIFlash_010101 bmc.kepler.Chip.FlashIO Erase a{ss}uu 0 65536
2.4 bmc.kepler.Chip.JtagTarget JTAG升级接口
功能说明
提供CPLD芯片通过JTAG总线进行固件升级的接口,包括收集升级数据、执行升级、验证结果、获取芯片ID等操作。
| 属性 |
内容 |
| 接口名 |
bmc.kepler.Chip.JtagTarget |
| 首发版本 |
1.120.0 |
| 废弃状态 |
正常可用 |
参数说明
| 方法 |
描述 |
| Collect |
收集升级数据 |
| Upgrade |
执行CPLD固件升级 |
| Verify |
验证升级结果 |
| GetChipIdcode |
获取CPLD芯片ID |
| SetTargetNumber |
设置JTAG目标编号 |
| SetBypassMode |
设置JTAG旁路模式 |
| BypassChannelTest |
测试旁路通道连通性 |
返回值与异常
| 返回值 |
含义 |
触发条件 |
处理建议 |
| 0 |
成功 |
正常执行完成 |
无 |
| kepler.hwproxy.IOError |
I/O错误 |
JTAG通信失败 |
检查JTAG链路和CPLD状态 |
| kepler.hwproxy.RequestTimeout |
请求超时 |
升级过程超时 |
CPLD升级默认不设超时(request_timeout=-1) |
应用场景
- CPLD在线升级:通过JTAG接口完成固件收集、升级、验证全流程
- 多JTAG设备级联场景下设置目标编号和旁路模式
限制条件
- 仅Cpld类型芯片支持此接口
- 升级过程默认无超时限制(request_timeout=-1),升级时间取决于固件大小
- 升级期间同一JTAG链路上其他芯片的访问将被阻塞
调试示例
# 获取CPLD芯片ID
~ # busctl --user call bmc.kepler.hwproxy /bmc/kepler/Chip/Cpld/Cpld_010101 bmc.kepler.Chip.JtagTarget GetChipIdcode
# 执行CPLD升级
~ # busctl --user call bmc.kepler.hwproxy /bmc/kepler/Chip/Cpld/Cpld_010101 bmc.kepler.Chip.JtagTarget Upgrade ...
# 验证升级结果
~ # busctl --user call bmc.kepler.hwproxy /bmc/kepler/Chip/Cpld/Cpld_010101 bmc.kepler.Chip.JtagTarget Verify ...
2.5 bmc.kepler.Chip 芯片基础接口
功能说明
提供芯片级别的状态查询与控制接口,包括健康状态、电源状态、自检结果、可访问性和锁定状态的查询与设置。
| 属性 |
内容 |
| 接口名 |
bmc.kepler.Chip |
| 首发版本 |
1.120.0 |
| 废弃状态 |
正常可用 |
属性说明
| 属性名 |
类型 |
访问权限 |
描述 |
| HealthStatus |
U8 |
只读 |
芯片健康状态 |
| PowerStatus |
U8 |
只读 |
芯片电源状态 |
| SelfTestResult |
U8 |
只读 |
自检结果 |
| Accessibility |
U8 |
只读 |
芯片可访问性状态 |
| LockStatus |
U8 |
只读 |
芯片锁定状态 |
方法说明
| 方法 |
参数 |
描述 |
| SetAccessibility |
Status(U8), DisableDuration(U32) |
设置芯片可访问性,Status=0关闭、1开启;DisableDuration为关闭持续时间(秒),范围1~1800 |
| SetLockStatus |
OpType(U8), LockTime(U32) |
设置芯片锁定状态,OpType=0加锁、1解锁;LockTime为锁定持续时间(秒) |
调试示例
# 查询芯片健康状态
~ # busctl --user get-property bmc.kepler.hwproxy /bmc/kepler/Chip/Smc/Smc_CpuBrdSMC_010101 bmc.kepler.Chip HealthStatus
# 临时关闭芯片访问(持续60秒)
~ # busctl --user call bmc.kepler.hwproxy /bmc/kepler/Chip/Smc/Smc_CpuBrdSMC_010101 bmc.kepler.Chip SetAccessibility uu 0 60
2.6 bmc.kepler.Scanner 扫描器接口
功能说明
Scanner是hwproxy内部周期性扫描硬件的机制,扫描值自动更新到D-Bus资源树。业务组件通过CSR同步语法(<=/Scanner_X.Value)关联Scanner的Value属性,即可获取硬件扫描值,无需主动调用。
| 属性 |
内容 |
| 接口名 |
bmc.kepler.Scanner |
| 首发版本 |
1.120.0 |
| 废弃状态 |
正常可用 |
属性说明
| 属性名 |
类型 |
访问权限 |
描述 |
| Value |
U64 |
只读 |
扫描值 |
| Status |
-- |
只读 |
扫描状态 |
调试示例
# 查询Scanner当前值
~ # busctl --user get-property bmc.kepler.hwproxy /bmc/kepler/Scanner/Scanner_PSU_1 bmc.kepler.Scanner Value
# 追踪Scanner防抖详情(需要DiagnoseMgmt权限)
~ # busctl --user call bmc.kepler.hwproxy /bmc/kepler/Scanner/Scanner_PSU_1 bmc.kepler.Release.Scanner TraceDebounce s "start"
2.7 bmc.kepler.Accessor 访问器接口
功能说明
Accessor是按需访问硬件的机制,当业务组件读取或写入Accessor.Value属性时,hwproxy实时访问硬件并返回结果。通过CSR引用语法(#/Accessor_X.Value)关联。
| 属性 |
内容 |
| 接口名 |
bmc.kepler.Accessor |
| 首发版本 |
1.120.0 |
| 废弃状态 |
正常可用 |
属性说明
| 属性名 |
类型 |
访问权限 |
描述 |
| Value |
U64 |
读写 |
访问器值(读取时从硬件获取,写入时写入硬件) |
| Status |
-- |
只读 |
访问器状态 |
| PrintableValue |
-- |
只读 |
值的可打印表示 |
调试示例
# 读取Accessor当前值
~ # busctl --user get-property bmc.kepler.hwproxy /bmc/kepler/Accessor/Accessor_PwrButtonLock bmc.kepler.Accessor Value
# 写入Accessor值
~ # busctl --user set-property bmc.kepler.hwproxy /bmc/kepler/Accessor/Accessor_PwrButtonLock bmc.kepler.Accessor Value u 1
2.8 bmc.kepler.Bus 总线接口
功能说明
提供总线级别的状态查询与控制接口。
| 属性 |
内容 |
| 接口名 |
bmc.kepler.Bus |
| 首发版本 |
1.120.0 |
| 废弃状态 |
正常可用 |
属性说明
| 属性名 |
类型 |
描述 |
| AccessEnabled |
U8 |
总线访问使能状态 |
| Timeout |
U8 |
总线超时时间 |
方法说明
| 方法 |
参数 |
描述 |
| SetAccessibility |
Status(U8), DisableDuration(U32) |
设置总线可访问性 |
调试示例
# 查询总线访问使能状态
~ # busctl --user get-property bmc.kepler.hwproxy /bmc/kepler/Bus/I2c_1 bmc.kepler.Bus AccessEnabled
2.9 bmc.kepler.Bus.BlockIO 总线级块读写接口
功能说明
提供I2C总线级别的块读写操作(不经过芯片驱动,直接与总线交互),仅I2c类型总线支持。
| 属性 |
内容 |
| 接口名 |
bmc.kepler.Bus.BlockIO |
| 首发版本 |
1.120.0 |
| 废弃状态 |
正常可用 |
方法说明
| 方法 |
描述 |
| Read |
总线级块读 |
| Write |
总线级块写 |
| WriteRead |
总线级写后读 |
调试示例
# 总线级块读(I2c总线直接读取,需指定设备地址)
~ # busctl --user call bmc.kepler.hwproxy /bmc/kepler/Bus/I2c_1 bmc.kepler.Bus.BlockIO Read a{ss}uu 0 32
2.10 bmc.kepler.Manufacture 制造自检接口
功能说明
提供制造场景下的硬件自检能力,支持启动、停止和获取自检结果。
| 属性 |
内容 |
| 接口名 |
bmc.kepler.Manufacture |
| 首发版本 |
1.120.0 |
| 废弃状态 |
正常可用 |
方法说明
| 方法 |
描述 |
| Start |
启动自检 |
| Stop |
停止自检 |
| GetResult |
获取自检结果 |
调试示例
# 启动制造自检
~ # busctl --user call bmc.kepler.hwproxy /bmc/kepler/Manufacture/DftPca9555/DftPca9555_010101 bmc.kepler.Manufacture Start
# 获取自检结果
~ # busctl --user call bmc.kepler.hwproxy /bmc/kepler/Manufacture/DftPca9555/DftPca9555_010101 bmc.kepler.Manufacture GetResult
# 停止自检
~ # busctl --user call bmc.kepler.hwproxy /bmc/kepler/Manufacture/DftPca9555/DftPca9555_010101 bmc.kepler.Manufacture Stop
2.11 bmc.kepler.Debug.Mock 调试Mock接口
功能说明
提供测试/调试用的Mock接口,用于模拟Scanner故障和总线控制,仅在非Release版本中可用。
| 属性 |
内容 |
| 接口名 |
bmc.kepler.Debug.Mock |
| 首发版本 |
1.120.0 |
| 废弃状态 |
仅用于调试 |
方法说明
| 方法 |
描述 |
| MockScannerFailure |
模拟Scanner扫描失败 |
| MockBusCtrl |
控制总线模拟(挂起/恢复) |
调试示例
# 模拟Scanner扫描失败(持续30秒)
~ # busctl --user call bmc.kepler.hwproxy /bmc/kepler/Mock/Mock bmc.kepler.Debug.Mock MockScannerFailure s "Scanner_PSU_1" u 30
# 挂起总线
~ # busctl --user call bmc.kepler.hwproxy /bmc/kepler/Mock/Mock bmc.kepler.Debug.Mock MockBusCtrl s "I2c_1" s "suspend"
# 恢复总线
~ # busctl --user call bmc.kepler.hwproxy /bmc/kepler/Mock/Mock bmc.kepler.Debug.Mock MockBusCtrl s "I2c_1" s "resume"
3. 组件扩展案例
3.1 扩展能力概述
Hwproxy提供以下扩展能力:
- 新增芯片类型:通过在
object_defs.lua中注册新的芯片类定义,即可支持新的硬件器件
- 新增总线类型:通过实现Stream接口并注册,即可支持新的总线协议
- 新增防抖算法:通过扩展
mc.debounce.debounce并在object_defs.lua中添加Debounce类型
- 插件机制:通过PluginRequest接口和插件目录注册自定义芯片操作插件
- 制造自检扩展:通过添加Dft对象类型,自动注册Start/Stop/GetResult方法
3.2 扩展点说明
| 扩展点 |
位置 |
触发时机 |
说明 |
| 芯片类型注册 |
src/lualib/object_defs.lua |
对象添加时(AddObject回调) |
定义芯片类型名、回调函数、支持的接口能力标志 |
| 总线Stream实现 |
外部模块stream.* |
工作服务创建总线对象时 |
实现read/write等总线操作接口 |
| 防抖算法扩展 |
src/lualib/object_defs.lua + mc.debounce.debounce |
Scanner扫描值处理时 |
新增Debounce类型和算法实现 |
| 插件注册 |
hwproxy_objects/work_objects.lua |
PluginRequest方法调用时 |
注册自定义插件名和处理函数 |
| MDS模型扩展 |
mds/schema.json / mds/model.json |
代码生成与服务启动时 |
定义新的对象类型、属性和D-Bus接口映射 |
| 制造自检对象 |
src/lualib/object_defs.lua(Dft类型) |
Dft对象添加时 |
自动注册Start/Stop/GetResult到Manufacture接口 |
3.3 二次开发指导
以新增一种芯片类型为例:
步骤一:在object_defs.lua中注册芯片类型
在src/lualib/object_defs.lua中添加新的芯片定义:
objects.NewChipType = {
['type'] = 'Chip',
['add_call_back'] = 'chip_object_handle',
['support_block_io'] = true,
['support_bit_io'] = true,
['support_block_write_read'] = true,
['support_trace'] = true
}
支持的标志位包括:
support_block_io:块读写(BlockIO)
support_bit_io:位读写(BitIO)
support_block_write_read:扩展读(WriteRead)
support_block_combo_write_read:原子写后读(ComboWriteRead)
support_block_write_read_by_protocol:按协议扩展读
support_flash_io:Flash读写(FlashIO)
support_trace:芯片追踪(TraceChip)
support_bus_block_io:总线级块读写
support_chip_module:支持的芯片型号子集(如Ina的Ina238/Ina226/Ina220)
request_timeout:自定义请求超时时间(秒),-1表示无超时
步骤二:实现用户态驱动
在driver.*模块中实现新芯片的驱动,提供read/write方法:
local driver = {}
function driver.read(chip, offset, length)
return data
end
function driver.write(chip, offset, data)
return true
end
return driver
步骤三:更新MDS模型定义
- 在
mds/schema.json中添加NewChipType的对象定义和属性
- 在
mds/model.json中添加NewChipType到D-Bus路径和接口的映射
验证方法
- 编译组件并部署到测试环境
- 使用busctl验证新芯片对象已正确注册到D-Bus资源树
- 使用busctl调用BlockIO.Read/Write验证硬件读写功能正常
- 使用TraceChip追踪芯片访问日志确认路径正确
注意事项
- 芯片类型名称需与SR中的Class名称前缀一致(如
NewChipType_XXX)
- 同一总线上相同地址的不同类型芯片会被自动合并,合并时会产生警告日志
- 新增芯片类型需确保对应总线类型的Stream已实现
support_chip_module不设置时表示支持所有型号;设置后仅支持列出的型号
3.4 插件开发指导
通过PluginRequest接口可实现芯片特定的自定义操作。插件模块放在hwproxy/plugins/目录下:
local plugin = {}
plugin.__index = plugin
function plugin.new(service)
return setmetatable({service = service}, plugin)
end
function plugin:has_cmd(cmd)
return cmd == "custom_read" or cmd == "custom_write"
end
function plugin:run_cmd(chip_obj, cmd, ...)
if cmd == "custom_read" then
return chip_obj:driver_read(...)
elseif cmd == "custom_write" then
return chip_obj:driver_write(...)
end
end
return plugin
验证:通过busctl调用PluginRequest,指定PluginName为test_plugin,Cmd为custom_read。
注意事项:插件按需加载(首次调用时require),需确保插件模块路径正确;插件命令在芯片请求队列中作为plugin类型排队执行。
4. 日志说明
4.1 一键日志收集
执行系统一键日志收集功能时,hwproxy组件会收集以下日志文件:
| 文件路径 |
内容说明 |
| /var/log/framework/hwproxy.log |
主日志文件,包含组件运行时的全部日志信息 |
| {dump_path}/snapshot.csv |
Scanner/Accessor当前值快照,包含芯片名、扫描器/访问器名、周期、状态、成功/失败计数、当前值、信号发射计数、错误信息 |
| {dump_path}/topology.txt |
硬件拓扑树结构,包含Bus→Mux→Chip的完整连接关系及芯片别名映射 |
| {dump_path}/smc_dfx_info.txt |
SMC DFX诊断信息,包含聚合扫描的数据详情 |
| {dump_path}/chips_access_statistic.csv |
芯片访问统计,包含每个芯片的读写成功/失败计数、统计时长、每秒访问次数、最近错误记录(仅非Release版本收集) |
4.2 关键日志信息
| 日志片段 |
日志级别 |
含义解读 |
建议处理动作 |
Not support object, class name: %s, object name: %s |
ERROR |
收到未定义类型的对象,hwproxy无法处理 |
检查SR配置中的Class名称是否在object_defs.lua中注册 |
Not support chip model, object name: %s, chip model: %s |
ERROR |
芯片型号不在support_chip_module允许列表中 |
检查芯片型号是否与配置匹配 |
the chip %s access has been closed, please manually open it! |
ERROR |
芯片可访问性被关闭后仍有访问请求 |
检查是否误调用了SetAccessibility关闭芯片 |
the %s queue len of %s is over limit, bus name: %s, queue len : %s |
ERROR |
请求队列溢出超过上限 |
减少并发请求或检查是否有请求堆积 |
chip: %s run failed error: %s |
ERROR |
扫描任务中芯片访问失败 |
检查硬件连接状态 |
Bus not exist, start scan failed |
ERROR |
扫描时总线对象不存在 |
检查总线对象是否已正确注册 |
position: %s chip: %s get bus object failed pre_device: %s |
ERROR |
工作服务获取总线对象失败 |
检查拓扑关系配置中Bus引用是否正确 |
topology file open failed / snapshot file open failed |
ERROR |
一键日志收集时文件创建失败 |
检查磁盘空间和文件权限 |
chip: %s was deleted in topology, pre_device is %s |
INFO |
芯片从拓扑中移除 |
正常操作,无需处理 |
Start to clear interface(bmc.kepler.Scanner) shm data. |
NOTICE |
服务启动时清理Scanner共享内存 |
正常启动流程 |
%s work service heart beat lost, restart work service |
WARN |
工作服务心跳连续丢失,触发重启 |
检查硬件是否阻塞或工作服务内存是否越限 |
set the hwproxy health status to need restart now, bus_name: %s |
ERROR |
1小时内工作服务重启超过2次上限,进程将被systemd重启 |
检查工作服务持续异常的根因 |
main service no recevice from work service, bus_name: %s, position: %s |
NOTICE |
主服务未收到工作服务的拓扑上报 |
可能是工作服务启动慢或通信异常 |
the chip %s access has been closed after reboot |
ERROR |
重启后芯片访问被关闭 |
重启流程中芯片被停止,需手动开启或等待自动恢复 |
5. 问题定界指南
5.1 典型问题定界
| 现象描述 |
是否为本组件问题 |
判断依据 |
关键证据收集方法 |
| 组件启动时读写硬件失败 |
否 |
hwproxy接收对象后需等待整个SR分发完成获取拓扑链路后才能访问,期间存在对象已上树但访问失败的间隔 |
查看hwproxy.log中是否有on_add_object_complete日志,确认拓扑是否已完成分发 |
| Scanner值不更新 |
是 |
可能是防抖算法将值过滤、扫描周期配置异常、或硬件通信失败 |
1. 查看hwproxy.log中扫描失败日志 2. 使用mdbctl追踪防抖详情(TraceDebounce) 3. 检查snapshot.csv中Scanner状态 |
| Accessor读写返回错误 |
是 |
可能是芯片不可访问、拓扑链路未建立、或硬件通信故障 |
1. 查看hwproxy.log中ChipNotExistError/IOError 2. 检查topology.txt中芯片是否存在 3. 使用busctl查询Chip.Accessibility |
| D-Bus上报服务不存在或接口不存在 |
否 |
业务组件未在service.json中声明对Scanner/Accessor的弱依赖 |
检查业务组件service.json是否添加了hwproxy依赖 |
| 引用/同步的属性与预期不符 |
待定 |
需先确认hwproxy资源树中的值是否正确 |
1. busctl直接查询hwproxy资源树上Scanner/Accessor的值 2. 检查启动日志中同步/引用是否有错误打印 |
| 工作服务频繁重启 |
是 |
可能是工作服务心跳丢失或内部异常 |
1. 查看hwproxy.log中monitor相关日志 2. 检查工作服务是否有内存越限(512M限制) 3. 确认是否超过1小时内最大重启次数(2次) |
| 同一总线上芯片值读取异常 |
待定 |
可能是同地址不同类型芯片被合并导致 |
查看hwproxy.log中芯片合并(Chip alias)相关警告 |
5.2 错误码速查表
| 错误码 |
含义 |
可能原因 |
排查建议 |
| kepler.hwproxy.Unknown |
未知错误 |
内部未预期的异常 |
查看hwproxy.log中详细错误堆栈 |
| kepler.hwproxy.RequestTimeout |
请求超时 |
硬件响应超时、总线被占用、驱动挂死 |
1. 检查总线状态 2. 查看驱动日志 3. 确认是否需要增大超时时间 |
| kepler.hwproxy.IOError |
I/O错误 |
硬件通信失败(NACK、总线错误等) |
1. 检查硬件物理连接 2. 确认芯片地址配置正确 3. 查看总线是否被其他操作占用 |
| kepler.hwproxy.ChipNotExistError |
芯片不存在 |
拓扑链路中找不到目标芯片 |
1. 检查SR配置中Chip引用路径 2. 查看topology.txt确认芯片是否存在 3. 确认对象分发是否完成 |
| ChipRequestLimitExceeded |
请求队列溢出 |
同一芯片并发请求超过队列上限 |
1. 减少并发请求 2. 可通过环境变量CHIP_REQUEST_QUEUE_MAX_LEN调整上限(100~1000) |
5.3 调试方法
开启调试日志
- 通过D-Bus调试接口动态调整日志级别:
# 设置日志级别为DEBUG(0=DEBUG, 1=INFO, 2=NOTICE, 3=WARNING, 4=ERROR)
~ # busctl --user call bmc.kepler.hwproxy /bmc/kepler/Debug bmc.kepler.Debug SetLogLevel u 0
- 开启芯片追踪(TraceChip):
# 追踪指定芯片的所有访问操作(需要DiagnoseMgmt权限)
~ # busctl --user call bmc.kepler.hwproxy /bmc/kepler/Release/Chip/Smc/Smc_CpuBrdSMC_010101 bmc.kepler.Release.TraceChip TraceChip
- 开启防抖追踪(TraceDebounce):
# 开始追踪Scanner防抖详情
~ # busctl --user call bmc.kepler.hwproxy /bmc/kepler/Scanner/Scanner_PSU_1 bmc.kepler.Release.Scanner TraceDebounce s "start"
# 停止追踪
~ # busctl --user call bmc.kepler.hwproxy /bmc/kepler/Scanner/Scanner_PSU_1 bmc.kepler.Release.Scanner TraceDebounce s "stop"
- 一键日志收集:
~ # busctl --user call bmc.kepler.hwproxy /bmc/kepler/Debug bmc.kepler.Debug Dump
- mdbctl调试终端(非Release版本):
~ # mdbctl -s bmc.kepler.hwproxy
环境变量
| 环境变量 |
默认值 |
说明 |
| CHIP_REQUEST_QUEUE_MAX_LEN |
500 |
芯片请求队列最大长度(有效范围100~1000) |
| SCANNER_PERIOD_DELAY_TIME |
30000 |
系统启动期间(ms),对100ms以上的Scanner周期进行扩大处理 |
| HEART_BEAT_WAIT_TIME |
6000 |
工作服务心跳超时检测时间(ms) |
| HEART_BEAT_INTERVAL |
3000 |
工作服务心跳检测间隔(ms,即30s检测一轮) |
可观测性指标
hwproxy通过OpenTelemetry暴露以下指标:
| 指标名 |
类型 |
说明 |
| bmc.hw.chip.io |
Counter |
芯片I/O操作计数(读写成功/失败) |
| bmc.hw.chip.scanner |
Counter |
Scanner扫描计数(成功/失败) |
| bmc.hw.chip.accessor |
Counter |
Accessor访问计数(成功/失败) |
复现问题方法
- 前置条件设置:确保hwproxy服务正常运行(
systemctl status hwproxy)
- 操作步骤:
- 使用busctl调用目标接口复现问题
- 开启DEBUG级别日志和芯片追踪
- 收集一键日志(Dump)
- 预期现象:根据日志中ERROR/WARN信息和错误码定位问题
关键机制说明
扫描任务优先级:工作服务内部采用三级优先级调度——High(实时读写请求,如Accessor/BlockIO)优先于Secondary(聚合扫描)优先于Low(周期Scanner扫描)。低优先级扫描每50ms检查是否有高优先级任务插入。
心跳与重启策略:Monitor服务每30s检测一次工作服务心跳,连续3次丢失(I3C总线为10次)则触发重启。1小时内最多重启2次工作服务,超过后设置健康状态为NEED_RESTART_NOW。
请求队列模型:每个芯片维护4种请求队列(read、write、plugin、cpld_upg),相同Offset+Length+Type的读请求会自动合并fetch,减少硬件访问次数。
6. 常见问题解答
Q1:组件启动时读写硬件失败
- 问题描述:业务组件启动后立即访问硬件,返回ChipNotExistError或IOError
- 一句话答案:hwproxy需要等待整个SR分发完成获取拓扑链路后才能访问硬件,启动初期对象已上树但访问链路尚未建立
- 根因说明:hwproxy接收对象后,需在
on_add_object_complete回调中完成拓扑链路构建,在此之前的硬件访问请求会因找不到芯片或总线未就绪而失败
- 解决方案:业务组件在访问硬件时增加重试机制,重试间隔建议1~2秒
- 规避方案:在组件初始化阶段等待hwproxy服务就绪后再开始硬件访问
- 适用版本:所有版本
Q2:Scanner需要写入硬件值如何处理
- 问题描述:Scanner属性只读,需要向Scanner对应的硬件寄存器写入值
- 一句话答案:另定义一个配置相同的Accessor对象,Scanner用于周期读取,Accessor用于写入
- 根因说明:Scanner设计为单向采集,Value属性只读;写入硬件需使用Accessor的引用语法(#/)
- 解决方案:在CSR中定义与Scanner相同Chip/Offset/Size/Mask/Type的Accessor,业务属性使用
#/Accessor_X.Value关联
- 适用版本:所有版本
Q3:报错找不到服务或接口不存在
- 问题描述:业务组件使用Scanner/Accessor属性时报D-Bus服务不存在或接口不存在
- 一句话答案:未在组件service.json中声明对hwproxy的依赖
- 根因说明:业务组件未声明依赖导致hwproxy服务未部署,或未require生成的client代码
- 解决方案:1. 在组件service.json中添加hwproxy依赖 2. 在app入口文件require生成的client文件
- 适用版本:所有版本
Q4:引用/同步的属性值与预期不符
- 问题描述:通过Scanner同步或Accessor引用的属性值与硬件实际值不一致
- 一句话答案:先确认hwproxy资源树上的原始值是否正确,再检查同步/引用配置
- 根因说明:可能原因包括:防抖算法过滤了正常值、Scanner扫描周期过长、CSR配置中Chip引用路径错误、同步/引用语法使用错误
- 解决方案:1. 使用busctl直接查询hwproxy资源树上Scanner/Accessor的Value 2. 使用TraceDebounce追踪防抖过程 3. 检查CSR配置中
<=/和#/语法是否正确使用
- 规避方案:对于变化频繁的值,选择合适的防抖算法和参数
- 适用版本:所有版本
Q5:Accessor每次读取都触发硬件访问,性能问题
- 问题描述:业务代码中多次访问同一Accessor.Value属性,每次都触发RPC请求读取硬件
- 一句话答案:Accessor每次属性访问都会实时读取硬件,需使用local变量缓存值
- 根因说明:Accessor.Value的每次读取都会触发property_read信号,hwproxy收到后实时访问硬件并返回;连续多次访问导致多次硬件I/O
- 解决方案:在代码中使用
local value = obj.Property接收并保存硬件值,后续使用local变量而非重复访问属性
- 适用版本:所有版本
Q6:BMC启动初期Scanner扫描周期偏长
- 问题描述:系统启动后前30秒,Scanner的扫描周期比配置值长
- 一句话答案:这是启动优化机制,系统启动30秒内对100ms以上的Scanner周期自动扩大,避免启动期间硬件访问过载
- 根因说明:由环境变量
SCANNER_PERIOD_DELAY_TIME控制(默认30000ms),启动期间大量Scanner同时扫描会抢占总线资源,影响关键启动流程
- 解决方案:正常机制,无需处理。如需调整可通过
SCANNER_PERIOD_DELAY_TIME环境变量修改延迟时间
- 适用版本:所有版本
Q7:工作服务心跳丢失导致hwproxy整体重启
- 问题描述:hwproxy健康状态变为NEED_RESTART_NOW,进程被systemd重启
- 一句话答案:1小时内工作服务重启超过2次上限,Monitor将健康状态设为NEED_RESTART_NOW触发进程重启
- 根因说明:工作服务心跳连续3次丢失触发重启(I3C总线为10次);若1小时内累计重启超过2次,判定为不可恢复故障
- 解决方案:1. 检查hwproxy.log中心跳丢失原因(硬件访问阻塞、内存越限等) 2. I3C升级NPU场景下插件占用时间较长,已将心跳检查次数放宽至10次
- 规避方案:避免在工作服务线程中执行长时间阻塞操作
- 适用版本:所有版本
附录
附录A 参考资料
- openUBMC社区贡献指南
- hwproxy README.md — 组件详细设计与接口说明
- hwproxy CHANGELOG.md — 版本变更记录
附录B 修订记录
| 版本 |
日期 |
修订人 |
修订内容 |
| v1.0 |
2026-08-24 |
openUBMC |
初始版本创建 |