*openUBMC 支持BlueField DPU卡功能重构详细设计说明书*

<table>
    <tr>
        <td>所属SIG组:</td>
        <td>hardware</td>
    </tr>
    <tr>
        <td>落入版本:</td>
        <td>25.12</td>
    </tr>
    <tr>
        <td>设计人员:</td>
        <td>hetong</td>
    </tr>
    <tr>
        <td>日期:</td>
        <td>2026/1/12</td>
    </tr>
</table>

**Copyright © 2026 openUBMC Community**

您对&quot;本文档&quot;的复制，使用，修改及分发受木兰宽松许可证, 第2版协议(以下简称&quot;MulanPSL2&quot;)的约束。
为了方便用户理解，您可以通过访问<https://license.coscl.org.cn/MulanPSL2>了解MulanPSL2的概要 (但不是替代)。
MulanPSL2的完整协议内容您可以访问如下网址获取：<https://license.coscl.org.cn/MulanPSL2>。

**改版记录**

<table>
    <tr>
        <th>日期</th>
        <th>修订版本</th>
        <th>修订描述</th>
        <th>作者</th>
        <th>审核</th>
    </tr>
    <tr>
        <td>2026/1/12</td>
        <td>1.0</td>
        <td>支持BlueField DPU卡功能重构</td>
        <td>hetong</td>
        <td>已审核</td>
    </tr>
</table>

**List of abbreviations**  **缩略语清单** ：

<table>
    <tr>
        <th>Abbreviations 缩略语</th>
        <th>Full spelling 英文全名</th>
        <th>Chinese explanation 中文解释</th>
    </tr>
    <tr>
        <td>CPLD</td>
        <td>Complex Programming Logic Device</td>
        <td>复杂可编程逻辑器件</td>
    </tr>
    <tr>
        <td>BMC</td>
        <td>Baseboard Management Controller</td>
        <td>基板管理控制器</td>
    </tr>
    <tr>
        <td>AC</td>
        <td>Alternating Current</td>
        <td>交流电，系统断电重启</td>
    </tr>
    <tr>
        <td>DC</td>
        <td>Direct Current</td>
        <td>直流电，系统下电</td>
    </tr>
    <tr>
        <td>CSR</td>
        <td>Component Self-description Resource</td>
        <td>组件自描述资源</td>
    </tr>
    <tr>
        <td>BCU</td>
        <td>Base Control Unit</td>
        <td>基础控制单元板</td>
    </tr>
</table>

[TOC]

# 1.功能分析
## 1.1 功能背景

当前是把BlueField DPU卡当做普通网卡来适配，具备网卡对象和PCIe卡对象，没有DPU卡对象。如果要新增OS复位检测功能，无法复用当前DPU卡类已有的接口和方法，只能在network_adapter组件另外实现一套，可复用性差。

## 1.2 功能描述

本功能主要实现Bluefield DPU卡功能重构，增加DPU卡对象：

### 1.2.1 生效条件与兼容性问题

1. **CSR配置扩展**：
   - 在Bluefield卡对应的csr中新增`DPUCard`对象
    ```json
    "DPUCard_1": {
        "Model": "BF2",
        "BoardID": 65535,
        "BoardName": "BF2",
        "Name": "BF2",
        "Description": "BF2",
        "FunctionClass": 11,
        "Architecture": "BlueField_DPU",
        "TotalCores": 16,
        "PcbVersion": "<=/PCIeCard_1.PcbVersion",
        "SlotID": "<=/PCIeDevice_1.SlotID",
        "NodeID": "<=/PCIeDevice_1.SlotID |> string.format('BF2_%s',$1)",
        "Manufacturer": "NVIDIA",
        "HeartBeatLoss": 0,
        "RefFrudata": "#/FruData_BF2",
        "LinkWidth": "<=/NetworkAdapter_1.LinkWidth",
        "VendorID": "#/NetworkAdapter_1.VendorID",
        "DeviceID": "#/NetworkAdapter_1.DeviceID",
        "SubVendorID": "#/NetworkAdapter_1.SubsystemVendorID",
        "SubDeviceID": "#/NetworkAdapter_1.SubsystemDeviceID",
        "Position": "<=/PCIeDevice_1.Position",
        "LaneOwner": "<=/PCIeDevice_1.SocketID",
        "DeviceName": "<=/PCIeDevice_1.DeviceName",
        "PartNumber": "<=/FruData_BF2.BoardPartNumber",
        "SerialNumber": "<=/FruData_BF2.BoardSerialNumber",
        "RefComponent": "#/Component_DPUCard",
        "ManagerType": "BMC",
        "SRVersion": "${DataVersion}"
    }
    ```
