hwproxy:基于 Skynet 的 BMC 硬件代理服务

Through the SR data and hwdiscovery to obtain the object configurations and hardware topology, directly interact with user-space drivers, to access the hardware resources.

Branch2Tags0
FilesLast commitLast update
1 month ago
2 months ago
2 months ago
10 days ago
2 months ago
10 days ago
2 months ago
11 days ago
10 days ago
1 month ago
19 days ago
2 months ago
2 months ago
10 days ago
2 months ago
2 months ago
2 months ago
2 months ago
2 months ago
2 months ago

Hwproxy 硬件代理

硬件代理归属基础框架子系统,属于南向硬件管理的一部分;通过SR数据与硬件自发现获取自身对象配置与硬件拓扑关系,直接与用户态驱动进行交互,完成对硬件的访问;

1. 目录结构

hwproxy/
├── src/                        # 源代码
│   ├── service/                # Skynet服务入口
│   │   ├── main.lua            # 主服务
│   │   ├── work.lua            # 工作服务
│   │   └── monitor.lua         # 监控服务
│   └── lualib/                 # 核心库
│       ├── access/             # Scanner与Accessor实现
│       ├── hw_utils/           # 硬件辅助工具
│       ├── hwproxy_objects/    # 对象管理
│       ├── defs/               # 常量定义
│       ├── chip.lua            # Chip抽象
│       ├── dispatch.lua        # 分发管理
│       ├── scan.lua            # 扫描管理
│       ├── aggregate.lua       # 聚合扫描
│       └── ...                 # 其他模块
├── gen/                        # 自动生成代码
│   ├── hwproxy/                # 服务接口与类型定义
│   └── class/                  # 类模型定义
├── mds/                        # 模型定义文件
│   ├── schema.json             # CSR Schema
│   ├── service.json            # 服务元数据
│   ├── errors.json             # 错误码定义
│   ├── model.json              # 接口属性映射
│   └── types.json              # 自定义类型
├── manufacture/                # 制造自检应用
├── dist/                       # 部署配置
│   ├── config.cfg              # Skynet配置
│   └── user_conf/              # 系统启动脚本与systemd服务
├── test/                       # 测试
│   ├── unit/                   # 单元测试
│   ├── integration/            # 集成测试
│   └── fuzz/                   # 模糊测试
├── proto/                      # 协议数据
├── CMakeLists.txt              # CMake构建配置
├── Makefile                    # 测试与代码生成目标
├── conanfile.py                # Conan包配置
└── conanbase.py                # Conan基础配置

2. 功能简介

2.1 硬件代理业务流程

