firmware_mgmt ​

版本信息 ​

1. 组件概述 ​

1.1 组件简介 ​

固件管理为BMC基本功能特性，客户使用场景中主要涉及固件升级、固件生效、固件信息查询、固件回滚等。

1.2 解决什么问题 ​

firmware_mgmt组件主要解决固件升级流程的统一调度与协同问题、智能管理多固件升级的并发与冲突问题、升级过程的安全与信任问题、固件信息与状态的集中化管理问题、升级过程中的资源与异常管理问题以及装备定制化配置的注入问题。

1.3 核心功能 ​

• 固件升级

固件升级是客户使用过程中常见场景，如对BMC、BIOS、CPLD等固件进行升级。此功能使用频率较高。当前固件管理提供了串行升级和并行升级两种升级方式，功能上包括本地升级和远程升级。

本地升级：固件升级包已存在于BMC本地文件系统（位于 /tmp 目录下），升级时直接从本地路径读取固件包进行升级。

远程升级：固件升级包存储在远程服务器上，BMC通过网络协议（如FTP、TFTP、HTTP、NFS、SCP等）下载固件包到本地后再进行升级。适用于固件包存储在远程服务器，需要通过网络传输获取的场景。

• 固件生效

当前固件生效存在两种生效方式，一种是被动生效，一种是主动生效。 被动生效为固件管理模块检测到生效条件满足后自动触发生效任务，主动生效为客户通过BMC界面进行生效操作。 当前较危险的生效动作，如BMC升级后重启或者CPLD生效后进行掉电处理，此类操作可能会影响固件之间的生效，导致异常情况，因此由固件管理统一管理。

• 固件信息查询

当客户需要查询当前系统的固件信息时，如各固件的名称、类型、版本、发布时间等基本信息，此特性可以提供对所有固件信息进行统一管理，方便查询。

• 镜像回滚

当客户需要回滚到之前的固件版本时，此特性可以提供回滚操作，如BMC主备分区倒换功能。

1.4 关键术语表 ​

1.5 外部交互边界图 ​

固件升级功能时序图

并行升级功能时序图

白牌包升级时序图

2. API 使用说明与示例 ​

2.1 资源协作接口概览 ​

2.1.1 bmc.kepler.UpdateService ​

path:/bmc/kepler/UpdateService

properties

methods

• ParallelUpgradePackages详细说明

• UpdateProgress详细说明

• PendingFirmware详细说明

signals

2.1.2 bmc.kepler.UpdateService.FirmwareActive ​

path:/bmc/kepler/UpdateService/FirmwareActive

methods

signals

2.1.3 bmc.kepler.UpdateService.FirmwareActiveInfo ​

path:/bmc/kepler/UpdateService/FirmwareActive/:Id

properties

此接口内容通常是通过bmc.kepler.UpdateService.FirmwareActive下RegisterActiveAction方法添加。

添加案例：

local param = {}
param[#param+1] = {Key = 'FirmwareId', Value = 'CPLD'}
param[#param+1] = {Key = 'FirmwareType', Value = 'CPLD'}
param[#param+1] = {Key = 'ActiveCondition', Value = active_condition}
param[#param+1] = {Key = 'ActiveMode', Value = active_mode}
param[#param+1] = {Key = 'ActiveStatus', Value = active_status}
client:FirmwareActiveFirmwareActiveRegisterActiveAction(context.new(), param)

添加成功后，firmware_mgmt 存在关键日志：register: FirmwareId = xxx ......

2.1.4 bmc.kepler.UpdateService.FirmwareInventory ​

path:/bmc/kepler/UpdateService/FirmwareInventory

methods

• FirmwareInfoItem详细说明

2.1.5 bmc.kepler.UpdateService.FirmwareInfo ​

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

properties

此接口通常是通过 bmc.kepler.UpdateService.FirmwareInventory 下 Add 方法添加。

添加案例：

local FWINVENTORY_PATH = '/bmc/kepler/UpdateService/FirmwareInventory/'
local FIRMWARE_INFO_INTERFACE = 'bmc.kepler.UpdateService.FirmwareInfo'

...

local obj = mdb.get_object(bus, FWINVENTORY_PATH, FIRMWARE_INFO_INTERFACE)
local param = {
    Id = id,
    Name = name,
    Version = version,
    BuildNum = build_num or '',
    ReleaseDate = release_date or '',
    LowestSupportedVersion = lowest_supported_version or '',
    SoftwareId = software_id or '',
    Manufacturer = manufacturer or '',
    Location = location or '',
    State = state or 'Enabled',
    Severity = severity or 'Informational'
}
obj:Add(context.new(), param, true, 1, 90)
...

添加成功后，firmware_mgmt 存在关键日志：Add firmware inventory successfully, Id:xxx, ......。

如果添加失败，常见原因：

• 固件名称重复，添加失败，关键日志：Already exist the same Id:[xxx] to path xxx

• 固件信息参数不正确，方法调用失败。Add方法的FirmwareInfoTable签名为a{ss}，因此通过FirmwareInfoTable传参给 firmware_mgmt 需要保证内容为字符串（firmware_mgmt 会将字符串转换为资源协作接口定义的类型）

2.2 StartUpgrade ​

功能说明 ​

启动固件升级。

参数说明 ​

AdditionalOptions键值对举例

返回值与异常 ​

应用场景 ​

启动固件升级。

调试示例 ​

命令行调试 ​

busctl --user call bmc.kepler.firmware_mgmt /bmc/kepler/UpdateService bmc.kepler.UpdateService StartUpgrade a{ss}is 3 Interface Busctl UserName Administrator ClientAddr <ip> 1 /tmp/openUBMC.hpm

响应：u 3

2.3 ParallelUpdate ​

功能说明 ​

启动固件并行升级。

参数说明 ​

UpgradeOptions键值对举例

AdditionalOptions键值对举例

返回值与异常 ​

应用场景 ​

启动固件并行升级。

调试示例 ​

命令行调试 ​

注意： 不建议通过busctl命令直接进行并行升级，推荐使用redfish接口：/redfish/v1/UpdateService/Actions/Oem/{{OemIdentifier}}/UpdateService.ParallelUpdate。

3. 组件扩展案例 ​

3.1 扩展能力概述 ​

提供客户定制验签方式。

3.2 扩展点说明 ​

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

3.3 二次开发指导 ​

步骤一 ​

FirmwareCustomConfig对象中配置CustomVerifyEnabled和CustomVerifyLibraryName属性，分别表示客户验签流程定制使能和客户验签流程定制库名称。

步骤二 ​

客户新增定制库/opt/bmc/luaclib/xxx.so，并实现xxx.so库中的内容，提供方法parse_hpm_file供lua接口调用。

示例代码 ​

"FirmwareCustomConfig": {
    "CustomVerifyEnabled": true, //客户签名定制使能
    "CustomVerifyLibraryName": "sign_verify" //客户签名定制库为sign_verify.so
}

验证方法 ​

日志说明

注意事项 ​

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

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 调试方法 ​

开启调试日志 ​

busctl资源协作接口方法调试见文档第二章节。

更多命令请查阅《升级你的BMC》、《整包升级指导》。

7. 常见问题解答 ​

常见问题解答请查阅《MCU、VRD、CSR、CPLD升级与板卡管理问题指南》、《升级常见问题指南》。

附录 ​

附录A 参考资料 ​

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

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

• 《升级常见问题指南》

• 《升级你的BMC》

• 《整包升级指导》

附录B 修订记录 ​