openUBMC 在线调试特性设计说明书

Copyright © 2025 openUBMC Community

您对"本文档"的复制，使用，修改及分发受木兰宽松许可证, 第2版协议(以下简称"MulanPSL2")的约束。 为了方便用户理解，您可以通过访问https://license.coscl.org.cn/MulanPSL2了解MulanPSL2的概要 (但不是替代)。 MulanPSL2的完整协议内容您可以访问如下网址获取：https://license.coscl.org.cn/MulanPSL2。

改版记录

目录

1.特性概述

1.1 目的

1.2范围

1.3特性需求列表

2.需求场景分析

2.1特性需求来源与价值概述

2.2特性场景分析

2.3特性影响分析

2.3.1硬件限制

2.3.2技术限制

2.3.3对License的影响分析

2.3.4对系统性能规格的影响分析

2.3.5对系统可靠性规格的影响分析

2.3.6对系统兼容性的影响分析

2.3.7与其他重大特性的交互性，冲突性的影响分析

2.4同类社区/商用软件实现方案分析

3.特性/功能实现原理(可分解出来多个Use Case)

3.1目标

3.2总体方案

4.Use Case一实现

4.1设计思路

4.2约束条件

4.3详细实现(从用户入口的模块级别或进程级别消息序列图)

4.4子系统间接口(主要覆盖模块接口定义)

4.5子系统详细设计

4.6DFX属性设计

4.6.1性能设计

4.6.2升级与扩容设计

4.6.3异常处理设计

4.6.4资源管理相关设计

4.6.5小型化设计

4.6.6可测性设计

4.6.7安全设计

4.7系统外部接口

4.8自测用例设计

5.Use Case二实现

6.可靠性&可用性设计

6.1冗余设计

6.2故障管理

6.3过载控制设计

6.4升级不中断业务

6.5人因差错设计

6.6故障预测预防设计

7.安全&隐私&韧性设计

7.1Low Level威胁分析及设计

7.1.12层数据流图

7.1.2业务场景及信任边界说明

7.1.3外部交互方分析

7.1.4数据流分析

7.1.5处理过程分析

7.1.6数据存储分析

7.1.7缺陷列表

7.2隐私风险分析与设计

7.2.1隐私风险预分析问卷

7.2.2隐私风险预分析总结

7.2.3个人数据列表

7.2.4XX需求设计

7.2.5YY需求设计

8.特性非功能性质量属性相关设计

8.1可测试性

8.2可服务性

8.3可演进性

8.4开放性

8.5兼容性

8.6可伸缩性/可扩展性

8.7 可维护性

8.8 资料

9.数据结构设计（可选）

10.参考资料清单

表目录

表1：特性需求列表
表2：特性场景分析
表3：同类社区/商用软件实现方案分析
表4：核心场景与规格目标
表5：保证新特性的自身性能
表6：异常处理设计
表7：功能测试
表8：性能测试
表9：异常与可靠性测试
表10：可服务性

图目录

图1：方案总体实现设计
图2：IDE实现在线调试序列图
图3：BMC Studio实现在线调试序列图
图4：可视化观测序列图

List of abbreviations 缩略语清单 ：

1.特性概述 ​

本特性旨在构建一个高度集成、自动化的BMC（基板管理控制器）在线开发与调试环境，以彻底革新传统低效的手工开发流程。该环境核心由 BMC Studio和 VScode 插件构成，后端依托 Qemu模拟的BMC运行环境。
特性通过打通代码编辑、部署、生效与验证的全链路，实现了代码/配置的自动同步、服务的自动重启以及数据的可视化观测。开发者在 IDE（VScode）或 BMC Studio 中修改代码或配置数据后，系统会自动将变更同步至 Qemu 仿真环境并触发相关组件热更新或重启，无需任何手动拷贝或命令操作。最终，开发者可通过 IDE 或 BMC Studio 的图形化界面，直观地观测资源协作接口的调用结果和数据库的数据变化，极大提升了开发调试的效率与体验。

简而言之，本特性将原本分散、手动的操作整合为一个无缝的自动化闭环，为BMC软件开发提供了“编码即生效，所见即所得”的现代化开发体验。

1.1目的 ​

当前BMC软件开发流程中存在诸多痛点，严重制约了开发效率与质量。本特性的引入旨在解决以下核心问题：