2. **兼容性问题处理**：
    新增的DPU卡对象，和原有的DPU卡流程有较大差异，主要体现在：
    (1)ipmi命令
    (2)rpc方法
    (3)其他流程（smbus）
    采用`Model`和已有业务流程作区分
    ```
    local hardware_config_model<const> = {
        ['HyperCard4.0'] = 'hypercard_object',
        ['BF2'] = 'bluefield_object',
        ['BF3'] = 'bluefield_object'
    }
    function dpu_service:on_add_object(class_name, object, position)
        local switch = {
            ['DPUCard'] = function ()
                local ok
                local dpu_object
                local model = hardware_config_model[object.Model]
                if not model then
                    dpu_object = require 'dpu_service.dpu_object'
                    self:on_add_default_dpu_object(dpu_object, object, position)
                    return
                end
                ok, dpu_object = pcall(require, string.format('dpu_service.%s', model))
                if not ok or not dpu_object then
                    log:error('No specific dpu_object file for this DPUCard(Model: %s)', object.Model)
                    return
                end
                local dpu_obj = dpu_object.new(object, position)
                dpu_obj:start()
                self.dpu_objects_with_model[position] = dpu_obj
            end,
            ['SRUpgrade'] = function ()
                self.sr_upgrade_list[position] = object
                if self.dpu_objects[position] then
                    self.dpu_objects[position]:set_dpu_type(self.sr_upgrade_list[position].Type)
                end
            end
        }
        if switch[class_name] then
            switch[class_name]()
            log:info('[DPU] add object, class: %s, position: %s',class_name, position)
        end
    end
    ```
    ```mermaid
    flowchart TD
        A[对象自分发] --> B[general_hardware对象加载回调]
        B --> C{Model是否特殊列表?}
        C -->|是| D[使用该Model创建]
        C -->|否| E[使用dpu_object创建]
        D --> F{dpu_objects_with_model列表}
        E --> G{dpu_objects列表}
        H[ipmi回调注册] --> J[匹配DPU卡对象]
        I[rpc回调注册] --> K[匹配DPU卡对象]
        J --> G
        K --> G
        K --> F
    ```
    如果匹配不到对象，或者对象不存在相关方法，直接抛错并记录相关日志

## 1.3 功能场景

### 1.3.1 场景触发条件及对象
- **使用角色**：系统管理员、运维人员、技术支持工程师
- **使用工具**：IPMI、Redfish工具
- **使用技能**：具备基本的BMC管理经验

### 1.3.2 使用时间及频度
较低

### 1.3.3 主要场景及子场景
查看/设置Blufied卡相关属性或方法

## 1.4 功能列表
| 功能编号 | 功能标题 | 功能描述 |
| ------- | ------- | -------- |
| 1 | Blufied卡管理 | 具备DPU卡管理功能 |

# 2.功能设计
## 2.1 总体方案分析

### 2.1.1 方案详细设计
#### 2.1.1.1 方案概述
csr添加DPU卡对象、代码内部根据Model进入不同处理流程

#### 2.1.1.2 开发视图

```mermaid
graph TB
    subgraph "外部接口层"
        A[Web API] --> F[rackmount]
        B[CLI] --> F
        C[IPMI] --> G[ipmi_core]
        D[Redfish] --> F
    end

    subgraph "general_hardware组件"
        subgraph "dpu_service"
            I[on_add_object]
            I --> J{Model是否特殊列表?}
            J -->|是| K[使用该Model创建]
            J -->|否| L[使用dpu_object创建]
            K --> |add to|M[dpu_objects_with_model列表]
            L --> |add to|N[dpu_objects列表]
            Q[get_dpu_obj_by_path]
            R[get_dpu_obj_by_device_no]
            Q --> |search|M
            Q --> |search|N
            R --> |search|N
            T[on_delete_object]
            T --> Q
        end

        subgraph "ipmi注册"
            O[register_ipmi]
            O --> R
        end

        subgraph "redfish注册"
            P[register_rpc]
            P --> Q
        end
    end

    subgraph "自发现"
        S[hwdiscovery]
        S --> |加载|I
        S --> |卸载|T
    end

    F --> P
    G --> O
    
```

