bmc_upgrade ​

版本信息 ​

1. 组件概述 ​

1.1 组件简介 ​

bmc_upgrade是BMC固件升级管理组件，负责BMC自身固件的具体升级执行。该组件响应firmware_mgmt发出的升级信号，执行实际的BMC固件升级操作，包括升级包解密、flash写入、分区切换等。

1.2 解决什么问题 ​

bmc_upgrade组件主要解决BMC自身固件升级的具体执行问题，与firmware_mgmt协同工作：firmware_mgmt负责升级流程调度和协调，bmc_upgrade负责BMC固件升级的实际执行。主要解决以下问题：

• BMC固件升级三阶段的具体实现（prepare、process、finish）
• 升级包的解密和flash写入
• 启动分区切换和回滚操作
• BMC固件信息的管理和注册
• 版本号定制化支持

1.3 核心功能 ​

• 固件升级

响应firmware_mgmt发出的UpgradePrepareSignal、UpgradeProcessSignal、UpgradeFinishSignal信号，执行BMC固件升级的三个阶段：

prepare阶段：

验证固件类型是否为BMC升级消息

解析升级配置文件（update.cfg）

解析扩展参数（RestoreFactorySettings、ActiveMode、Platform等）

回复PrepareReply给firmware_mgmt

process阶段：

解密升级包（AES CBC 128算法）

提取升级镜像文件

获取当前启动分区，计算目标写入分区

格式化目标分区并写入镜像

设置启动分区标志

回复ProcessReply给firmware_mgmt

finish阶段：

更新AvailableBMC固件信息到数据库

向firmware_mgmt注册生效动作（ActiveMode）

若需要恢复出厂设置，发送RestoreFactorySettings信号

回复FinishReply给firmware_mgmt

• 固件回滚

响应firmware_mgmt发出的RollbackSignal信号，执行BMC固件回滚：

查询ActiveBMC和AvailableBMC的固件信息

更新AvailableBMC的版本信息

获取当前启动分区，设置启动分区为另一个分区

调用GracefulReset复位BMC

• 固件信息管理

维护BMC固件信息表（BmcFwInfoTable），包括：

ActiveBMC：当前运行的BMC固件信息

AvailableBMC：可用分区的BMC固件信息

ActiveBMCSDK：当前运行的BMC SDK固件信息

向firmware_mgmt注册BMC固件信息

支持版本号定制化（根据Customer获取定制版本）

• 升级管理配置

管理BMC升级相关的配置：

降级控制（DowngradeAllowed）

撤销版本管理（RevokedVersions）

恢复出厂设置选项

1.4 关键术语表 ​

1.5 外部交互边界图 ​

BMC固件升级时序图

bmc_upgrade与firmware_mgmt的交互流程：

firmware_mgmt                    bmc_upgrade
     |                                  |
     |------ UpgradePrepareSignal ----->|
     |                                  |--- prepare阶段处理
     |<----- PrepareReply --------------|
     |                                  |
     |------ UpgradeProcessSignal ----->|
     |                                  |--- process阶段处理
     |<----- ProcessReply --------------|
     |                                  |
     |------ UpgradeFinishSignal ------>|
     |                                  |--- finish阶段处理
     |<----- FinishReply ---------------|
     |                                  |

2. API 使用说明与示例 ​

2.1 资源协作接口概览 ​

2.1.1 bmc.kepler.UpdateService.ManagerVersion ​

path: /bmc/kepler/UpdateService/ManagerVersion

properties

methods

2.1.2 bmc.kepler.UpdateService.UpdateMgmt ​

path: /bmc/kepler/UpdateService/UpdateMgmt

properties

methods

signals

2.1.3 bmc.kepler.UpdateService.FirmwareInfo ​

path: /bmc/kepler/UpdateService/FirmwareInventory/:Id

bmc_upgrade组件负责维护和注册BMC相关的固件信息，包括：

properties

此接口由bmc_upgrade组件通过调用firmware_mgmt的Add方法添加。

添加案例：

