*openUBMC 固件升级支持版本号检测详细设计说明书*

<table>
    <tr>
        <td>所属SIG组:</td>
        <td>hardware</td>
    </tr>
    <tr>
        <td>落入版本:</td>
        <td>26.0</td>
    </tr>
    <tr>
        <td>设计人员:</td>
        <td>lisongwei</td>
    </tr>
    <tr>
        <td>日期:</td>
        <td>2026/01/13</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>2026/01/13</td>
        <td>1.0</td>
        <td>通用硬件子系统固件升级支持版本号检测</td>
        <td>lisongwei</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 Programmable Logic Device</td>
        <td>复杂可编程逻辑器件</td>
    </tr>
    <tr>
        <td>MCU</td>
        <td>Microcontroller Unit</td>
        <td>微控制器</td>
    </tr>
    <tr>
        <td>VRD</td>
        <td>Voltage Regulator Device</td>
        <td>电压调节器器件</td>
    </tr>
    <tr>
        <td>SR</td>
        <td>Self Record</td>
        <td>自描述文件</td>
    </tr>
</table>

[TOC]

# 1.功能分析
## 1.1 功能背景
<!-- 描述该需求的来源或背景，比如：支撑XXX功能、XXX优化等；以及该需求对用户（含组件）带来什么具体价值，如果没有该需求，对用户（含组件）带来什么损失； -->
基础服务子系统支持hpm大包精细化能力，大包可以一次传入多个固件进行升级。当部分固件与设备实际运行版本一致时，无须执行升级动作。通用硬件子系统需要根据该场景，在固件升级时判断待升级的固件是否与设备实际运行版本一致，从而决定是否需要执行升级动作。

## 1.2 功能描述
<!-- 描述该需求交付的整体功能，主要实现XXX功能，解决XXX问题，明确方案如何实现 -->
当本组件收到固件升级请求时，获取升级固件包中附带的当前固件版本号，并与环境上待升级设备上已有固件版本进行对比。如果两者版本号一致，则不执行升级动作。

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

### 1.3.1 场景触发条件及对象
使用角色：系统管理员。使用工具：BMC前台网页。使用技能：具备基本的BMC管理经验。

### 1.3.2 使用时间及频度
基础服务子系统下发固件升级请求时，在升级流程中触发该判断逻辑。

### 1.3.3 主要场景及子场景
固件升级场景。

## 1.4 功能列表
<!-- 描述该需求交付的功能列表，内容包括：列出功能详细描述，标题、描述。 -->
| 功能编号 | 功能标题 | 功能描述 |
| ------- | ------- | -------- |
| 1 | 固件升级支持版本号检测 | 在固件升级过程中，检测待升级固件与环境上运行固件的版本号。若两者一致，则不进行升级操作。 |

# 2.功能设计
## 2.1 总体方案分析
<!-- 描述该方案的总体设计（注：相关输出方案可同步刷新到各组件仓） -->
为实现本方案功能，hpm包中的固件对象须新增一条属性，表示当前固件对象的版本。本组件执行升级流程时，在解析hpm包的配置文件过程中读取该版本号。后续升级动作中，当固件对象与环境上的设备匹配后，首先读取设备上实际运行的固件版本号并与配置文件中的版本号进行比较。如果两者版本号一致，则不进行升级操作。

### 2.1.1 方案详细设计
#### 2.1.1.1 方案概述
<!-- 描述该方案的整体实现，内容包括：涉及的关键点，实现策略等 -->
基础服务负责解析hpm包中的cfg文件，并在升级流程的信号入参中新增Version字段与ForceUpdate字段，通知本组件要如何进行升级。本组件解析基础服务下发的入参，判断是否存在Version字段与ForceUpdate字段，如果存在则校验这两个字段，判断是否需要强制升级。

如果校验结果为不升级，则跳过当前固件继续处理下一个固件，否则保持当前代码升级逻辑对固件进行升级。

升级流程结束时，本组件向基础服务返回结果时，如果有至少一个固件升级成功，则返回成功。如果所有固件都因为版本一致而跳过升级，则返回失败。

#### 2.1.1.2 开发视图
<!-- 开发视图面向系统开发及软件管理，描述系统代码结构，构建结构的视图，主要解决系统技术实现和开发的问题，它依托逻辑视图，描述代码、构建结构 -->
```mermaid
graph TB
    subgraph A[BMC前台]
        A1[固件升级界面]
    end
    
    subgraph B[基础服务]
        B1[固件包cfg文件解析]
        B2[固件升级管理模块]
    end

    subgraph C[general_hardware组件]
        C1[固件升级信号订阅模块]
        C2[固件升级流程]
    end

    A1 --> B1
    B1 --> B2
    B2 --> C1
    C1 --> C2
    C2 --> C1
    C1 --> B2
```