sequenceDiagram
    actor 用户
    participant bmc studio
    participant vpd
    participant 天池组件 Eeprom/BMC Flash
    participant hwdiscovery
    participant 业务组件
    participant sd_bus资源树
    participant hwproxy主服务
    participant hwproxy work工作服务
    participant 用户态驱动

    用户->>bmc studio: 硬件拓扑关系,对象定义
    activate 用户
    activate bmc studio
    deactivate 用户

    bmc studio->>+ vpd: 生成SR文件/升级包
    deactivate bmc studio
    activate vpd

    vpd->>+天池组件 Eeprom/BMC Flash: 保存SR数据
    activate 天池组件 Eeprom/BMC Flash
    deactivate vpd
    deactivate 天池组件 Eeprom/BMC Flash

    hwdiscovery->>+ 天池组件 Eeprom/BMC Flash:硬件自发现对象数据,拓扑数据
    activate hwdiscovery
    天池组件 Eeprom/BMC Flash-->>hwdiscovery:
    deactivate 天池组件 Eeprom/BMC Flash

    activate sd_bus资源树
    hwdiscovery->>+sd_bus资源树:硬件自发现对象数据,拓扑数据
    deactivate hwdiscovery
    deactivate sd_bus资源树


    hwproxy主服务->>+sd_bus资源树:AddObject<br>获取对象数据
    activate hwproxy主服务
    sd_bus资源树-->>-hwproxy主服务:

    hwproxy主服务->>+hwproxy work工作服务:根据bus创建工作服务
    activate hwproxy work工作服务
    deactivate hwproxy work工作服务

    hwproxy主服务->>+sd_bus资源树:AddObjectComplete<br>获取拓扑关系
    sd_bus资源树-->>-hwproxy主服务:

    hwproxy主服务->>+hwproxy work工作服务:分发对象给工作服务<br>根据bus创建拓扑
    activate hwproxy work工作服务
    hwproxy work工作服务->>-hwproxy work工作服务: 建立拓扑关系
    hwproxy work工作服务->>-hwproxy主服务:对象上树
    hwproxy主服务->>-sd_bus资源树:对象上树
    activate sd_bus资源树
    deactivate sd_bus资源树


    activate hwproxy work工作服务
    hwproxy work工作服务->>hwproxy work工作服务:内部低优先级任务<br>开始Scanner开始进行扫描
    hwproxy work工作服务->>+用户态驱动:获取硬件信息
    用户态驱动-->>-hwproxy work工作服务:
    hwproxy work工作服务->>+hwproxy主服务: Scanner扫描值更新
    deactivate hwproxy work工作服务
    deactivate hwproxy主服务
    hwproxy主服务->>+sd_bus资源树:
    deactivate sd_bus资源树


    业务组件->>+sd_bus资源树: 硬件读写请求
    activate 业务组件
    deactivate sd_bus资源树
    sd_bus资源树->>+hwproxy主服务:
    hwproxy主服务->>+hwproxy work工作服务:高优先级实时<br>读写请求处理
    hwproxy work工作服务->>+用户态驱动: 硬件读写请求
    用户态驱动-->>-hwproxy work工作服务:
    hwproxy work工作服务-->>-hwproxy主服务:
    hwproxy主服务-->>-业务组件:
    deactivate 业务组件
  • 通过devkit开发工具定义硬件拓扑关系以及对象数据,保存在天池组件Eeprom或通过打包至BMC Flash空间;
  • BMC启动时硬件自发现读取SR数据并解析,将对象数据与拓扑关系更新到资源树;
  • 硬件代理获取对象数据与拓扑关系,创建工作服务;
  • 硬件代理内部启动低优先级Scanner扫描任务,从硬件扫描到值后更新到资源树;
  • 其他组件通过资源树接口创建高优先级硬件读写请求,硬件代理发送给对应硬件后通过资源树返回结果;

2.2 硬件代理对象类图

classDiagram
    class Dispatch {
        +scans: table<Scan>
        +run()
    }

    class Scan {
        +bus: object<Bus>
        +chips: table<Chip>
    }

    class Chip {
        +l_chip: object<Chip>
        +r_chips: table<Chip>
        +accessors: object<Accessor>
        +position: int
        +driver: object<Driver>
        +protocol: object<Protocol>
        +mux: object<Mux>
    }

    class Bus {
        +name: string
        +id: int
        +write()
        +read()
    }

    class Stream
    <<interface>> Stream
    Stream : +read()
    Stream : +write()

    class LocalBus {
        +read()
        +write()
    }

    class I2c {
        +read()
        +write()
    }

    class Accessor {
        +name: string
        +offset: int
        +size: int
        +mask: int
        +type: int
        +resources: object<Resource>
    }

    class Resource {
        +uri: string
        +property:string
        +period: int
        +priority: int
    }

    class Debounce
    <<interface>> Debounce
    Debounce : +calcu()

    class MidAvg {
        +calcu()
    }

    class Median {
        +calcu()
    }

    class Cont {
        +calcu()
    }

    class ContBin {
        +calcu()
    }

    class None {
        +calcu()
    }

    Dispatch "n" o-- "1" Scan
    Scan "n" o-- "1" Chip

    Stream <|.. LocalBus : Realization
    Stream <|.. I2c : Realization

    Bus "1" *-- "1" Stream
    Scanner "1" o-- "1" Bus

    Resource "n" --o "1" Accessor
    Chip "1" o-- "n" Accessor

    Debounce <|.. MidAvg : Realization
    Debounce <|.. Median : Realization
    Debounce <|.. Cont : Realization
    Debounce <|.. ContBin : Realization
    Debounce <|.. None : Realization

    Chip "1" o-- "1" Debounce

    class Mux
    <<interface>> Mux
    Mux : +open_channel()
    Mux : +close_channel()

    class Pca9545 {
        +open_channel()
        +close_channel()
    }

    class Pca9544 {
        +open_channel()
        +close_channel()
    }

    class Driver    {
        +host_bus: object<Bus>
        +own_ship: object<Chip>
        +read()
        +write()
    }
    <<interface>> Driver

    class Lm75 {
        +read()
        +write()
    }

    class Eeprom {
        +read()
        +write()
    }

    class Protocol
    <<interface>> Protocol
    Protocol : +wrap()

    class Smc {
        +wrap()
    }

    Mux <|.. Pca9545 : Realization
    Mux <|.. Pca9544 : Realization
    Driver <|.. Lm75 : Realization
    Driver <|.. Eeprom : Realization
    Protocol <|.. Smc : Realization

    Chip "1" o-- "1" Mux
    Chip "1" *-- "1" Driver
    Chip "1" o-- "1" Protocol

