openUBMC xx特性设计说明书

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.参考资料清单

表目录

表X：特性场景相关性分析

表X：特性需求列表

图目录

图X：方案总体实现原理图

图X：样图：处理流程示意图

List of abbreviations 缩略语清单 ：

1.特性概述 ​

【关键内容】 介绍关键特性定位，对于特性面向的使用客户和市场范围，基于需求分析明确说明特性设计要达成的目的。 对本方案的概况介绍。简述特性背景信息，并说明本文档所包含的主要内容和适用范围等。

【参考输入】《系统需求说明书》

【参考说明】

本特性作为面向互联网市场产品，主要面向国内头部互联网公司提供硬盘带外管理能力。产品集成到openUBMC固件当中，满足客户硬盘管理运维需求。 互联网厂商要求，OCP卡的x16资源需要从2个CPU上出，每个CPU出一个x8组成一个x16，OCP卡或者PCIe标卡的资源应该归属2个CPU。当前BMC只支持1个CPU出PCIe资源，不满足实际情况。

1.1目的 ​

【关键内容】

本文档以xxx文档/issue为分析指导，对xxx模块或者xxx特性的功能进行设计，明确数据结构和主要处理过程，作为后续软件开发人员、测试人员的指导。 本文档作为openUBMC PCIe资源支持multihost特性需求的分析指导，对PCIe资源支持multihost功能进行设计，明确主要处理过程，作为后续软件开发人员、测试人员的指导。

注意： 后续章节基于实际情况进行灵活裁剪

1.2范围 ​

简述特性主要包含哪些功能点 【关键内容】 描述特性背景及适用范围

表1 表X：PCIe资源支持multihost特性场景相关性分析

1.3特性需求列表 ​

表X：特性需求列表

需求情况，简要介绍特性，解决客户的xxx场景诉求

表1 表X 特性需求列表

2.需求场景分析 ​

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

描述该特性需求来源或背景，比如： XXX 使用场景、 XXX 内部优化等。描述该特性对用户带来什么具体价值，如果没有该特性，对用户使用或者竞争力带来什么损失。 互联网厂商要求，OCP卡的x16资源需要从2个CPU上出，每个CPU出一个x8组成一个x16。满足厂商多样化定制需求。

2.2特性场景分析 ​

描述该特性的业务使用场景

内容包括：

1）场景触发条件及对象：什么角色/工具/接口等在什么具体情况下使用该特性，使用对象技能如何？

2）描述该特性主要有哪些用户应用场景、子场景及关键任务操作。_

【关键内容】

1. 使用者
2. 时间，频率
3. 关键任务

2.3特性影响分析 ​

描述该特性在整个系统中的位置及周边接口。描述该特性有哪些关键约束或特性冲突。

与其他需求及特性的交互分析：bios上报两个设备BDF给pcie_device，影响原有的加载流程

平台差异性分析：不涉及

兼容性分析：BIOS会调用新的IPMI命令来上报两个设备BDF，要保证原有的流程不受影响

约束及限制：不涉及

2.3.1硬件限制 ​

简单描述承载子系统的硬件约束，主频，内存，线程数及其它对软件有影响的硬件特点

如有，给出规避方案。 不涉及

2.3.2技术限制 ​

操作系统：

编程语言：

如有，给出规避方案。 不涉及

2.3.3对License的影响分析 ​

明确对特性所涉及技术的合规性、所引入的第三方开源软件的 license 的影响分析。 不涉及

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

明确系统容量规格，基于特性运行资源的设定条件。比如至少需多少 G 内存才能使用此特性 未新增常驻轮询，无影响

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

特性对于可靠性指标的假设和约束，例如在预设的条件下要支持 x 个 9 的目标等。 不涉及

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

是否会影响数据库的前向兼容，也就是用户在数据库旧版本使用的特性在新版本上是否依然可以使用。 BIOS旧的命令逐步废弃，要保证旧的IPMI命令仍然可用，避免出现BIOS与BMC的配套问题

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

分析包括周边工具、其他内核特性的交互和影响 BIOS会调用新的IPMI命令来上报两个设备BDF，要保证原有的流程不受影响

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

该特性在同类社区 / 商用软件上的实现机制，对比分析，体现优劣性对比 不涉及

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

3.1目标 ​

该章节主要描述特性在什么场景下要实现什么规格、达到什么目标

3.2总体方案 ​

该章节主要阐述该特性的详细设计，包括选择什么硬件、使用什么算法、架构如何布局等