#### 2.1.1.3 运行视图
<!-- 运行视图面向系统运行，描述系统启动过程、运行期交互的视图，主要解决系统运行期交互，描述各可执行交付件在运行期的交互关系 -->
```mermaid
sequenceDiagram
    participant general_hardware as general_hardware组件
    participant firmware_mgmt as 基础服务

    firmware_mgmt->>general_hardware: 固件升级prepare阶段
    Note over general_hardware: 保持当前逻辑
    general_hardware-->>firmware_mgmt: 返回结果
    firmware_mgmt->>general_hardware: 固件升级process阶段
    Note over general_hardware: 判断入参是否带有Version字段和ForceUpdate字段？<br>是：判断待升级固件是否与Version版本一致，一致则跳过升级<br>否：保持当前逻辑
    general_hardware-->>firmware_mgmt: 返回结果：若所有固件都跳过升级，则返回失败，否则返回成功
    firmware_mgmt->>general_hardware: 固件升级finish阶段
    Note over general_hardware: 保持当前逻辑
    general_hardware-->>firmware_mgmt: 返回结果
    firmware_mgmt->>general_hardware: 固件升级active阶段
    Note over general_hardware: 保持当前逻辑
    general_hardware-->>firmware_mgmt: 返回结果

```

### 2.1.2 内部依赖分析
<!-- 是否涉及与其他组件接口依赖，如果涉及需要确认当前是否已完成，是否匹配当前需求开发诉求 -->
本组件代码开发不依赖其他组件，但是验证流程依赖基础服务。

### 2.1.3 外部依赖分析
<!-- 是否涉及与平台SDK的依赖关系 -->
依赖hpm包中update.cfg文件的Firmware域新增Version字段。

### 2.1.4 北向接口分析
<!-- 需要分析当前功能是否有以下接口影响，如果有影响，则需要具体的补充影响点。其中注意点如下：
（1）如果有新增IPMI接口，请排查代码中IPMI命令注册的过滤字段，是否完全和IPMI命令的定义一致？
（2）新增一个接口时，需要咨询SIG组是否还有其他的接口受影响 
（3）新增接口需要将对应接口属性名称和属性值列出，属性值若有单位、异常值处理、范围限制或格式规范也需要列出，对于标准接口需要列出标准接口文档中对应的属性名称和属性值相关规定-->
| 特性 | SNMP | CLI | WEB | KVM_VMM | IPMI(RMCP/RMCP+) | HMM | Redfish |
| ---- | ---- | ---- | --- | ------ | ---------------- | --- | ------- |
| 通用硬件子系统支持业务侧下电和重启生效的固件在注册固件清单时携带相关信息 | NA | NA | NA | NA | NA | NA | NA |

### 2.1.5 兼容性分析
<!-- 当前的功能对现有在网的功能是否有影响，具体的影响点进行分析之后输出影响分析表格 -->
如果升级的hpm包中不存在Version字段，则本需求开发的功能不生效，固件升级流程将按照现有的逻辑进行（即不进行版本判断，完成固件和设备的匹配后直接进行升级）。

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

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

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

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

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

### 2.1.11 用例场景分析
<!-- 以表格的形式输出该需求涉及的用例场景 -->

| 用例编号 | 用例名称 | 前置条件 | 操作步骤 | 预期结果 |
| ---- | ---- | ---- | ---- | ---- |
| 1 | 升级固件，固件包中版本号与当前运行版本一致 | 1. BMC正常运行<br> 2. 准备CPLD、MCU、VRD、SR、Retimer固件包，固件包中版本号与当前运行版本一致 | 1. 登录BMC前台，依次升级所有固件包，观察升级结果，预期有结果a<br>2. 查看general_hardware日志，预期有结果b | a. 所有固件均升级成功<br> b. 日志中记录有升级跳过的信息
| 2 | 升级固件，固件包中版本号与当前运行版本不一致 | 1. BMC正常运行<br> 2. 准备CPLD、SR、Retimer固件包，固件包中版本号与当前运行版本不一致 | 1. 登录BMC前台，依次升级所有固件包，观察升级结果，预期有结果a | a. 所有固件均升级成功
| 3 | 升级固件，固件包中无Version字段，实际固件包版本与当前运行版本一致 | 1. BMC正常运行<br> 2. 准备CPLD、MCU、VRD、SR、Retimer固件包，固件包中无Version字段，实际固件包版本与当前运行版本一致<br>3. 强制升级选项关闭 | 1. 登录BMC前台，依次升级所有固件包，观察升级结果，预期有结果a | a. 所有固件均升级成功
| 4 | 升级固件，固件包中无Version字段，实际固件包版本与当前运行版本不一致 | 1. BMC正常运行<br> 2. 准备CPLD、SR、Retimer固件包，固件包中无Version字段，实际固件包版本与当前运行版本不一致<br>3. 强制升级选项关闭 | 1. 登录BMC前台，依次升级所有固件包，观察升级结果，预期有结果a | a. 所有固件均升级成功

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

