*openUBMC xx功能详细设计说明书*

<table>
    <tr>
        <td>所属SIG组:</td>
        <td>hardware</td>
    </tr>
    <tr>
        <td>落入版本:</td>
        <td>openUBMC26.00</td>
    </tr>
    <tr>
        <td>设计人员:</td>
        <td>黄鼎</td>
    </tr>
    <tr>
        <td>日期:</td>
        <td>2026.01.06</td>
    </tr>
</table>

**Copyright © 2025 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>xxx</td>
        <td>xxx</td>
        <td>xxx</td>
        <td>xxx</td>
        <td>xxx</td>
    </tr>
    <tr>
        <td>xxx</td>
        <td>xxx</td>
        <td>xxx</td>
        <td>xxx</td>
        <td>xxx</td>
    </tr>
</table>

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

<table>
    <tr>
        <th>Abbreviations 缩略语</th>
        <th>Full spelling 英文全名</th>
        <th>Chinese explanation 中文解释</th>
    </tr>
    <tr>
        <td>xxx</td>
        <td>xxx</td>
        <td>xxx</td>
    </tr>
    <tr>
        <td>xxx</td>
        <td>xxx</td>
        <td>xxx</td>
    </tr>
</table>

[TOC]

# 1.功能分析
## 1.1 功能背景
<!-- 描述该需求的来源或背景，比如：支撑XXX功能、XXX优化等；以及该需求对用户（含组件）带来什么具体价值，如果没有该需求，对用户（含组件）带来什么损失； -->
为了使pcie_device的功能更加内聚，现在将sdk中提供的获取带内上报的PCIe设备拓扑的功能向pcie_device中迁移，由pcie_device保留相关PCIe拓扑信息（迁移sdk中的PCIeAddrInfo数据库）。

系统视角下的pcie设备和机框视角下pcie设备如下图：

```mermaid
graph TD
    System1 --> bri1[PCIe_Bridge【0000:00:00.0】]:::redNode
    System1 --> bri2[PCIe_Bridge【0000:05:00.0】]:::prupleNode

    bri1 --> pcie1[PCIeDevice1【0000:01:00.0】]:::orangeNode
    bri2 --> sw1[PCIe_Switch【0000:06:00.0】]:::greenNode
    sw1 --> pcie2[PCIeDevice2【0000:07:00.0】]:::greyNode
    sw1 --> pcie3[PCIeDevice3【0000:08:00.0】]:::greyNode

    System2 --> bri3[PCIe_Bridge【0000:00:00.0】]:::blueNode

    bri3 --> pcie4[PCIeDevice1【0000:01:00.0】]:::orangeNode

    classDef redNode fill:#ffcccc,stroke:#ff0000
    classDef greenNode fill:#ccff99,stroke:#00ff00
    classDef orangeNode fill:#ffeaa7,stroke:#fdcb6e
    classDef greyNode fill:#e0e0e0,stroke:#404040
    classDef blueNode fill:#99ffff,stroke:#00ffcc
    classDef prupleNode fill:#cc99ff,stroke:#6600cc
```
<center> 图1. 系统视角的PCIe设备 </center>

```mermaid
graph TD
    Chassis --> bri1[PCIeAddrInfo【0000:00:00.0】]:::redNode
    Chassis --> bri2[PCIeAddrInfo【0000:05:00.0】]:::prupleNode
    bri2 --> retimer[Retimer（PCIeSwitch）]:::greenNode

    bri1 --> pcie1[PCIeDevice1【0000:01:00.0】]:::orangeNode

    classDef redNode fill:#ffcccc,stroke:#ff0000
    classDef greenNode fill:#ccff99,stroke:#00ff00
    classDef orangeNode fill:#ffeaa7,stroke:#fdcb6e
    classDef greyNode fill:#e0e0e0,stroke:#404040
    classDef blueNode fill:#99ffff,stroke:#00ffcc
    classDef prupleNode fill:#cc99ff,stroke:#6600cc
```
<center> 图2. 机框视角的PCIe设备 </center>

可以看到，即使两种视角下描述的PCIe设备有重合的部分，但是在两种视角下，它们仍是不同的。例如对于PCIeDevice1，这张PCIe卡由System1和System2共享，但是在机框视角只存在一张卡；对于Retimer挂载的PCIeSwitch，以及挂载在PCIeSwitch上的PCIe卡，在系统视角上可以看到PCIeSwitch和挂载的两张PCIe卡，但是在机框视角上只能看到插槽和Retimer卡。