3. 关键特性

硬件代理归属基础框架子系统,属于南向硬件管理的一部分;通过SR数据与硬件自发现获取自身对象配置与硬件拓扑关系,直接与用户态驱动进行交互,完成对硬件的访问;

硬件代理提供统一的硬件访问接口,简化开发适配,解决了访问具体硬件因需要通过复杂多样的硬件接口去进行访问而产生的效率低、易出错、适配拓展性差等问题;

4. 对外接口

bmc.kepler.Chip.BlockIO Read method NA uu Offset ay OutData 块读写接口
Length
Write method NA uay Offset
InData
ComboWriteRead method NA uayuu WriteOffset ay OutData
InData
ReadOffset
ReadLength
WriteRead method NA ayu InData ay OutData
ReadLength
BatchWrite method NA a(uay) a(Offset,InData)
PluginRequest method NA ssay PluginName ay OutData
Cmd
Params
bmc.kepler.Chip.BitIO Read method NA uyu Offset ay OutData 位读写接口
Length
Mask
Write method NA uyuau Offset
Length
Mask
InData

4.1 bmc.kepler.Chip.BlockIO 块读写接口

  • Read
  • 签名:a{ss}uu (Offset, Length)
  • 返回值:ay (OutData)

普通的块读接口,同V2dfl_chip_blkread 使用示例: (1) 代码中使用

-- SR中定义与对应Chip的引用关系
"SRUpgrade_1": {
    "UID": "PRODUCT",
    "Type": "PSR",
    "Version": "1.01",
    "StorageChip": "#/Eeprom_1"
}

-- 通过对应对象进行访问
sr_upgrade:chip_read(...)
    -- 存储SR文件的器件
    chip = self.mds_obj.StorageChip
    ...
    -- 调用Read方法进行访问
    chip:Read(...)
    ...

(2) 资源树使用

~ ~ # busctl --user call bmc.kepler.hwproxy /bmc/kepler/Chip/Eeprom/Eeprom_BCU_010101 bmc.kepler.Chip.BlockIO Read a{ss}uu 0 100 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
~ ~ #
  • Write
  • 签名:a{ss}uay (Offset, InData)
  • 返回值:无

普通的块写接口,同V2dfl_chip_blkwrite 使用示例: (1) 代码中使用

-- SR中定义与对应Chip的引用关系
"SRUpgrade_1": {
    "UID": "PRODUCT",
    "Type": "PSR",
    "Version": "1.01",
    "StorageChip": "#/Eeprom_1"
}

-- 通过对象进行访问
sr_upgrade:chip_write(...)
    -- 存储SR文件的器件
    chip = self.mds_obj.StorageChip
    ...
    chip:Write(...)
    ...

(2) 资源树使用

