本文档主要介绍如何启动并在BMC业务中使用QEMU。

1. 🛠️ QEMU 环境搭建 ​

什么是 QEMU？ ​

QEMU 是一个开源的硬件仿真器，可以在你的电脑上模拟出一台完整的服务器。对于 BMC（基板管理控制器）开发来说，这是一个非常实用的工具——你不需要准备真实的硬件单板，就可以在虚拟环境中验证大部分功能。

想象一下，传统的开发流程是这样的：修改代码 → 编译 → 烧录到硬件 → 启动服务器 → 测试功能 → 发现问题 → 重复上述过程。每次测试都需要硬件配合，而且烧录固件也需要时间。

有了 QEMU，流程就变成了：修改代码 → 编译 → 重启 QEMU → 测试功能。整个过程在本地就可以完成，大大缩短了开发周期。

为什么使用 openUBMC 的 QEMU？ ​

openUBMC 社区针对 BMC 开发的特点，对 QEMU 做了专门的优化和配置。主要优势包括：

• 预配置好的硬件拓扑：模拟了真实服务器的硬件结构，不用自己从头搭建
• 完整的北向接口支持：CLI、Redfish、Web、IPMI 等接口开箱即用
• 便捷的启动方式：提供脚本和 deb 包两种启动方式，适应不同使用场景
• 活跃的社区支持：遇到问题可以在论坛上交流讨论

关于 manifest 仓库

你可能会问：为什么总是提到 manifest 仓库？这是因为 manifest 是 openUBMC 社区维护的配置管理中心，里面包含了：

• 启动脚本：用于拉起 QEMU 虚拟机
• 配置文件：定义了硬件拓扑、端口映射、PCIe 卡等
• 初始化工具：自动下载和配置 BMC 运行所需的各种文件

后续的环境初始化、QEMU 启动、PCIe 卡配置等操作都需要通过 manifest 仓库来完成。简单来说，它是你使用 openUBMC QEMU 的"控制中心"。

manifest 仓库地址：https://gitcode.com/openUBMC/manifest

每次都需要保持本地的 manifest 仓库是最新的，可以执行下面的指令：

# 如果第一次 git clone manifest 仓库
git clone https://gitcode.com/openUBMC/manifest.git  
cd manifest  
git pull

环境初始化 ​

第一次使用前，需要先初始化环境。这一步会下载必要的文件和配置。

cd manifest
python3 init.py -path <bmc_sdk.zip文件路径> -user <openUBMC社区用户名> -psw <openUBMC社区用户密码>

参数说明：

• -path：bmc_sdk.zip 文件的路径，这个 zip 包包含了 BMC 固件运行所需的基础文件（获取路径：https://www.openubmc.cn/zh/marketplace/bmcsdk）
• -user：你的 openUBMC 社区用户名
• -psw：你的 openUBMC 社区密码

1.1 方式一：通过脚本启动 ​

这是最直接、最常用的启动方式，特别适合日常的开发调试。

为什么推荐这种方式？ ​

脚本启动方式的优点：

• 简单直接：一条命令就能启动，不需要额外配置
• 调试友好：QEMU 的输出会直接显示在终端，方便查看日志
• 灵活可控：可以通过修改脚本参数调整 QEMU 的配置
• 更新及时：脚本总是和 manifest 仓库同步，第一时间获得最新功能

启动 QEMU ​

cd manifest 
python3 build/works/packet/qemu_shells/vemake_1711.py

执行后，你会看到 QEMU 的启动日志滚动显示。等待一段时间后，BMC 固件就会启动完成，你可以通过 SSH 或者 Web 界面连接进去。

Uncompressing... done, booting...
[    0.000000] Booting Linux on physical CPU 0x0000000000 [0x412fd050]
[    0.000000] Linux version 5.10.0 (oe-user@oe-host) (aarch64-euler-linux-gcc (BiSheng Embedded CPU 302.1.0.B016) 7.3.0, GNU ld (BiSheng Embedded CPU 302.1.0.B016) 2.41) #1 SMP PREEMPT Tue Nov 26 22:03:48 CST 2024

如何停止 QEMU？ ​

有时候你需要停止 QEMU，比如要修改配置或者结束今天的工作。