![PCIe配置空间](../pic/PCIeHeader.png)
<center> 图3. PCIe配置空间 </center>

上图展示了PCIe配置空间，所有的所有的桥设备用Type 1 Header描述，所有的PCIe设备（EndPoint）用Type 0 Header描述，带内上报错误信息有两种手段，第一种是上报桥的BDF（代码里表示为rootBDF）；第二种时上报MMIO（即图3中Base Address范围内的某一地址）。为了通过这个桥的BDF来找到对应的设备BDF，需要提前把带内的拓扑信息保存到数据库中，之前这个功能放在SDK中。

为了将对应的告警关联到机框视角下的设备中，SDK会从数据库中找到对应的BDF，之后向pcie_device上报对应的告警和rootBDF，pcie_device通过rootBDF来索引到资源树上对应的设备，之后设置告警信息。

## 1.2 功能描述
<!-- 描述该需求交付的整体功能，主要实现XXX功能，解决XXX问题，明确方案如何实现 -->
将这个数据库放在SDK中有两个问题：

一、带内上报BDF数据的动作和SDK关系不大，但是和pcie_device关联较强，相关逻辑放到闭源部分不利于伙伴功能开发。

二、pcie_device进行设备管理的时候需要有一些手段将带内拓扑信息和机框拓扑信息进行关联（比如获取带内真实拓扑信息、通过Sec Bus和Sub Bus遍历挂载的PCIe设备进行热插拔等）

对于本需求，需要pcie_device组件新增ipmi接口，获取带内上报的pcie_addr_info拓扑信息。同时提供BDF接口，使得其他组件可以通过BDF获取到对应的pcie设备。

## 1.3 功能场景
<!-- 描述该需求的业务使用场景，内容包括：
1) 场景出发条件及对象：什么角色/工具/接口等在什么具体情况下使用该特性，使用对象技能如何？
2) 使用时间及频度
3) 描述该特性主要有哪些场景、子场景及关键任务操作 -->

带内上报带内拓扑，bmc利用带内拓扑建立拓扑数据库，并向sdk同步

## 1.4 功能列表
<!-- 描述该需求交付的功能列表，内容包括：列出功能详细描述，标题、描述。 -->
| 功能编号 | 功能标题 | 功能描述 |
| ------- | ------- | -------- |
| 1 | 接收ipmi上报的带内拓扑 | 接收bios上报的带内拓扑，建立带内拓扑数据库 |
| 2 | 将ipmi消息转发给sdk | 接收ipmi上报的带内拓扑时直接转发给sdk |

# 2.功能设计
## 2.1 总体方案分析
<!-- 描述该方案的总体设计（注：相关输出方案可同步刷新到各组件仓） -->

bios启动时会发送带内PCIe拓扑，pcie_device组件每收到一条就转发给sdk，之后将消息加入队列稍后处理。

### 2.1.1 方案详细设计
#### 2.1.1.1 方案概述
<!-- 描述该方案的整体实现，内容包括：涉及的关键点，实现策略等 -->

```mermaid
graph TD
    Bios([bios启动]) --> ipmi[/bios上报带内拓扑信息/]
    ipmi --> ipmi_sw{判断优先级}
    ipmi_sw -- pcie_device优先级高 --> pcie[/接收上报的拓扑信息/]
    ipmi_sw -- sdk优先级高 --> sdk
    pcie --> sdk[/转发给sdk/]
    pcie --> pcie2[/加入pcie_device本地数据库/]
```

#### 2.1.1.2 开发视图
<!-- 开发视图面向系统开发及软件管理，描述系统代码结构，构建结构的视图，主要解决系统技术实现和开发的问题，它依托逻辑视图，描述代码、构建结构 -->

```mermaid
classDiagram
    note for pcie_device_app"pcie_device记录pcie_addr_info"

    pcie_device_app *-- database

    class pcie_device_app{
        +database t_system_pcie_topo_info
        +SetSystemPCIeTopoInfo()
    }

    class database{
        +database t_system_pcie_topo_info
        +WriteTopoData(data)
        +ReadTopoData()
        +Save()
    }

```

#### 2.1.1.3 运行视图
<!-- 运行视图面向系统运行，描述系统启动过程、运行期交互的视图，主要解决系统运行期交互，描述各可执行交付件在运行期的交互关系 -->