从整体流程上，根据场景分析和系统分解，将特性实现分为多个关键场景（ Use Case ）

定义对接的原则

方案整体架构图

示意图：

4.Use Case一实现 ​

4.1设计思路 ​

说明 Use Case 实现的思路 原上报PCIe卡设备BDF的IPMI接口基于槽位顺序上报，本身不带槽位信息，multihost场景下一个槽位有多组设备BDF，需要BIOS调用新的IPMI命令，支持同一槽位上报多组设备BDF

4.2约束条件 ​

描述前提条件，即该功能开启的限制条件，比如会导致系统 xx 功能不可用，比如在 xx 内存限制下才能开启等。 BIOS使用新版本

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

本章节具体描述 Use Case 实现过程。使用时序图、流程图描述各模块间的交互过程。

同时用简短文字说明时序图、流程图的各个模块分配需求的变化，尽量使用结构化的语言。

时序图：

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

在这个章节只要说本次修改涉及哪个 .h 的哪个接口的修改，大致的修改内容简述下即可。 见新增ipmi命令支持上报PCIeCard/PCIeDisk/OCPCard的设备BDF

4.5子系统详细设计 ​

详细描述各模块的修改点。 1、BIOS通过新的IPMI命令上报同一槽位的两组设备BDF信息 2、pcie_device组件接收两组设备BDF信息，通过其中一组查询四元组信息，把csr加载起来。注意不能重复加载

4.6DFX属性设计 ​

4.6.1性能设计 ​

特性是否影响已有的相关性能指标，是否会影响现有特性的性能，如何保证新特性的性能 不涉及

4.6.2升级与扩容设计 ​

特性是否会影响到升级和扩容

_升级设计原则包括: _

1. _涉及系统表修改的特性，必须设计系统表升级脚本和回滚脚本，以及版本号控制
2. _对于涉及修改持久化数据（如日志）的特性，必须考虑新老版本共存时的兼容性场景，必要情况下，需要增加版本号以进行控制
3. _对于涉及修改执行态数据格式（如syscache结构）的特性，必须考虑新老版本共存时的兼容性场景，必要情况下，需要增加版本号以进行控制
4. _涉及升级工具gs_upgradectl的修改，设计需要考虑灰度升级、回滚、再升级和升级提交等内部逻辑
5. _涉及集群管理工具(例如om或cm)的公共函数修改，设计需要考虑灰度升级、回滚、再升级和升级提交等内部逻辑 不涉及

4.6.3异常处理设计 ​

有哪些异常场景，是否有规避方案，怎么提示用户，如何保证用户业务影响最小 不涉及

4.6.4资源管理相关设计 ​

是否占用额外的内存、磁盘 I/O 、网络 I/O 等资源，资源占用规格是什么，如果资源超出环境限制后，是否有处置措施 不涉及

4.6.5小型化设计 ​

请说明特性是否会影响小型化版本的规格（内存使用、安装包大小、 CPU 占用等），如果影响，是否有调整优化手段或者使用宏隔离。 不涉及

4.6.6可测性设计 ​

特性是否具备可测试性，给出测试应该涵盖的功能、性能、安全、可靠性等方面，涵盖边界值、异常场景等。 不涉及

4.6.7安全设计 ​

有哪些会影响数据库或者 OS 安全的地方，比如用户权限管理、秘钥管理、网络协议、外部攻击等。 要求此命令限制只能带内发送

4.7系统外部接口 ​

是否会影响到系统外部接口，包括 guc 参数、工具使用方式、 SQL 语法、网络协议、系统表视图函数、驱动（ JDBC/ODBC ）等 不涉及

4.8自测用例设计 ​

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

5.Use Case二实现 ​

5.1设计思路 ​

网卡的rootBDF可通过Set FDM Info这条IPMI命令上报。此命令会上报root BDF以及对应SecBus和SubBus，通过判断设备BDF是否落在[SecBus, SubBus]区间可以反推OCP卡的root BDF。将匹配到的两组root BDF设置到PCIeDevice对象上，并同步给NetworkAdapter对象

5.2约束条件 ​

不涉及

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

本章节具体描述 Use Case 实现过程。使用时序图、流程图描述各模块间的交互过程。

同时用简短文字说明时序图、流程图的各个模块分配需求的变化，尽量使用结构化的语言。

时序图：

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

沿用当前已有的Set FDM Info接口