1. 提升开发效率：消除在多个工具之间频繁切换、手动执行命令（如拷贝、重启、查询）所产生的大量耗时操作，将开发者从重复性劳动中解放出来，专注于代码逻辑本身。
2. 加速反馈循环：将“修改-部署-验证”的周期从分钟级缩短至秒级。即时反馈机制允许开发者快速验证想法的正确性，显著减少因上下文切换和等待而导致的思维中断，提升开发流畅度。
3. 降低调试难度：提供图形化的数据观测界面，直观展示资源协作接口的总线消息以及数据库的表数据变化，解决了通过命令行查询数据晦涩难懂、操作繁琐的问题，降低了新人的上手门槛。
4. 保证环境一致性：通过 Qemu 模拟标准化的BMC硬件环境，避免了因物理硬件差异或状态污染导致的环境问题，确保开发、调试和测试阶段的环境一致性，减少“在我机器上是好的”这类问题

1.2范围 ​

本特性旨在服务基于 openUBMC 的所有BMC领域的开发者，包括但不限于核心功能开发者、系统定制者以及应用层开发者，旨在为他们提供一个统一的、高效的现代化开发体验。目标用户范围：

• BMC核心功能开发者：从事BMC固件基础服务（如 IPMI、Redfish、传感器管理、设备控制等）开发的人员。
• 平台与硬件适配开发者：为不同主板或硬件平台进行BMC适配和驱动开发的工程师。
• 上层应用开发者：在BMC基础上开发定制化功能的开发者。
• 开源项目贡献者：参与openUBMC相关开源项目的广大社区贡献者。

1.3特性需求列表 ​

2.需求场景分析 ​

2.1特性需求来源与价值概述 ​

需求来源 ​

本特性的构想直接源于BMC软件开发中长期存在的共性痛点。在传统的开发模式中，无论是资深的核心开发者还是新入社区的贡献者，都普遍面临以下挑战：

• 环境搭建复杂：新手需要花费大量时间学习如何配置BMC开发环境，高昂的入门门槛阻碍了社区成员的快速参与和贡献。
• 开发调试流程低效：代码修改后的“部署-重启-验证”循环完全依赖开发者手动完成。需要在SSH终端、代码编辑器等多个窗口间频繁切换，执行重复命令，整个过程繁琐、耗时且容易出错。
• 结果验证不直观：验证代码是否生效往往需要通过命令行手动查询数据库或抓取资源协作接口数据，数据显示不直观，分析效率低下，尤其不利于复杂逻辑的调试。

这些广泛存在的摩擦严重影响了开发者的专注度和生产力，构成了社区开发效率提升的主要瓶颈。本特性旨在通过工程自动化手段，系统性解决上述痛点，为整个社区提供一种更优的开发范式。

价值概述 ​

本特性的成功实施将为openUBMC开源社区带来以下核心价值：

• 极大提升开发效率：将开发者从重复性的手动操作中彻底解放出来，实现“代码保存即生效”的极速调试体验。这将显著缩短开发反馈循环，使开发者能更专注于核心逻辑与创新，而非运维操作。
• 大幅降低参与门槛：提供一站式的标准化开发环境，新贡献者无需深究环境配置细节即可快速上手并开始编码，有效吸引了更广泛的开发者参与，促进了社区的繁荣与活力。
• 增强调试深度与透明度：提供可视化的数据观测能力，将关键的内部状态（如资源协作接口数据、数据库变更）透明地呈现给开发者，使调试过程从“黑盒”走向“白盒”，极大地提升了问题定位和解决的效率。
• 促进协作与标准化：为所有社区开发者提供统一、一致的开发工具链和环境，减少了因环境差异导致的问题，使得代码共享、协作评审和问题复现变得更加顺畅可靠。
• 推动开发模式现代化：本特性是向现代化、自动化开发工作流迈出的关键一步，提升了整个社区的工程能力。

总而言之，本特性不仅是一个工具改进，更是一次开发体验的革新。它通过解决基础效率问题，赋能于每一位社区成员，从而加速整个openUBMC生态的技术迭代和创新进程。

2.2特性场景分析 ​

2.3特性影响分析 ​

本特性在整体开发体系中扮演着 “开发-调试层” 的角色。它并非BMC产品固件本身的一部分，而是位于开发工具链与Qemu仿真环境之间的一套自动化与可视化套件。其核心位置如下图所示：