```mermaid
sequenceDiagram
    participant Bios
    participant Sdk
    participant pcie_device

    Bios->>pcie_device: 上报带内拓扑信息
    pcie_device->>Sdk: 转发带内拓扑信息
    pcie_device-->>pcie_device: 数据存盘
```

### 2.1.2 内部依赖分析
<!-- 是否涉及与其他组件接口依赖，如果涉及需要确认当前是否已完成，是否匹配当前需求开发诉求 -->
不依赖其他组件接口

### 2.1.3 外部依赖分析
<!-- 是否涉及与平台SDK的依赖关系 -->
不依赖特定版本SDK

### 2.1.4 北向接口分析
<!-- 需要分析当前功能是否有以下接口影响，如果有影响，则需要具体的补充影响点。其中注意点如下：
（1）如果有新增IPMI接口，请排查代码中IPMI命令注册的过滤字段，是否完全和IPMI命令的定义一致？
（2）新增一个接口时，需要咨询SIG组是否还有其他的接口受影响 -->
| 特性 | SNMP | CLI | WEB | KVM_VMM | IPMI(RMCP/RMCP+) | HMM | Redfish |
| ---- | ---- | ---- | --- | ------ | ---------------- | --- | ------- |
| 支持XXX功能 | NA | NA | NA | NA | NA | NA | NA |

### 2.1.5 兼容性分析
<!-- 当前的功能对现有在网的功能是否有影响，具体的影响点进行分析之后输出影响分析表格 -->
| pcie_device | sdk | 影响分析 |
| ----------- | --- | ------- |
| 新          | 新   | 无影响  |
| 旧          | 旧   | 无影响  |
| 旧          | 新   | 无影响  |
| 新          | 旧   | 无影响  |

### 2.1.6 定制化接口分析
<!-- 如果支持定制化设置，则需要给出定制化时的默认值（空定制化项条件下的设置值），如果涉及到定制化接口变更或新增，注意定制化接口文档需配套修改。注意定制化默认值变更对白牌包的影响 -->
不存在定制化接口

### 2.1.7 导入导出分析
<!-- 如果支持导入导出的配置，则需要分析导入导出的schema。 -->
不涉及

### 2.1.8 传感器分析
<!-- 如果需要新增传感器，则需要提前登记和评审新增的传感器要素。新增传感器评审需要上SIG-Interface进行评审 -->
不涉及

### 2.1.9 精准告警事件分析
<!-- 如果需要新增事件，则需要提前登记和评审新增的时间要素 -->
不涉及

### 2.1.10 系统锁定分析
<!-- 对外的接口或者命令是否支持系统锁定 -->
不涉及

### 2.1.11 用例场景分析
<!-- 以表格的形式输出该需求涉及的用例场景 -->
| 编号 | 场景描述 |
| --- | -------- |
| Case1 | 整机AC上电场景 |
| Case2 | 重启BMC场景 |

### 2.1.12 装备能力差异分析
<!-- 当前功能是否在装备版本和Release版本中存在能力差异，若有差异需要进行说明 -->
不涉及

## 2.2 非功能质量属性设计
### 2.2.1 扩展性分析
<!-- 考虑后续新增类似功能可以很好地扩展 -->
不涉及

### 2.2.2 重用性分析
<!-- 是否为通用处理方式、接口，如果是得考虑重用性 -->
不涉及

### 2.2.3 可测试性分析
<!-- 此需求如何验证，是否可直接验证，or通过XXX功能覆盖验证，or需要单独怎加测试接口验证 -->
| 编号 | 用例描述 | 环境要求 | 测试步骤 | 预期结果 |
| --- | -------- | -------- | ------- | ------- |
| Case1 | 测试下发ipmi后能否加入数据库 | 环境能发通ipmi命令 | 1、 发送Get FDM Info指令 <br> 2、 使用访问本地数据库 t_systems_pcie_topo_info 查看数据库中的带内拓扑信息 | 数据库中的带内拓扑信息和发送的一致 |
| Case2 | 测试带内拓扑数据持久化 | 环境中存在拓扑数据 | 1、访问本地数据库 t_systems_pcie_topo_info查看数据 <br> 2、重启BMC，再次执行指令，和之前对比 | 两次数据一致 |

### 2.2.4 资料分析
<!-- 是否涉及资料修改 -->
不涉及