方法 1：优雅退出（推荐）

在 QEMU 启动的终端窗口中，直接按 Ctrl + C，脚本会自动清理相关进程。

方法 2：强制结束

如果 Ctrl + C 没有响应，可以用 kill 命令强制结束：

# 先查看 QEMU 进程的 PID
ps aux | grep qemu

# 然后结束进程，<pid> 对应 QEMU 进程的 PID
# 一般情况下查找 qemu-system-aarch64 所对应的 PID 号
kill -9 <pid>

1.2 方式二：通过 .deb 软件包启动 ​

如果你习惯了使用 Linux 的包管理工具，或者需要在自动化测试、CI/CD 流程中使用，deb 包方式会更方便。在最开始环境初始化的过程中，就已经将 deb 包安装好了，剩下的事情就只需要一键启动即可。

什么时候选择这种方式？ ​

• CI/CD 环境：在持续集成流程中，使用 deb 包更容易集成
• 多台机器部署：安装一次 deb 包，之后可以快速启动
• 命令行偏好：习惯了 apt install 的操作方式

deb 包相关命令 ​

# 查询版本命令
openubmc-qemu version

# 查询接口状态命令（当接口 up 时，用户就可以连接）
openubmc-qemu status

# 关闭 QEMU 命令
openubmc-qemu close

启动 QEMU ​

# 初始化环境（第一次使用时需要）
openubmc-qemu init

# 启动 QEMU
openubmc-qemu run --remote

--remote 参数表示使用远程模式，这样 QEMU 的服务端口会映射到宿主机上，你可以通过网络访问。

1.3 连接到 QEMU 中的 BMC ​

QEMU 启动后，BMC 固件就开始运行了。但是你还没有办法直接操作它，因为 BMC 运行在 QEMU 虚拟出来的"服务器"里，而不是你的物理电脑。

为了解决这个问题，QEMU 使用了端口映射技术。简单来说，就是把虚拟机里的端口"转发"到你的物理电脑上。

举个例子，当你连接 127.0.0.1:10022 时，实际上连接的是虚拟机里的 22 端口（SSH）。

SSH 连接 ​

SSH 是最常用的连接方式，可以执行各种管理命令。在登录 SSH 之前需要知晓宿主机的 IP，在 Linux 中执行 ifconfig 查看 IP，找到 eth0 的 IP，然后在宿主机中执行：

# 此处默认的 IP 地址是 localhost 也就是 127.0.0.1
ssh -p 10022 Administrator@127.0.0.1

输入密码 Admin@90000 后，你就进入了 BMC 的命令行界面，可以像操作真实服务器一样执行各种命令。

默认账号信息：

• 用户名：Administrator
• 密码：Admin@90000

安全提示：在生产环境中，请务必修改默认密码！

Telnet 连接 ​

Telnet 是一个更简单的协议，主要用于调试。

telnet 127.0.0.1 10023

1.4 卸载 deb 包 ​

apt purge -y openubmc-qemu

2. 🌐 BMC 北向接口在 QEMU 中的应用 ​

什么是北向接口？ ​

BMC（基板管理控制器）是服务器上的一个小型独立计算机，负责监控和管理服务器的各种状态。但是 BMC 自己不会主动去"管理"什么——它需要和外部管理系统配合工作。

北向接口就是 BMC 对外提供的"沟通渠道"。通过这些接口，外部的管理系统（比如数据中心管理平台、监控软件）可以：

• 查询服务器的硬件状态（温度、电压、风扇转速等）
• 控制服务器的电源（开机、关机、重启）
• 管理固件版本
• 配置各种参数
• 接收告警通知

openUBMC 支持以下北向接口：CLI、Redfish、Web、IPMI。每个接口都有自己的特点和适用场景。

QEMU 如何暴露这些接口？ ​

在真实的服务器上，BMC 的北向接口通过网络对外提供服务。在 QEMU 虚拟环境中，我们使用端口转发技术，把虚拟机里的端口映射到宿主机上。

这样，你就可以在宿主机上直接访问 BMC 的各种服务，就像访问一台真实服务器的 BMC 一样。

⌨️ a) CLI 接口（命令行接口） ​