5.5子系统详细设计 ​

通过判断设备BDF是否落在[SecBus, SubBus]区间获取OCP卡的root BDF，将匹配到的两组root BDF设置到PCIeDevice对象上

5.6DFX属性设计 ​

5.6.1性能设计 ​

不涉及

5.6.2升级与扩容设计 ​

不涉及

5.6.3异常处理设计 ​

不涉及

5.6.4资源管理相关设计 ​

不涉及

5.6.5小型化设计 ​

不涉及

5.6.6可测性设计 ​

不涉及

5.6.7安全设计 ​

不涉及

5.7系统外部接口 ​

不涉及

5.8自测用例设计 ​

不涉及

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

本章不涉及

6.1冗余设计 ​

特性设计考虑的冗余主要是系统采用了冗余设计，特性需要考虑镜像备份、配置参数备份和主备冗余系统之间进行数据同步等信息。

特性设计时，需要给出备份的关键配置参数清单，主备冗余系统之间进行数据同步时间 / 策略和关键数据清单，主备切换时数据核查机制 / 脏数据处理策略、备份恢复策略等。

对于镜像式备份，如快照 /checkpoint 机制，需要给出备份周期、数据核查机制 / 脏数据处理策略、恢复策略等，对系统性能有明显影响的特性，需要给出设计约束条件。

6.2故障管理 ​

故障管理包括故障检测、故障隔离、故障定位、故障恢复和相互关联的设计。

特性的故障管理，主要是特性自身的故障检测、告警 / 日志设计、故障恢复以及故障接口设计。

故障管理通常的设计原则包括：

1. 故障全面快速检测通常考虑检测范围、备用检测、检测速度、检测影响；
2. 控制失效影响范围通常考虑多平面、多粒度、隔离单位等隔离域划分；
3. 故障快速恢复通常考虑自动恢复、优先恢复、分级复位、无耦合恢复、分层保护等策略。

故障管理常见的设计模式包括 RollBack 模式、故障 Bypass 、断路器模式、隔离仓模式等。

6.3过载控制设计 ​

特性的过载控制设计需要考虑特性内处理业务的流量检测、检测位置和业务丢弃位置、业务丢弃时响应的业务消息信息，以及与统一的过载控制机制之间的调用、被调用关系、接口。

特性内部简单的过载控制机制通常采用限速的方式，需要考虑限速的位置、默认限速值、日志告警等信息。

过载控制通常的设计原则包括动态限流、弹性扩缩容、先负载均衡后流控、尽早控制、优先级保障、优雅降级设计等：

1. 尽早控制：系统过载时，应尽可能在业务流程处理前端或业务处理较早的处理模块上控制业务接入，避免中间控制带来不必要的性能消耗；
2. 优先级保障：系统过载时保证高优先级的业务能够优先获得资源，优先得到处理，从而保证社会效益最大化；
3. 优雅降级设计：非核心业务降级、核心功能放通、体验降级等。

6.4升级不中断业务 ​

特性内部的升级不中断业务，主要考虑特性在不同软件版本的消息兼容、配置数据格式兼容、接口兼容、与周边特性的相互依赖，以及升级失败时的快速回退处理过程。

6.5人因差错设计 ​

特性的人因差错主要考虑特性涉及的命令、操作、配置文件 / 数据等人机接口的错误防护，通常考虑如下几个方面：

1. 删除、破坏性修改需要提供高危提示以及二次确认，页面焦点默认"取消"。用户可见接口（ cli 以及 web 页面）都需要考虑，包括开源组件提供的命令接口；
2. 对重启节点操作需要提前检查是否影响客户 VM 运行，给出明确提示建议操作；
3. 所有高危操作需要记录审计日志；
4. 预防配置错误、预防硬件误操作、操作执行前的系统检查和操作错误后的快速回退。

人因差错通常的设计原则包括：

1. 角色约束：通过权限控制设计预防对不同角色的配置范围进行约束，避免越权配置导致错误；
2. 配置校验：通过配置生效机制设计确保在配置生效前进行必要的校验，避免错误配置生效；
3. 备份恢复：通过配置数据备份与恢复设计确保在出现配置错误时能够快速恢复到正确的配置数据状态。

6.6故障预测预防设计 ​

特性应配合系统故障预测预防能力提供相关的数据采集和统计接口。比如磁盘空间检测等。

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

不涉及的需要说明原因或者简要说明存在的风险(通常低风险且无对应消减建议的可不写当前章节) 硬件管理能力，未新增暴露面，本章不涉及