+---------------------------------+
|          开发工具链             | <--> (构建接口 Bingo)
|   (BMC Studio / VScode)        |
+---------------------------------+
         | (控制与数据接口) 
         |  [自动化同步] [观测请求]
         v
+---------------------------------+
|       本特性 (BMC Studio)        | 
|   +---------------------------+ |
|   |       同步与控制引擎       | | 
|   +---------------------------+ |
|   +---------------------------+ |
|   |       数据观测服务         | | <-| (数据接口)
|   +---------------------------+ |    |
+---------------------------------+    |
         | (部署与命令接口)            | (数据采集接口)
         v                             |
+---------------------------------+    |
|       Qemu BMC仿真环境          |    |
|   +---------------------------+ |    |
|   |                           | |----
|   |     - 运行中的BMC服务      | |
|   |     - 资源协作接口(DBus)   | |
|   |     - 数据库(SQLite)       | |
|   +---------------------------+ |
+---------------------------------+

2.3.1硬件限制 ​

2.3.2技术限制 ​

操作系统：ubuntu24

编程语言：仓颉、python、C、TS

2.3.3对License的影响分析 ​

不涉及

2.3.4对系统性能规格的影响分析 ​

不涉及

2.3.5对系统可靠性规格的影响分析 ​

不涉及

2.3.6对系统兼容性的影响分析 ​

不涉及

2.3.7与其他重大特性的交互性，冲突性的影响分析 ​

见特性影响分析章节

2.4同类社区/商用软件实现方案分析 ​

在OpenBMC等主流开源社区及主要商用BMC解决方案中，基于Qemu的在线一体化调试能力目前尚未成为标准实践。社区与厂商现有的技术投入更多地聚焦于自动化测试框架的构建、管理接口（如RedFish、DBus）的标准化，以及内核级调试能力（如KGDB）的增强。以下为在线调试模式与传统手动调试方式的对比分析：

3.特性/功能实现原理 ​

3.1目标 ​

本特性的核心目标是构建一个高度自动化、可视化的BMC开发调试环境，彻底革新传统低效的手工流程。具体目标如下：

1. 核心场景与规格目标

2. 量化性能目标

• 效率提升：将“修改-部署-验证”的循环周期从传统方式的分钟级（>3分钟） 缩短至秒级（<10秒）。
• 操作简化：将一次完整的代码生效流程所涉及的手动命令数从10条以上减少至0（仅需保存文件）。
• 资源开销：特性本身在主机侧的资源占用（CPU/内存）应低于10%，且不应显著影响Qemu虚拟机的正常运行性能。

3. 整体体验目标

• 一体化：在BMC开发工具或VScode内形成“编码 -> 同步 -> 重启 -> 观测”的无缝闭环体验，消除工具间切换的割裂感。
• 开箱即用：所有功能无需复杂配置即可使用，极大降低开发者的前期准备成本。
• 社区友好：该特性设计应对社区所有开发者开放，不依赖特定内部系统或硬件，促进协作与贡献。

3.2总体方案 ​

下图展示了该在线调试特性的整体系统架构及各组件间的交互关系：

该架构采用客户端-服务器模型，其中：

• 客户端：位于开发主机上，包括BMC Studio可视化工具、VScode插件，负责提供用户界面、接收用户指令、呈现数据。
• 服务端：位于Qemu BMC虚拟机内，包括BMC系统本身，负责执行命令、提供服务、暴露数据。
• 中间层：调试控制台、同步与控制引擎、数据观测服务是架构的核心，作为网关连接客户端与服务端，封装了所有与Qemu的交互细节，向上提供统一的API。

4.Use Case一实现 ​

4.1设计思路 ​

系统应作为一个高效、可靠且透明的“智能代理”，在用户（Actor）触发动作后，自动完成一系列复杂的中后台操作，并将最终结果清晰、及时地反馈给用户。
总体交互原则

1. 即时反馈 ：任何由Actor触发的操作，系统都必须立即提供视觉或状态反馈（如按钮变为loading状态、弹出“同步中...”提示），避免用户因等待而产生“是否生效”的疑虑。
2. 状态可视 ：将系统的后台状态（如“连接Qemu”、“同步文件”、“重启服务”）主动地、可视化地告知用户，让整个流程对用户透明。
3. 优雅降级：当自动化流程失败时，不仅需要报错，还应尽可能提供可操作的解决方案（如“重启失败，请手动执行 systemctl restart xyz”），将控制权交还给用户。
4. 最小打扰 ：自动化流程不应打断开发者的主要工作流（编码）。成功的操作应以非模态提示（如右下角Toast）通知，而非弹窗阻塞。