CLI（Command Line Interface）是最直接、最原始的管理方式。通过命令行，你可以执行几乎所有的 BMC 管理操作。

CLI 的特点 ​

• 响应快速：没有图形界面的开销，命令执行速度快
• 适合脚本：可以编写脚本批量执行操作
• 调试利器：开发者最常用的接口，可以快速定位问题
• 功能完整：几乎所有功能都可以通过 CLI 访问

步骤 1：查看版本信息 ​

连接上 BMC 后，第一件事通常是查看版本信息，确认 BMC 固件是否正确加载。BMC 提供丰富的 CLI 命令，如下图所示，可以看到 ipmcget 命令支持查询固件版本信息、查询时间等操作。

ipmcget -d v

执行后会输出 BMC 的版本信息，包括：

• BMC 固件版本号
• BIOS/UEFI 版本
• CPLD 版本
• 各种子卡固件版本

步骤 2：使用 D-Bus 接口 ​

D-Bus 是 Linux 系统中用于进程间通信的机制。在 openUBMC 中，各个功能模块之间通过 D-Bus 互相调用，协同工作。

通过 busctl 命令，你可以：

• 查看 BMC 的组件结构
• 查看每个组件提供的接口
• 调用组件的方法
• 监听组件的事件

查看组件资源协作接口：

# 命令可以依赖 bmc.kepler.<组件名> 来拼接
# 以固件管理 firmware_mgmt 为例
busctl --user tree bmc.kepler.firmware_mgmt

这个命令会显示 bmc.kepler 服务的对象树结构，像文件系统的目录树一样，展示了各个子组件的层级关系。

查看接口定义：

busctl --user introspect bmc.kepler.firmware_mgmt /bmc/kepler/UpdateService/FirmwareInventory/ActiveBMC

introspect 命令会详细列出某个对象的所有接口、方法、属性和信号，包括它们的参数类型和返回值类型。这对于开发者来说是非常有用的调试工具。

🦊 b) Redfish 接口 ​

Redfish 是 DMTF（分布式管理任务组）制定的现代数据中心管理标准。相比传统的 IPMI 协议，Redfish 具有以下优势：

Redfish 的优势 ​

• 基于 HTTP/HTTPS：使用标准的 Web 协议，易于集成
• JSON 格式：数据格式简洁，解析方便
• RESTful 风格：API 设计符合 REST 规范，直观易懂
• 安全性更好：支持 HTTPS 和现代认证机制
• 扩展性强：可以方便地添加新的资源和功能

认证信息 ​

• 访问地址：https://127.0.0.1:10443
• 用户名：Administrator
• 密码：Admin@90000

步骤 1：使用 Postman 测试 ​

Postman 是一个流行的 API 测试工具，提供图形化界面，支持保存请求历史，非常适合用来调试 Redfish 接口。

操作步骤：

1. 打开 Postman，新建一个请求
2. 选择请求方法（GET 用于查询数据，POST 用于创建资源，PATCH 用于修改资源）
3. 输入 URL：https://127.0.0.1:10443/redfish/v1/
4. 配置认证：
   • 切换到 Authorization 标签
   • Type 选择 Basic Auth
   • Username 输入 Administrator
   • Password 输入 Admin@90000
5. 关闭 SSL 验证：Settings → SSL certificate verification → Off（因为 QEMU 使用的是自签名证书）
6. 点击 Send 发送请求

步骤 2：查询系统信息 ​

Redfish 使用树状结构组织资源，/redfish/v1/ 是根路径，从这里可以访问所有子资源。

查询系统信息：

curl -k -u Administrator:Admin@90000 \
  https://127.0.0.1:10443/redfish/v1/Systems/1

返回的 JSON 数据包含了服务器的各种信息：

• SerialNumber：序列号
• Model：型号
• Status：健康状态
• PowerState：电源状态
• Boot：启动配置

💻 c) Web 接口（Web UI） ​

Web UI 是最直观、最易用的管理方式。你不需要记忆任何命令，也不需要编写代码，通过浏览器就可以完成大部分管理操作。

Web UI 的特点 ​

• 图形化界面：直观易用，不需要培训
• 实时监控：可以查看传感器的实时读数
• 功能全面：支持固件管理、用户配置、网络设置等
• 跨平台：只要有浏览器就可以使用