local ctx = require('mc.context').get_context_or_default()
local datas = {
    Id = 'ActiveBMC',
    Name = 'ActiveBMC',
    Version = '5.11.00.01',
    BuildNum = '001',
    ReleaseDate = '14:14:47 Sep 14 2025',
    LowestSupportedVersion = '5.00.00.01',
    SoftwareId = 'BMC-iBMC',
    Manufacturer = 'Huawei',
    Location = '',
    State = 'Enabled',
    Severity = 'Informational',
    ComponentID = '25',
    SubComponentID = '4294967295',
    TargetUIDs = '',
    RelatedItem = '/redfish/v1/Managers/1'
}
obj:Add(ctx, datas, true, 5, 90)

添加成功后，存在关键日志：register firmware [ActiveBMC] successfully。

2.2 GetReleaseVersion ​

功能说明 ​

获取BMC各分区的版本号信息。

参数说明 ​

无输入参数。

返回值与异常 ​

应用场景 ​

查询BMC各分区的固件版本号，用于升级前确认版本信息或升级后验证版本。

调试示例 ​

命令行调试 ​

busctl --user call bmc.kepler.bmc_upgrade /bmc/kepler/UpdateService/ManagerVersion bmc.kepler.UpdateService.ManagerVersion GetReleaseVersion

响应：sss "5.11.00.01" "5.11.00.01" "5.10.00.01"

2.3 AddRevokedVersions ​

功能说明 ​

添加撤销版本，用于防止固件回退到指定版本。

参数说明 ​

返回值与异常 ​

无返回值。

应用场景 ​

防止固件回退到已知存在安全漏洞的版本，配合RevokedVersionEnabled使用。

调试示例 ​

命令行调试 ​

busctl --user call bmc.kepler.bmc_upgrade /bmc/kepler/UpdateService/UpdateMgmt bmc.kepler.UpdateService.UpdateMgmt AddRevokedVersions s "5.00.00.01"

3. 组件扩展案例 ​

3.1 扩展能力概述 ​

bmc_upgrade组件支持以下扩展能力：

• 版本号定制化：根据Customer信息获取定制版本号
• 恢复出厂设置：升级后可触发恢复出厂设置流程

3.2 版本号定制化 ​

扩展点说明 ​

BMC版本号支持定制化，根据客户信息（Customer）获取对应的定制版本号。

二次开发指导 ​

步骤一

在Package对象中配置Customer属性，指定客户名称。

步骤二

在/opt/bmc/extend/<Customer>/目录下创建version.json文件，内容示例：

{
    "Version": "5.11.00.01-Custom"
}

验证方法 ​

3.3 恢复出厂设置 ​

扩展点说明 ​

升级时可通过AdditionalOptions参数指定升级后恢复出厂设置。

使用方式 ​

在升级参数中设置RestoreFactorySettings=true：

local para_tab = {
    RestoreFactorySettings = "true"
}

升级完成后，bmc_upgrade会发送RestoreFactorySettings信号给oms组件处理。

4 CSR配置介绍 ​

4.1 UpdateMgmt对象配置介绍 ​

此对象用于配置BMC升级管理相关参数。

4.2 BmcFwInfoTable对象配置介绍 ​

此对象用于持久化BMC固件信息，由bmc_upgrade组件内部维护。

3. 组件扩展案例 ​

3.1 扩展能力概述 ​

提供客户定制验签、拆包解析方式。

3.2 扩展点说明 ​

客户可以定制hpm解析的接口库（xxx.so），自行实现xxx.so中的内容。详见《固件验签、拆包解析定制要求及使用指导》。

3.3 二次开发指导 ​

步骤一 ​

定制固件验签、拆包解析需要配置CSR，需要在FirmwareCustomConfig对象中配置CustomVerifyEnabled、CustomVerifyLibraryName、CustomParseEnabled、CustomParseLibraryName属性。属性说明见下表：

步骤二 ​

• 验签定制：客户新增定制库/opt/bmc/luaclib/xxx.so，并实现xxx.so库中的内容，提供方法parse_hpm_file供lua接口调用。
• 拆包解析定制：客户新增定制库/opt/bmc/luaclib/xxx.so，并实现xxx.so库中的内容，提供方法 custom_parse_pkg供lua接口调用。