4.2约束条件 ​

必须满足以下所有条件，该特性方可正常使用：

1. 环境依赖：

• 必须运行于 Qemu 仿真环境中，严禁在生产环境或物理BMC硬件上开启。部分高权限操作可能对物理设备造成不可预知的影响。
• Qemu 虚拟机必须已正确配置网络连接，确保开发主机与虚拟机之间可通过 SSH 协议通信。
• Qemu 虚拟机内的 BMC 系统必须包含 SSH 服务端, 仿真镜像包须内置 busybox 调试工具。

本特性在以下场景中可能无法正常工作或不被建议使用：

• 硬件相关调试：所有依赖特定硬件时序、寄存器操作或未完美仿真之外设的驱动开发与调试，本特性无法替代物理硬件调试环境，结果仅供参考。
• 性能剖析：此功能旨在进行功能正确性调试，不适合用于进行精细的性能分析（如函数调用耗时、CPU热点分析），因为 Qemu 仿真无法反映真实的硬件性能指标。
• 并发压力测试：自动化同步重启机制并非为模拟高并发场景而设计，在进行压力或并发测试时，建议关闭自动同步功能，以免干扰测试过程。

4.3详细实现 ​

4.3.1 通过IDE实现在线调试Use Case实现过程 ​

• 开发者在 VSCode 中编写 Lua 脚本后，点击一键同步，BMC Studio 自动识别代码所属组件，将其精准部署至 Qemu 环境中的对应路径，并智能重启关联服务，使变更即时生效。
• 开发者在 VSCode 中编写 C/C++ 代码后，点击一键同步，BMC Studio 自动判定组件依赖，完成组件或动态库的构建，将生成产物同步至 Qemu 环境目标位置，并自动重启受影响服务，实现代码快速部署与验证。
• 开发者在 VSCode 中修改 CSR 或接口映射文件后，点击一键同步，BMC Studio 自动分析配置所属组件，将更新后的配置文件同步至 Qemu 环境指定位置，并智能触发相关服务重启，确保配置动态生效。

4.3.2 通过BMC Studio实现在线调试Use Case实现过程 ​

• 开发者在 BMC Studio 可视化页面修改CSR配置后，点击一键同步， BMC Studio 自动分析配置所属组件，将更新后的配置文件同步至 Qemu 环境指定位置，并智能触发相关服务重启，确保配置动态生效。
• 开发者在 BMC Studio 的可视化界面中修改板卡仿真配置数据后，BMC Studio 将自动把更新后的数据同步至 Qemu 仿真环境；Qemu 会实时监测数据变化并立即重新加载，使新的仿真配置动态生效。

4.3.3 可视化观测Use Case实现过程 ​

• 开发者在 VSCode 插件中查看资源协作接口或数据库数据时，插件将请求转发至 BMC Studio，由 Studio 向 Qemu 环境发起数据查询，最终将结果返回到 VSCode 插件界面并展示给开发者。
• 当开发者在 BMC Studio 工具界面中查看资源协作接口或数据库数据时，Studio 直接向 Qemu 环境请求数据，并在工具内完成结果的解析与可视化呈现。

4.4子系统间接口(主要覆盖模块接口定义) ​

在这个章节只要说本次修改涉及哪个 .h 的哪个接口的修改，大致的修改内容简述下即可。

4.5子系统详细设计 ​

详细描述各模块的修改点。

4.6DFX属性设计 ​

4.6.1性能设计 ​

对现有特性的性能影响 ​

在正确部署和使用的场景下，该特性对现有Qemu中运行的BMC仿真环境的核心功能性能影响微乎其微，几乎可以忽略不计。原因如下：

• 隔离性：该特性的核心逻辑（同步引擎、数据服务）运行在开发主机上，而非Qemu虚拟机内部。其主要资源消耗（CPU、内存）体现在开发者的物理机或工作站上，与Qemu虚拟机本身的计算资源是隔离的。
• 被动性：Qemu内部的BMC系统只是在接收文件、执行重启命令或响应数据查询时才会与主机交互。在非调试时段，BMC系统处于完全独立、不受干扰的运行状态。
• 轻量级操作：