访问方式 ​

在浏览器中打开：https://127.0.0.1:10443

输入用户名和密码登录即可。

步骤 1：访问 Web UI ​

登录后，你会看到 BMC 的主界面，这里显示了服务器的整体状态概览。

主界面通常包括：

• 系统信息：型号、序列号、健康状态
• 传感器读数：温度、电压、风扇转速
• 电源状态：开机/关机状态
• 告警信息：最近的告警事件

步骤 2：固件管理 ​

固件管理页面可以查看和升级各个组件的固件版本。

这里可以管理：

• BMC 固件：BMC 本身的固件
• BIOS/UEFI：主板的 BIOS 固件
• CPLD/FPGA：各种可编程逻辑器件的固件
• 子卡固件：网卡、RAID 卡等扩展卡的固件

步骤 3：服务管理 ​

服务管理页面可以配置 BMC 提供的各种网络服务。

可配置的服务包括：

• SSH 服务：命令行接口
• Web 服务：Web UI 和 Redfish
• IPMI 服务：IPMI over LAN
• 虚拟控制台：KVM/VNC 重定向

你可以启用或禁用某个服务，修改监听端口，配置访问白名单等。

🛠️ d) IPMI 接口 ​

IPMI（Intelligent Platform Management Interface，智能平台管理接口）是 BMC 的传统协议。虽然 Redfish 已经成为新的标准，但 IPMI 在许多存量系统中仍然被广泛使用。

IPMI 的特点 ​

• 历史悠久：从上世纪 90 年代就开始使用
• 兼容性好：几乎所有的服务器都支持
• 工具成熟：有大量的管理工具可以使用
• 安全性较低：相比 Redfish，IPMI 的安全性较弱

认证信息 ​

• 端口：10623
• 用户名：Administrator
• 密码：Admin@90000

步骤 1：查询 FRU 信息 ​

FRU（Field Replaceable Unit，现场可替换单元）信息记录了硬件的各种标识数据，包括制造商、型号、序列号等。这些信息对于资产管理和故障追踪非常重要。

ipmitool -I lanplus -H 127.0.0.1 -p 10623 -U Administrator -P Admin@90000 fru

FRU 信息通常包括：

• Product Info：产品制造商、型号、序列号
• Board Info：主板信息、生产日期
• Chassis Info：机箱类型、机箱序列号

步骤 2：读取电子标签 ​

电子标签（E-label）存储在组件的 EEPROM 中，是一种更灵活的存储格式。和 FRU 相比，电子标签可以存储更多信息，并且更容易更新。

ipmitool -I lanplus -H 127.0.0.1 -p 10623 -U Administrator -P Admin@90000 raw 0x30 0x90 0x05 0x01 0x2 0x03 0x00 0x3

这条命令使用 IPMI 的 raw 命令直接发送底层指令。参数的含义：

• 0x30 0x90：读取电子标签的命令码
• 0x05：FRU ID
• 0x01：区域（Board/Product/Chassis）
• 0x2：字段类型
• 0x03：偏移量
• 0x00：读取起始位置
• 0x3：读取长度

3. 🏗️ QEMU 进阶应用 ​

前面的章节介绍了基本的接口使用，这一节我们会进入更高级的主题：模拟复杂的硬件场景。

为什么需要进阶应用？ ​

在真实的运维环境中，服务器会遇到各种突发情况：温度过高、电源故障、设备损坏等。BMC 需要能够及时发现这些异常，并采取相应的措施（发出告警、自动关机、调整风扇转速等）。

如何验证 BMC 的异常处理逻辑是否正确？你不可能真的去破坏硬件来测试。QEMU 提供了一种安全的方式：在虚拟环境中模拟各种异常场景。

本节介绍两个实用场景：

1. PCIe 卡热插拔：模拟在线更换 PCIe 设备
2. 事件模拟：模拟各种硬件告警事件

⏰ 3.1 PCIe 卡热插拔 ​

什么是热插拔？ ​

热插拔（Hotplug）是指在系统运行状态下，在线添加或移除硬件设备，而不需要关机。

在数据中心运维中，这是一个非常实用的功能。比如：