示例代码 ​

"FirmwareCustomConfig": {
    "CustomVerifyEnabled": true, //客户签名定制使能
    "CustomVerifyLibraryName": "sign_verify", //客户签名定制库为sign_verify.so
    "CustomParseEnabled": true, //客户拆包解析定制使能
    "CustomParseLibraryName": "hpm_parser" //客户拆包解析定制库为hpm_parser.so
}

验证方法 ​

固件验签 ​

日志说明

注意事项 ​

1. 确保在指定路径/opt/bmc/luaclib下新增定制库；
2. 定制库xxx.so库中需提供方法parse_hpm_file供lua接口调用，并且入参file_path为hpm包路径；响应返回约定的状态码标识。

拆包解析 ​

日志说明

注意事项 ​

1. 确保在指定路径/opt/bmc/luaclib下新增定制库；
2. 定制库xxx.so库中需提供方法custom_parse_pkg供lua接口调用，并且入参file_path为hpm包路径，output_dir为拆包解析后数据存放目录；响应为true（解析成功）/false（解析失败），且在output_dir下存放必带文件。

4 CSR配置介绍 ​

4.1 FirmwareComponentInfo对象配置介绍 ​

此对象用于配置允许升级的固件，由ComponentID与ComponentIDEx确定唯一的固件，Name用于描述固件的名称

4.2 ActiveComponentInfo对象配置介绍 ​

此对象用于配置允许生效的固件名称。

4.3 MutuallyExclusiveFirmwares对象配置介绍 ​

此对象用于配置禁止固件同时升级的互斥关系，Id的构成方式为ComponentID与ComponentIDEx的组合的U64类型转换成字符串，其中ComponentID占高四字节，举例："0x0000000505000001"。

5. 日志说明 ​

5.1 一键日志收集 ​

5.2 关键日志信息 ​

6. 问题定界指南 ​

6.1 典型问题定界 ​

6.2 错误码速查表 ​

6.3 调试方法 ​

开启调试日志 ​

可通过查看bmc_upgrade服务日志获取调试信息：

journalctl -u bmc_upgrade -f

查询版本信息 ​

# 查询ManagerVersion属性
busctl --user get-property bmc.kepler.bmc_upgrade /bmc/kepler/UpdateService/ManagerVersion bmc.kepler.UpdateService.ManagerVersion Version

# 查询各分区版本号
busctl --user call bmc.kepler.bmc_upgrade /bmc/kepler/UpdateService/ManagerVersion bmc.kepler.UpdateService.ManagerVersion GetReleaseVersion

查询升级管理配置 ​

# 查询是否允许降级
busctl --user get-property bmc.kepler.bmc_upgrade /bmc/kepler/UpdateService/UpdateMgmt bmc.kepler.UpdateService.UpdateMgmt DowngradeAllowed

# 查询撤销版本配置
busctl --user get-property bmc.kepler.bmc_upgrade /bmc/kepler/UpdateService/UpdateMgmt bmc.kepler.UpdateService.UpdateMgmt RevokedVersions

7. 常见问题解答 ​

7.1 BMC升级失败如何排查？ ​

1. 检查升级包格式是否正确
2. 检查flash空间是否充足（需预留90MB以上tmp空间）
3. 查看bmc_upgrade日志定位具体失败阶段
4. 确认是否允许降级（DowngradeAllowed配置）

7.2 如何配置防回退？ ​

通过CSR配置DowngradeAllowed=false禁止降级，或通过RevokedVersions配置撤销版本列表。

7.3 如何查看BMC各分区版本？ ​

调用GetReleaseVersion方法或查询ManagerVersion属性。

更多问题请查阅《升级常见问题指南》。

附录 ​

附录A 参考资料 ​

• 《固件验签定制要求及使用指导》

• 《MCU、VRD、CSR、CPLD升级与板卡管理问题指南》

• 《升级常见问题指南》

• 《升级你的BMC》

附录B 修订记录 ​