### 2.2.5 资源使用分析
<!-- 新增线程、内存分配、模型属性名长度是否合理，CPU占用率是否会激增，Flash中新增文件是否合理（频繁读写Flash会大幅缩短emmc寿命）；是否涉及消息队列，如果涉及请检查是否存在某些场景下消息队列会满导致消息丢失，例如大量消息发送到队列且处理消息需要耗费较长时间的场景。 -->
在接收ipmi命令期间，由于命令有很多条，在转发给sdk的时候会多次调用rpc方法，需要关注在开机后的CPU占用率、完成时间和内存分配，重点测试是否超过基线。

### 2.2.6 可靠性分析
| 编号 | 场景 | 问题描述 | 可靠性影响 | 问题级别 | 建议解决方案/需求 | 讨论结果 | 跟踪人 | 备注 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 1 | DC场景 ||||||||
| 2 | AC场景 | 数据库不应保留 | 如果保留可能和新数据冲突 | 一般 | 只进行复位持久化 ||||
| 3 | BMC场景 | 数据库需要保留 | 如果BMC重启不保留数据库，带内上报错误时找不到对应属性 | 严重 | 进行复位持久化 ||||
| 4 | 服务重启 ||||||||
| 5 | 数据获取异常状态 ||||||||

### SFEMA
| 用例编号 | 正交步骤 | 故障模式 | 故障影响 | 容错措施 | 故障注入方法 | 备注 |
| ------- | -------- | ------- | ------- | -------- | ----------- | ----- |
| Case1   | sdk中处理故障部分被裁剪 | 发送失败 | 拓扑信息没有转发目标 | pcie_device转发时用pcall进行，如果没有对应rpc方法不会退出 | 手动裁剪对应sdk内组件 | 无 |

### 2.2.7 安全性分析
| 安全合规项 | 是否涉及 | 现有的防护措施 |
| --- | --- | --- |
| 访问控制（通道、文件权限、用户权限、查询权限、配置权限、接口权限） | 不涉及 |  |
| 敏感数据 | 不涉及 |  |
| 日志（操作日志、维护日志、安全日志、运行日志） | 不涉及 |  |
| 文档 | 不涉及 |  |
| 加密及算法 | 不涉及 |  |
| 新增关键资源（密钥、证书、关键配置）备份、恢复 | 不涉及 |  |
| 新增对外接口入参校验 | 不涉及 |  |
| 新增开源及三方软件引入 | 不涉及 |  |
# 3.功能实现
<!-- 通过表格、流程图、简明文字描述提供，力求容易看懂、容易实现，详细描述细节。 -->
## 3.1【功能编号】支持接收bios发送的带内拓扑信息功能实现
### 3.1.1 功能实现设计

一、在pcie_device新增数据库对象PCIeMMIOResource
```json
"SystemsPCIeTopoInfo": {
    "tableName": "t_systems_pcie_topo_info",
    "tableType": "ResetPer",
    "tableLocation": "Local",
    "properties": {
        "GlobalSystemId": {
            "baseType": "U8",
            "default": 0,
            "primerKey": true
        },
        "LocalSystemId": {
            "baseType": "U8",
            "default": 0,
            "primerKey": true
        },
        "Segment": {
            "baseType": "U8",
            "default": 0,
            "primerKey": true
        },
        "Socket": {
            "baseType": "U8",
            "default": 0,
            "primerKey": true
        },
        "Bus": {
            "baseType": "U8",
            "default": 0,
            "primerKey": true
        },
        "Device": {
            "baseType": "U8",
            "default": 0,
            "primerKey": true
        },
        "Function": {
            "baseType": "U8",
            "default": 0,
            "primerKey": true
        },
        "GroupId": {
            "baseType": "U8",
            "default": 0
        },
        "ComponentType": {
            "baseType": "U8",
            "default": 0
        },
        "Slot": {
            "baseType": "U8",
            "default": 0
        },
        "VendorId": {
            "baseType": "U16",
            "default": 0
        },
        "DeviceId": {
            "baseType": "U16",
            "default": 0
        },
        "SecBus": {
            "baseType": "U8",
            "default": 0
        },
        "SubBus": {
            "baseType": "U8",
            "default": 0
        },
        "BDFNo": {
            "baseType": "U8",
            "default": 0
        },
        "Reserved1": {
            "baseType": "U8",
            "default": 0
        },
        "CfgLowBase": {
            "baseType": "U32",
            "default": 0
        },
        "CfgLowLimit": {
            "baseType": "U32",
            "default": 0
        },
        "CfgHighBase": {
            "baseType": "U64",
            "default": 0
        },
        "CfgHighLimit": {
            "baseType": "U64",
            "default": 0
        },
        "Reserved2": {
            "baseType": "U16",
            "default": 0
        },
        "Reserved4": {
            "baseType": "U32",
            "default": 0
        },
        "UpdateFlag": {
            "baseType": "U8",
            "default": 0
        },
        "MMIOCnt": {
            "baseType": "U8",
            "default": 0
        },
        "MMIO0Base": {
            "baseType": "U64",
            "default": 0
        },
        "MMIO0Limit": {
            "baseType": "U64",
            "default": 0
        },
        "MMIO1Base": {
            "baseType": "U64",
            "default": 0
        },
        "MMIO1Limit": {
            "baseType": "U64",
            "default": 0
        },
        "MMIO2Base": {
            "baseType": "U64",
            "default": 0
        },
        "MMIO2Limit": {
            "baseType": "U64",
            "default": 0
        },
        "MMIO3Base": {
            "baseType": "U64",
            "default": 0
        },
        "MMIO3Limit": {
            "baseType": "U64",
            "default": 0
        },
        "MMIO4Base": {
            "baseType": "U64",
            "default": 0
        },
        "MMIO4Limit": {
            "baseType": "U64",
            "default": 0
        },
        "MMIO5Base": {
            "baseType": "U64",
            "default": 0
        },
        "MMIO5Limit": {
            "baseType": "U64",
            "default": 0
        }
    }
}
```