1. 文件同步：是基于SSH协议，是现代操作系统和虚拟化技术优化后的常规操作。
2. 服务重启：与开发者手动在SSH中执行 systemctl restart 或 busctl 命令完全一致，没有引入额外的开销。
3. 数据查询：与管理员手动使用 busctl、sqlite3 等命令查询系统的开销一致。

如何保证新特性的自身性能 ​

为了保证新特性本身的高效和可用，设计上需要采取以下关键措施：

4.6.2升级与扩容设计 ​

不涉及

4.6.3异常处理设计 ​

以下是该特性可能遇到的异常场景、规避方案:

保证影响最小的核心思想是：“自动化优先，手动托底”。

• 在一切顺利时，系统默默无闻地完成工作，几乎感觉不到它的存在。
• 在出现异常时，系统能精准识别问题，以最不打扰的方式告知用户问题的本质和解决方案，将控制权交还给用户，而不是让用户陷入迷茫。

4.6.4资源管理相关设计 ​

宿主机要求：

• 内存：16G
• CPU：8核
• 硬盘：200G

4.6.5小型化设计 ​

不涉及

4.6.6可测性设计 ​

该特性具有良好的可测试性，原因如下：

1. 模块化设计：系统被清晰地分解为同步引擎、数据服务、前端插件等模块，每个模块可以独立进行单元测试和集成测试。
2. 环境隔离：核心测试依赖于Qemu仿真环境，该环境可以轻松地快速创建、销毁和回滚到快照，保证每次测试都在一个纯净、一致的状态下开始。
3. 状态可观测：特性本身的目的就是提供观测能力，这反过来又为测试提供了便利。测试脚本可以像用户一样，通过查询DBus和数据库来验证操作结果。

4.6.7安全设计 ​

不涉及

4.7系统外部接口 ​

不涉及

4.8自测用例设计 ​

描述自测用例是如何设计的，如何测试保证功能符合预期

5.Use Case二实现 ​

同第 4 章

6.可靠性&可用性设计 ​

6.1冗余设计 ​

不涉及

6.2故障管理 ​

不涉及

6.3过载控制设计 ​

不涉及

6.4升级不中断业务 ​

不涉及

6.5人因差错设计 ​

不涉及

6.6故障预测预防设计 ​

不涉及

7.安全&隐私&韧性设计 ​

不涉及

7.1Low Level威胁分析及设计 ​

7.1.12层数据流图 ​

不涉及

7.1.2业务场景及信任边界说明 ​

不涉及

7.1.3外部交互方分析 ​

不涉及

7.1.4数据流分析 ​

不涉及

7.1.5处理过程分析 ​

不涉及

7.1.6数据存储分析 ​

不涉及

7.1.7缺陷列表 ​

不涉及

7.2隐私风险分析与设计 ​

不涉及

7.2.1隐私风险预分析问卷 ​

不涉及

7.2.2隐私风险预分析总结 ​

不涉及

7.2.3个人数据列表 ​

不涉及

7.2.4XX需求设计 ​

不涉及

7.2.5YY需求设计 ​

8.特性非功能性质量属性相关设计 ​

8.1可测试性 ​

功能测试 ​

目标：验证每个功能点是否按照需求正常工作。

性能测试 ​

目标：验证特性满足性能指标，且不会引入不可接受的延迟。

异常与可靠性测试 ​

目标：验证系统在异常情况下能优雅降级，并能从错误中恢复。

8.2可服务性 ​

为确保用户能充分理解和使用本特性，将提供一套完整的文档：

8.3可演进性 ​

VScode插件和BMC Studio UI作为独立的前端，只负责UI渲染和用户指令发起。所有核心业务逻辑（同步、控制、数据采集）放在后端的调试控制台、同步引擎和数据服务中。未来若要支持新的IDE或新的UI框架，只需为新平台开发一个轻量级前端适配层，调用现有的后端API即可，后端核心逻辑无需任何改动。

8.4开放性 ​

不涉及

8.5兼容性 ​

不涉及

8.6可伸缩性/可扩展性 ​

8.7可维护性 ​

不涉及

8.8资料 ​

• openUBMC 在线调试特性设计说明书
• openUBMC 在线调试特性详细设计说明书

9.数据结构设计 ​

不涉及

10.参考资料清单 ​