#### 2.1.1.3 运行视图


### 2.1.2 内部依赖分析

| 依赖组件 | 依赖接口/功能 | 依赖说明 |
| ------- | ----------- | ------- |
| vpd | DPU卡对象配置 | 配置了对象才能分发 |

### 2.1.3 外部依赖分析

不涉及

### 2.1.4 北向接口分析

| 特性 | SNMP | CLI | WEB | KVM_VMM | IPMI(RMCP/RMCP+) | HMM | Redfish |
| ---- | ---- | ---- | --- | ------ | ---------------- | --- | ------- |
| 查询/设置接口 | NA | NA | 有 | NA | NA | NA | 有 |

说明：本功能不涉及新增北向接口，仅增加了部分可查询/设置内容。
涉及接口目前排查如下:
```
/redfish/v1/Chassis/:chassisid/PCIeDevices/:id/Actions/PCIeDevices.SetNMI
/redfish/v1/Chassis/:chassisid/PCIeDevices/:id/Actions/Oem/{{OemIdentifier}}/PCIeDevices.Reset
/redfish/v1/Chassis/:chassisid/PCIeDevices/:id/Actions/Oem/{{OemIdentifier}}/PCIeDevices.SetPowerState
/redfish/v1/Chassis/:chassisid/PCIeDevices/:id/Actions/Oem/{{OemIdentifier}}/PCIeDevices.ImportHttpsCert
/redfish/v1/Chassis/:chassisid/PCIeDevices/:id/SetNMIActionInfo
/redfish/v1/Chassis/:chassisid/PCIeDevices/:id/ResetActionInfo
/redfish/v1/Chassis/:chassisid/PCIeDevices/:id/SetPowerStateActionInfo
/redfish/v1/Chassis/:chassisid/PCIeDevices/:id/ImportHttpsCertActionInfo
/redfish/v1/Chassis/:chassisid/PCIeDevices
/redfish/v1/Chassis/:chassisid/PCIeDevices/:id/PCIeFunctions
/redfish/v1/Chassis/:chassisid/PCIeDevices/:id/PCIeFunctions/:funcid
/UI/Rest/System/PCIeDevices/SetSDICardNMI
/UI/Rest/System/PCIeDevices/SetSDICardLogLevel
/UI/Rest/System/PCIeDevices/ResetSDICard
/UI/Rest/System/PCIeDevices/SetSDICardPowerState
/UI/Rest/System/PCIeDevices/ImportSDICardPublicKey
/UI/Rest/System/Boards/PCIeCard
```
调用方法时，如果DPU卡不支持，例如访问/redfish/v1/Chassis/:chassisid/PCIeDevices/:id/Actions/PCIeDevices.SetNMI，直接抛错、记录相关日志，并返回400：
```json
{
    "error": {
        "code": "Base.1.0.GeneralError",
        "message": "A general error has occurred. See ExtendedInfo for more information",
        "@Message.ExtendedInfo": [
            {
                "@odata.type": "#Message.v1_0_0.Message",
                "MessageId": "iBMC.1.0.SetNMIFailed",
                "RelatedProperties": [],
                "Message": "the PCIe device may not supports NMI",
                "MessageArgs": [],
                "Severity": "Warning",
                "Resolution": "Make sure that the PCIe device supports NMI"
            }
        ]
    }
}
```

### 2.1.5 兼容性分析

| 影响项 | 影响说明 | 兼容性措施 |
| ----- | ------- | --------- |
| CSR配置 | 新增DPU卡对象 | vpd和general_hardware同版本 |
| 新老版本bmc互升 | 不涉及 | 不涉及 |

### 2.1.6 定制化接口分析
需要排查定制化redfish接口以及csr

### 2.1.7 导入导出分析
不涉及导入导出配置变更

### 2.1.8 传感器分析
不涉及新增传感器

### 2.1.9 精准告警事件分析
不涉及

### 2.1.10 系统锁定分析
不涉及