• 服务器的网卡坏了，需要更换新的网卡
• 需要增加一块 NVMe 硬盘来扩容
• RAID 卡故障，需要紧急更换

传统做法是关机 → 更换硬件 → 开机，这会导致服务中断。有了热插拔，你可以在不影响服务的情况下完成硬件更换。

BMC 在热插拔中的作用 ​

当 PCIe 设备插入或拔出时，硬件会触发中断信号。BMC 需要能够：

1. 检测到设备变化
2. 识别新设备的类型和信息
3. 更新资产记录
4. 发送告警通知给管理系统

通过 QEMU，我们可以模拟整个热插拔流程，验证 BMC 的响应是否正确。

默认支持的 PCIe 卡 ​

openUBMC 的 QEMU 环境目前支持以下 PCIe 卡的仿真：

步骤 1：查看 pcie_card.json 配置 ​

PCIe 卡的配置信息存储在 manifest 仓库的 pcie_card.json 文件中。这个文件控制着哪些 PCIe 卡"在位"（present）、每个卡的 CSR 数据是什么。

文件中每个 PCIe 卡都有一个 present 字段：

• 1 表示该卡在位（BMC 会尝试识别它）
• 0 表示该卡不在位（BMC 会忽略它）

步骤 2：修改 CSR 名称并启用 ​

CSR（Command Status Register）是一组记录 PCIe 卡信息的寄存器，包括设备 ID、厂商 ID、子系统 ID 等。

要将一张 PCIe 卡"插入"系统，需要：

1. 将 present 字段改为 1
2. 配置正确的 CSR 名称（这个名字对应 vpd 仓库中的 CSR 文件）

CSR 数据可以从 vpd 仓库获取，这里存放了各种 PCIe 卡的标准 CSR 定义：

步骤 3：添加仿真数据 ​

光有 CSR 名称还不够，BMC 还需要知道 PCIe 卡的详细属性，比如设备名称、功能类型、链路状态等。这些信息需要在配置文件中完整定义。

配置示例（SP670 网卡）：

"PCIeDevice_1": {
    "DeviceName": "PCIe Card $ (SP670)",
    "FunctionClass": 2,
    "DiagnosticFault": 0,
    "PredictiveFault": 0,
    "CorrectableError": 0,
    "UncorrectableError": 0,
    "FatalError": 0,
    "DeviceType": 8,
    "PCIeDeviceType": "MultiFunction",
    "SlotType": "FullLength",
    "FunctionProtocol": "PCIe",
    "FunctionType": "Physical"
}

字段说明：

这些字段会被 BMC 解析后展示在 Web UI 或通过 Redfish 接口对外提供。

步骤 4：验证结果 ​

配置完成后，可以在 BMC 中查看 PCIe 卡是否被正确识别。

# 查看 PCIe 卡信息
ipmcget -d v

如果一切正常，你应该能看到新添加的 PCIe 卡的信息，包括设备名称、厂商、型号等。

🔌 3.2 事件模拟 ​

什么是事件模拟？ ​

BMC 的一个重要职责是监控服务器的各种状态，当出现异常时及时发出告警。常见的事件类型包括：

• 温度告警：CPU 或环境温度过高
• 电压异常：电源电压超出正常范围
• 风扇故障：风扇转速过低或停止
• 设备故障：硬盘、网卡等设备出现故障

每个事件都会触发 BMC 的响应流程：记录日志（SEL）、更新传感器状态、发送告警通知（SNMP Trap、Redfish Event）、执行预设动作（调整风扇、自动关机）。

通过 QEMU 模拟这些事件，你可以验证 BMC 的告警机制是否正常工作，不用真的去制造硬件故障。

本节示例 ​

我们以 BCU1 VCC_12V0_2 电压传感器为例，演示如何手动触发一个电压告警事件。

步骤 1：查看 Web 告警列表 ​

先看看 BMC 的当前告警界面长什么样，了解一下告警信息的展示方式。

告警列表通常显示：

• 告警级别（Info/Warning/Critical）
• 告警时间
• 告警描述
• 告警来源（哪个传感器触发）

步骤 2：找到目标传感器的 UID ​