### 2.1.13 持久化分析
<!-- 当前的功能是否涉及持久化，尤其是持久化类型变更或某个属性新增了取值，是否兼容老版本 -->
不涉及

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

### 2.2.2 重用性分析
<!-- 是否为通用处理方式、接口，如果是得考虑重用性 -->
本方案开发的代码为组件内部处理逻辑，不涉及重用性。

### 2.2.3 可测试性分析
<!-- 此需求如何验证，是否可直接验证，or通过XXX功能覆盖验证，or需要单独怎加测试接口验证 -->
本方案开发的代码可以通过前台上传驱动包进行升级，之后观察升级结果，并且在后台读取本组件的日志进行验证。

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

### 2.2.5 资源使用分析
<!-- 新增线程、内存分配、模型属性名长度是否合理，CPU占用率是否会激增，Flash中新增文件是否合理（频繁读写Flash会大幅缩短emmc寿命）；是否涉及消息队列，如果涉及请检查是否存在某些场景下消息队列会满导致消息丢失，例如大量消息发送到队列且处理消息需要耗费较长时间的场景。 -->
不涉及

### 2.2.6 可靠性分析
| 编号 | 场景 | 问题描述 | 可靠性影响 | 问题级别 | 建议解决方案/需求 | 讨论结果 | 跟踪人 | 备注 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 1 | 固件升级，固件包为旧版本，无Version字段 | 解析cfg文件时，无法获取Version属性 | 影响对于是否需要强制升级该固件的判断 | 一般 | 代码中加入区分流程，如果固件包无Version字段，则默认强制升级，以兼容现有的升级逻辑。

### 2.2.7 安全性分析
| 安全合规项 | 是否涉及 | 现有的防护措施 |
| --- | --- | --- |
| 访问控制（通道、文件权限、用户权限、查询权限、配置权限、接口权限） | 不涉及 |  |
| 敏感数据 | 不涉及 |  |
| 日志（操作日志、维护日志、安全日志、运行日志） | 不涉及 |  |
| 文档 | 不涉及 |  |
| 加密及算法 | 不涉及 |  |
| 新增关键资源（密钥、证书、关键配置）备份、恢复 | 不涉及 |  |
| 新增对外接口入参校验 | 不涉及 |  |
| 新增开源及三方软件引入 | 不涉及 |  |
# 3.功能实现
<!-- 通过表格、流程图、简明文字描述提供，力求容易看懂、容易实现，详细描述细节。 -->
## 3.1 固件升级支持版本号检测
### 3.1.1 功能实现设计
基础服务负责解析hpm包中的cfg文件，并在升级流程的信号入参中新增Version字段与ForceUpdate字段，通知本组件要如何进行升级。本组件解析基础服务下发的入参，判断是否存在Version字段与ForceUpdate字段，如果存在则校验这两个字段，判断是否需要强制升级。
### 3.1.2 功能详细设计
本组件的固件升级流程process阶段需要新增判断逻辑。在process阶段中，具体对一个待升级的固件进行升级操作前，需要检查基础服务下发的入参parameters是否带有ForceUpdate字段。如果有，则说明基础服务已经开发了强制升级选项，进一步判断ForceUpdate取值是否为true。如果取值为true，说明当前需要强制升级，不进行后续判断，按照现有流程升级固件。如果取值为false，则判断当前待升级的固件与Version字段的值是否一致。如果两者一致，则跳过该固件的升级动作并记录日志，转而处理下一个固件。

当固件由于版本一致而跳过升级时，本组件需要向基础服务返回预先约定的返回值（71）以说明该情况。如果基础服务下发的升级信号匹配了本组件的多个固件，仅当所有待升级固件都跳过升级时返回71。如果有至少一个固件因为版本号不一致正常升级成功，则返回成功。
### 3.1.3 开发者测试
<!--
增加模块接口：以活动图/流程图等形式明确模块内处理流程，针对模块处理流程中的分支进行覆盖
修改模块接口处理流程：覆盖修改影响流程分支
-->
#### 3.1.3.1 单元测试
<!-- UT，主要是功能单元测试，测试对象是功能单元接口。UT测试设计要从黑盒（功能）角度设计，从输入(I)、处理（B）、预期输出（O）的角度进行用例分析设计，测试覆盖率仅作为反馈，用于分析哪些功能场景没有覆盖到，从而指导测试设计优化并补充测试用例 -->
不涉及
#### 3.1.3.2 集成测试
<!-- IT，主要是组件/模块内的集成测试，测试对象是模块/组件接口。IT测试设计将模块/组件当作黑盒测试，IT测试用例中禁止对组件/模块内部代码打桩，如果确实有少量场景难以构造，可以考虑在测试框架中统一打桩并提供接口供测试用例调用构造场景。
说明：API测试属于IT，其测试对象是微服务接口。
PCST，是指PC上的服务集成测试，测试对象是功能需求。PCST测试设计，要覆盖正常功能、异常功能和交叉功能，采用灰盒 -->
不涉及