### 2.1.11 用例场景分析
| 用例编号 | 用例名称 | 用例描述 | 前置条件 | 执行步骤 | 预期结果 |
| ------- | ------- | ------- | ------- | ------- | ------- |
| 1 | 对象加载 | BF卡正常加载DPU对象 | 环境存在BF卡 | web、ssh登录查看 | 正常加载、属性正常 |
| 2 | 北向接口访问 | 北向接口能够正常访问该DPU卡 | 环境存在BF卡 | 北向接口访问 | 正常访问 |



## 2.2 非功能质量属性设计
### 2.2.1 扩展性分析

本设计具有良好的扩展性：

1. **新增DPU卡扩展**：
   - 支持根据Model管理不同的DPU卡，可以有不同的业务逻辑

2. **方法扩展**：
   - 支持不同的DPU卡根据自身特性裁减方法

### 2.2.2 重用性分析
不涉及

### 2.2.3 可测试性分析
北向接口方便测试

#### 2.2.3.2 测试环境要求
具备BF卡

### 2.2.4 资料分析
不涉及

### 2.2.5 资源使用分析
目前只是增加DPU对象，内部无实际轮询业务流程，占用资源很少

### 2.2.6 可靠性分析(含SFMEA)

| 编号 | 正交步骤 | 故障影响 | 容错措施 | 故障注入方法 | 
| --- | --- | --- | --- | --- | 
| 1 | DPU卡卸载 | 残留业务逻辑 | 删除对象回调里遍历清除 | 拔出卡 |
| 2 | DPU卡不具备相关特性 | 北向接口调用出错 | 主动抛错并打印相关日志 | redfish调用不支持的方法 |

### 2.2.7 安全性分析

| 安全合规项 | 是否涉及 | 现有的防护措施 |
| --- | --- | --- |
| 访问控制（通道、文件权限、用户权限、查询权限、配置权限、接口权限） | 否 | 不涉及 |
| 敏感数据 | 否 | 不涉及敏感数据处理 |
| 日志（操作日志、维护日志、安全日志、运行日志） | 是 | 1. 记录所有生效操作日志<br>2. 记录生效条件判断日志<br>3. 记录异常和失败日志 |
| 文档 | 否 | 不涉及文档安全 |
| 加密及算法 | 否 | 不涉及加密算法 |
| 新增关键资源（密钥、证书、关键配置）备份、恢复 | 否 | 不涉及密钥证书管理 |
| 新增对外接口入参校验 | 否 | 不涉及新增对外接口 |
| 新增开源及三方软件引入 | 否 | 不涉及新的开源软件引入 |

# 3.功能实现

## 3.1 功能实现设计

csr添加DPU卡对象、代码内部根据Model进入不同处理流程

## 3.2 功能详细设计

```mermaid
graph TB
    subgraph "外部接口层"
        A[Web API] --> F[rackmount]
        B[CLI] --> F
        C[IPMI] --> G[ipmi_core]
        D[Redfish] --> F
    end

    subgraph "general_hardware组件"
        subgraph "dpu_service"
            I[on_add_object]
            I --> J{Model是否特殊列表?}
            J -->|是| K[使用该Model创建]
            J -->|否| L[使用dpu_object创建]
            K --> |add to|M[dpu_objects_with_model列表]
            L --> |add to|N[dpu_objects列表]
            Q[get_dpu_obj_by_path]
            R[get_dpu_obj_by_device_no]
            Q --> |search|M
            Q --> |search|N
            R --> |search|N
            T[on_delete_object]
            T --> Q
        end

        subgraph "ipmi注册"
            O[register_ipmi]
            O --> R
        end

        subgraph "redfish注册"
            P[register_rpc]
            P --> Q
        end
    end

    subgraph "自发现"
        S[hwdiscovery]
        S --> |加载|I
        S --> |卸载|T
    end

    F --> P
    G --> O
    
```

## 3.3 开发者测试

### 3.3.1 单元测试

#### 3.3.1.1 测试目录结构

#### 3.3.1.2 单元测试用例

| 组件名 | 用例类型 | 测试用例描述 | 预期结果 | 
| --- | --- | --- | --- | 
| general_hardware | UT | 对象加/卸载 | 正常加/卸载，处理残余任务 | 
| general_hardware | UT | rpc方法调用 | 定义了方法正常调用、未定义抛错 |

### 3.3.2 集成测试
不涉及