二、在pcie_device组件中增加ipmi接口（已有接口）
[Set FDM Info](https://support.huawei.com/enterprise/zh/doc/EDOC1100401667/c7ae28a7)：

NetFn = 30h

CMD = 92h

Sub command = 17h

ActiveType = 05h（在920验证） 、 20h（在920X上验证）

对应优先级为OEM（即对应ipmi命令有限报送给pcie_device）

### 3.1.2 功能详细设计

收到带内发送的ipmi指令后，启动两个协程，一个用于将指令转发给sdk，一个用于保存数据库。

### 3.1.3 开发者测试
<!--
增加模块接口：以活动图/流程图等形式明确模块内处理流程，针对模块处理流程中的分支进行覆盖
修改模块接口处理流程：覆盖修改影响流程分支
-->
DT设计参考：
| 组件名 | 用例类型 | 测试用例描述 | 用例名称 | 预置条件 | 操作步骤 | 预期结果 |
| --- | --- | --- | --- | --- | --- | --- |
| firmware_mgmt | IT | 测试BMC固件更新生效状态 | test_update_bmc_active_status | 状态机为parallel_upgrading | 1.更新固件生效资源<br/>2.访问bmc.kepler.firmware_mgmt下/bmc/kepler/UpdateService/FirmwareActive/BMC接口<br/>3.查看/bmc/kepler/UpdateService/FirmwareActive中生效对象生效信息<br/>4.查看/bmc/kepler/UpdateService/FirmwareActive/BMC下bmc.kepler.UpdateService.FirmwareActiveInfo中生效信息 | 1.更新成功<br/>2.访问成功<br/>3.查询到bmc生效资源<br/>4.bmc生效信息：'FirmwareId'='BMC', 'FirmwareType'='BMC', 'ActiveStatus'='Ready' |
#### 3.1.3.1 单元测试
<!-- UT，主要是功能单元测试，测试对象是功能单元接口。UT测试设计要从黑盒（功能）角度设计，从输入(I)、处理（B）、预期输出（O）的角度进行用例分析设计，测试覆盖率仅作为反馈，用于分析哪些功能场景没有覆盖到，从而指导测试设计优化并补充测试用例 -->
#### 3.1.3.2 集成测试
<!-- IT，主要是组件/模块内的集成测试，测试对象是模块/组件接口。IT测试设计将模块/组件当作黑盒测试，IT测试用例中禁止对组件/模块内部代码打桩，如果确实有少量场景难以构造，可以考虑在测试框架中统一打桩并提供接口供测试用例调用构造场景。
说明：API测试属于IT，其测试对象是微服务接口。
PCST，是指PC上的服务集成测试，测试对象是功能需求。PCST测试设计，要覆盖正常功能、异常功能和交叉功能，采用灰盒 -->