7.1Low Level威胁分析及设计 ​

7.1.12层数据流图 ​

Low level数据流图（2层数据流图）主要绘制具体的业务特性中数据的交互过程，该层数据流图需要能够描述清楚整个业务的交互过程，若涉及开源软件，需将开源软件作为产品的一部分进行整体的Low Level威胁分析。

数据流图元素及说明如下表所示：

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

针对数据流图，描述业务场景，描述数据流图中主要元素在业务场景中的作用；

对信任边界进行说明

7.1.3外部交互方分析 ​

针对数据流图中外部交互方进行威胁分析，外部交互方需要分析仿冒和抵赖两种威胁

7.1.4数据流分析 ​

针对数据流图中的数据流元素进行威胁分析，外部交互方需要分析篡改、消息泄漏、拒绝服务三种威胁

根据威胁分析结果，筛选出 XXX （如操作系统）安全方面的不可接受的风险，风险对应的规避措施应作为需求进行分析。

7.1.5处理过程分析 ​

针对数据流图中的数据流元素进行威胁分析，处理过程需要分析仿冒、抵赖、篡改、消息泄漏、拒绝服务，权限提升六种威胁

7.1.6数据存储分析 ​

针对数据流图中的数据流元素进行威胁分析，数据存储需要分析抵赖(特定情况下分析)、篡改、消息泄漏、拒绝服务四种威胁

7.1.7缺陷列表 ​

7.2隐私风险分析与设计 ​

本章目的在于帮助产品在做Low Level威胁分析前，分析当前系统是否需要做隐私风险分析。

7.2.1隐私风险预分析问卷 ​

7.2.2隐私风险预分析总结 ​

总结共分为以下情况：

1. 当前版本不涉及个人数据收集，因此该版本无需做隐私风险分析。

2. 当前版本需要做隐私风险分析。列出需要做隐私风险分析的新增特性（如 XX_ 特性）。同时刷新个人数据列表。_

本章描述所有隐私保护需求的设计，主要关注于个人数据的收集、使用、转移、存储和销毁五个阶段。

7.2.3个人数据列表 ​

需详细描述收集或处理个人数据的场景、个人数据类型、处理方法、收集目的、个人数据的保护措施以及数据存留期

7.2.4XX需求设计 ​

7.2.4.1需求说明

为满足相关的法律要求，涉及收集个人数据的系统应向用户提供法务审核后的符合系统实际情况并符合法律要求的隐私声明，并在必要时需获得用户明示同意。

7.2.4.2需求设计

1. 用户在注册时和产品升级为新版本会向用户提供隐私声明，得到用户明示同意后才可以继续注册流程和升级流程：

2. 客户端提供再次查看隐私声明功能，在该界面中会显示用户何时同意隐私声明。

7.2.5YY需求设计 ​

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

8.1可测试性 ​

重点从特性在测试的方向和规格上展开描述，说明在测试人员测试时应该测哪些方面，需要注意哪些边界值、异常值、异常场景。 从北向接口观察网卡、PCIe卡的资源归属以及BDF信息，可与OS内的PCIe信息进行对照

8.2可服务性 ​

对特性提供丰富的可维护可服务的措施，提供对特性的使用、维护、问题处理等的完整资料说明。 不涉及

8.3可演进性 ​

重点从特性架构、功能的可演进性上展开描述。 本特性落地后，可考虑替代原先PCIe卡root BDF的获取方法

8.4开放性 ​

重点描述特性的对外接口开放性，包括接口的规范性，比如符合 SQL 2011 标准。 不涉及

8.5兼容性 ​

重点描述特性是否会影响系统的前向兼容性，即旧功能在升级新版本之后是否可使用，使用行为是否和旧版本保持一致。 BMC需要保留旧的IPMI命令实现，保证与旧BIOS兼容

8.6可伸缩性/可扩展性 ​

有效满足系统容量变化的要求，包括数据库节点的扩缩容、数据库服务器本身的扩缩容。 不涉及

8.7可维护性 ​

重点从特性的可维护性展开描述，比如诊断视图、 log 打印等。 不涉及

8.8资料 ​

参考下表，评估特性会涉及到的各类资料的修改点，并说明具体修改点。

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

本章节完成数据库结构的设计（数据库系统表结构，可以使用 Power Designer 完成），可选章节。 不涉及

10.参考资料清单 ​

无