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提供以下扩展能力:

  1. 新增芯片类型:通过在object_defs.lua中注册新的芯片类定义,即可支持新的硬件器件
  2. 新增总线类型:通过实现Stream接口并注册,即可支持新的总线协议
  3. 新增防抖算法:通过扩展mc.debounce.debounce并在object_defs.lua中添加Debounce类型
  4. 插件机制:通过PluginRequest接口和插件目录注册自定义芯片操作插件
  5. 制造自检扩展:通过添加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方法:

-- driver/new_chip_type.lua
local driver = {}

function driver.read(chip, offset, length)
    -- 实现芯片读取逻辑
    return data
end

function driver.write(chip, offset, data)
    -- 实现芯片写入逻辑
    return true
end

return driver

步骤三:更新MDS模型定义

  1. 在mds/schema.json中添加NewChipType的对象定义和属性
  2. 在mds/model.json中添加NewChipType到D-Bus路径和接口的映射

验证方法

  1. 编译组件并部署到测试环境
  2. 使用busctl验证新芯片对象已正确注册到D-Bus资源树
  3. 使用busctl调用BlockIO.Read/Write验证硬件读写功能正常
  4. 使用TraceChip追踪芯片访问日志确认路径正确

注意事项

  • 芯片类型名称需与SR中的Class名称前缀一致(如NewChipType_XXX)
  • 同一总线上相同地址的不同类型芯片会被自动合并,合并时会产生警告日志
  • 新增芯片类型需确保对应总线类型的Stream已实现
  • support_chip_module不设置时表示支持所有型号;设置后仅支持列出的型号

3.4 插件开发指导

通过PluginRequest接口可实现芯片特定的自定义操作。插件模块放在hwproxy/plugins/目录下:

-- hwproxy/plugins/test_plugin.lua
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 调试方法

开启调试日志

  1. 通过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
  1. 开启芯片追踪(TraceChip):
# 追踪指定芯片的所有访问操作(需要DiagnoseMgmt权限)
~ # busctl --user call bmc.kepler.hwproxy /bmc/kepler/Release/Chip/Smc/Smc_CpuBrdSMC_010101 bmc.kepler.Release.TraceChip TraceChip
  1. 开启防抖追踪(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"
  1. 一键日志收集:
~ # busctl --user call bmc.kepler.hwproxy /bmc/kepler/Debug bmc.kepler.Debug Dump
  1. 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访问计数(成功/失败)

复现问题方法

  1. 前置条件设置:确保hwproxy服务正常运行(systemctl status hwproxy)
  2. 操作步骤:
    • 使用busctl调用目标接口复现问题
    • 开启DEBUG级别日志和芯片追踪
    • 收集一键日志(Dump)
  3. 预期现象:根据日志中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 参考资料

附录B 修订记录

版本 日期 修订人 修订内容
v1.0 2026-08-24 openUBMC 初始版本创建