~ ~ # 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
~ ~ #
  • WriteRead
  • 签名:a{ss}ayu (InData, ReadLength)
  • 返回值:ay (OutData)

I2c扩展读,适用于Offset超长或读数据时除了Offset以外还有其他数据的场景,实际为一条块读指令,同V2dfl_chip_blk_write_read

  • ComboWriteRead
  • 签名:a{ss}uayuu (WriteOffset, InData, ReadOffset, ReadLength)
  • 返回值:ay (OutData)

先写后读,V3新增接口,适用于发送写请求后需要立即读取,并且读取的数据有可能被其他的写请求干扰的情况,实现为hwproxy内部把写与读合并为一次原子操作; 使用示例:

-- chip_write_and_read 写入指定长的数据, 并读取指定长的数据
chip_write_read(...)
    -- write data
    ...
    -- read_data
    ...
  • BatchWrite
  • 签名:a{ss}a(uay) ({Offset, InData})
  • 返回值:无

批量写,V3新增接口,适用于升级等数据分为多帧,且数据固定的情况使用,将多帧数据合并为一个数组dbus请求,由hwproxy一次性进行写入,减少dbus通信时间损耗; 使用示例:

...
while offset < length
    -- 截取20个字节
    ...
    -- 最后不到20个字节的情况
    ...
    -- 每发送2048字节(2KB),延时1秒
    ...
    -- 数据组装为数组
    ...
...
pcall(smbus.chip_batch_write, ...)
...
-- chip_batch_write 批量写入数据
smbus.chip_batch_write(...)

4.2 bmc.kepler.Chip.BitIO 位读写接口

位读写操作由对应器件的用户态驱动实现,器件是否支持位操作及位操作如何处理均需要在对应器件的用户态驱动进行实现,I2c总线上的数据均为以byte为单位的块操作;

  • Read
  • 签名:a{ss}uyu (Offset, Length, Mask)
  • 返回值:ay (OutData)

位读 使用示例:

~ # 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
~ #
  • Write
  • 签名:a{ss}uyuay (Offset, Length, Mask, InData)
  • 返回值:无

位写 使用示例:

~ # 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
~ #

5. 配置介绍

5.1 适用场景

  • Scanner:在hwproxy内部中存在扫描任务对所有配置的Scanner进行周期性扫描,并将值更新到资源树,属性只读,适用于V2中循环获取值的场景,例如:
for {
    /* 获取当前硬件状态并复制到属性值 */
    result = dfl_get_extern_value(handle, PRESS_EVENT, &property_value, DF_COPY);   // 在循环中周期性获取值,属性关联硬件
}

在V3中可通过配置Scanner,通过属性同步获取值;

  • Accessor: 适用于不需要循环周期性获取值或需要写入硬件值的场景,属性可读写,当获取值时,hwproxy监听property_read信号,实时读取硬件的值并更新到资源树,当写入值时,hwproxy监听property_before_change信号,实时写入到硬件中;

5.2 CSR(组件资源配置)和使用示例

  • Scanner

以下配置使用CSR格式,支持//注释(非标准JSON语法):

	"Objects": {
	    ...
        // 以Scanner类名开头,且名称此sr内唯一
	    "Scanner_PSU_1": {
                // Scanner挂载的chip
	            "Chip": "#/Smc_2",
                // 偏移,json不支持16进制,需转换成10进制
	            "Offset": 469765888,
                // 读数据长度
	            "Size": 1,
                // 掩码,位读时有效,块读时无效可置0
                // 从硬件读取数据后与掩码进行按位与操作后返回结果
                // 写入时先获取值,再按位修改后写入到硬件
                // 需要器件支持
	            "Mask": 255,
                // 0:位读 1:块读
	            "Type": 0,
                // 扫描周期,单位ms
	            "Period": 100,
                // 防抖对象
	            "Debounce": "None",
                // Scanner读取的值,默认0
	            "Value": 0
	        },
	    "Connector_PSU_1": {
	            "Bom": "14100513",
	            "Slot": 1,
	            "Position": 1,
                // 使用的地方,需要在使用的组件声明属性,使用同步语法关联到Scanner的Value
	            "Presence": "<=/Scanner_PSU_1.Value",
	            "Id": "01",
	            "AuxId": "01",
	            "Buses": [
	                "I2c_2"
	            ],
	            "SystemId": 1,
	            "SilkText": "PSU",
	            "TargetType": 3,
	            "Chip": "#/Eeprom_2"
	        }
	}