每个传感器在 BMC 系统中都有一个唯一的 UID（唯一标识符），用于精确定位该传感器。

通过 Web 界面导航到 BCU 板卡的传感器页面，找到 VCC_12V0_2 电压传感器的 UID。

这里的 UID 是该板卡的唯一标识符。

步骤 3：查看传感器当前状态 ​

使用 mdbctl 命令可以查看传感器的实时读数和配置信息。

# 查看电压传感器的当前值
mdbctl lsprop Scanner_12v2_010101

# 查看电源状态
mdbctl lsprop Scanner_PowerGood_010101

输出会显示传感器的各种属性，如上图中所示：

• Value：当前读数
• ClassName：名称

步骤 4：修改传感器数值触发告警 ​

现在到了关键步骤：手动修改传感器的数值，看看 BMC 是否会触发告警。

# 设置一个超出正常范围的值（触发告警）
mdbctl setprop set Scanner_12v2_010101 bmc.kepler.Scanner Value 3000

# 恢复正常值（清除告警）
mdbctl setprop set Scanner_12v2_010101 bmc.kepler.Scanner Value 2200

第一条命令将电压值设为 3000（单位通常是毫伏），这明显超出了 12V 电源的正常范围。BMC 检测到这个异常值后，应该会产生一条告警。

刷新 Web 界面的告警列表，你应该能看到新增的电压告警记录。

如果你想清除告警，执行第二条命令，将电压值恢复正常即可。

🔧 3.3 板卡适配 ​

什么是板卡适配？ ​

板卡适配是将新的硬件板卡（如网卡、RAID 卡、GPU 卡等）集成到 BMC 管理系统中，使其能够被正确识别、监控和管理。

通过 QEMU，你可以在没有真实硬件的情况下完成大部分适配工作，硬件到位后只需做少量验证。

核心原理：通过 mdbctl 命令修改板卡的加载方式和 ID，实现板卡的在线替换适配。

步骤 1：查看当前板卡信息 ​

首先执行以下命令，查看系统中当前的板卡信息：

ipmcget -d v

记录下需要替换的板卡 UID，后续步骤会用到。

步骤 2：执行板卡替换 ​

本节以 UID 为 00000001040302044504 的 IEU 板卡为例，演示如何将其替换为 UID 为 00000001040302044501 的板卡。

执行流程：

# 1. 查看板卡当前属性信息
mdbctl lsprop Connertor_D7a_010101

# 2. 将板卡设置为不在位状态
mdbctl setprop  set Scanner_D7a_010101 bmc.kepler.Scanner Value 0

# 3. 设置连接器识别模式
mdbctl setprop  set Connertor_D7a_010101 bmc.kepler.Connector IdentifyMode 2

# 4. 修改板卡 ID（替换为新的 UID）
mdbctl setprop set Connertor_D7a_010101 bmc.kepler.Connector Id "00000001040302044501"

# 5. 将板卡恢复为在位状态
mdbctl setprop set Scanner_D7a_010101 bmc.kepler.Scanner Value 1

说明：图中的内容是进入了 mdbctl 模式分开执行的命令，可以通过上述的命令直接执行，而不用进入 mdbctl 模式单独执行命令。 命令说明：

步骤 3：验证替换结果 ​

板卡替换完成后，再次执行以下命令验证结果：

ipmcget -d v

你应该能看到板卡的 UID 已经更新为新的值，板卡信息与目标板卡一致。

📚 附录：快速参考 ​

认证信息汇总 ​

所有接口使用统一的账号密码，方便记忆：

常用命令速查 ​

# SSH 连接
ssh -p 10022 Administrator@127.0.0.1

# 查看版本信息
ipmcget -d v

# 查看传感器
ipmcget -d sensorlist

# 查看 FRU 信息
ipmitool -I lanplus -H 127.0.0.1 -p 10623 -U Administrator -P Admin@90000 fru

# Redfish 查询系统信息
curl -k -u Administrator:Admin@90000 https://127.0.0.1:10443/redfish/v1/Systems/1

# D-Bus 查看资源协作接口
busctl --user tree bmc.kepler.<组件名>

# 修改传感器值
mdbctl setprop set <sensor> bmc.kepler.Scanner Value <值>