使用时可监听信号property_changed通过属性变化触发的方式(推荐),或循环访问(Scanner循环访问时不会触发信号,不会实际访问硬件,值由hwproxy内部扫描更新),属性配置可参考V2进行配置,代码中通过Connector_PSU_1.Presence访问值;

Accessor

    "Objects": {
        ...
        // 以Accessor类名开头,且名称此sr内唯一
        // 配置同Scanner,无Period扫描周期属性
        "Accessor_PwrButtonLock": {
            "Chip": "#/Smc_ExpBoardSMC",
            "Offset": 134222336,
            "Size": 1,
            "Mask": 255,
            "Type": 0,
            "Value": 0
        },
        "FruCtrl_1_0": {
            "PowerGDStatus": "<=/Scanner_PowerGDStatus.Value",
            "ShortPushPowerButton": "#/Accessor_ShortPushPowerButton.Value",
            "LongPushPowerButton": "#/Accessor_LongPushPowerButton.Value",
            "ACCycle": "#/Accessor_ACCycle.Value",
            "NmiInterrupt": "#/Accessor_NmiInterrupt.Value",
            "ForceRestart": "#/Accessor_ForceRestart.Value",
            // 使用的地方,需要在使用的组件声明属性,使用引用语法关联到Accessor的Value
            "PwrButtonLock": "#/Accessor_PwrButtonLock.Value",
            "PwrButtonEvt": "<=/Scanner_PwrButtonEvt.Value",
            "SetPwrButtonEvt": "#/Accessor_PwrButtonEvt.Value",
            "SysResetDetected": "<=/Scanner_SysResetDetected.Value",
            "SetSysResetDetected": "#/Accessor_SysResetDetected.Value"
        }
    }

在代码中使用:

-- 从硬件获取值
local lock = FruCtrl_1_0.PwrButtonLock

-- 写入值到硬件
FruCtrl_1_0.PwrButtonLock = 1

注意:每次使用FruCtrl_1_0.PwrButtonLock都会触发RPC请求并读取硬件,在代码中同一个地方访问时应使用local接收并保存硬件值,否则可能访问多次,访问与代码预期不符的情况;

5.3 常见问题排查

  1. 组件启动时写/读硬件失败?

hwproxy接收到对象后,需要整个sr分发完成后获取拓扑链路后才能进行访问,中间存在资源树上有对象,但访问失败的间隔,组件启动时获取到对象就访问硬件可能出现失败,目前可通过增加重试解决;

  1. Scanner需要写入如何处理?

另外定义一个相同配置的Accessor,Scanner用于循环获取值,Accessor用于写入修改值;

  1. 报错找不到服务或interface不存在?

排查是否引用依赖:在组件service.json中声明Accessor/Scanner弱依赖,自动生成代码后在app入口文件require生成的client文件:

  1. 引用/同步的属性与预期不符?

先在hwproxy资源树查询/设置对应的Accessor/Scanner是否可以操作成功,若hwproxy资源树无问题检查启动日志中同步/引用时是否有错误打印;

6. 贡献指南

欢迎提交Issue和Pull Request。

详细的贡献规范请参阅openUBMC社区贡献指南。

7. 许可协议

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

8. 支持

此开源项目非华为产品,仅提供有限支持。

如果有任何问题、建议、或者发现任何bug,请在 Issues 页面提交一个新的 Issue。详细的描述可以帮助我们快速理解并解决问题。

也欢迎通过邮件方式与我们进行交流。community@public.openubmc.cn

Introduction

Through the SR data and hwdiscovery to obtain the object configurations and hardware topology, directly interact with user-space drivers, to access the hardware resources.

Customize your domain