openUBMC NPU管理下沉设备树特性设计说明书 ​

Copyright © 2026 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.4 同类社区/商用软件实现方案分析

3. 特性/功能实现原理 3.1 目标 3.2 总体方案

4. Use Case一实现：AO区管理下沉（I3C通道） 4.1 设计思路 4.2 约束条件 4.3 详细实现 4.4 子系统间接口 4.5 子系统详细设计 4.6 DFX属性设计 4.7 系统外部接口 4.8 自测用例设计

5. Use Case二实现：非AO区管理下沉（IPMB通道） 5.1 设计思路 5.2 详细实现 5.3 并行管理子服务的演进 5.4 自测用例

6. Use Case三实现：按硬件通道并行管理 6.1 设计思路 6.2 线程绑定方案 6.3 异常与可靠性 6.4 自测用例

7. 可靠性&可用性设计

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

9. 数据结构设计

10. 参考资料清单

表目录

表1：特性场景相关性分析 表2：特性需求列表 表3：新旧SR/BMC兼容矩阵

图目录

图1：NPU管理框图 图2：新SR搭配新BMC 图3：新SR搭配旧BMC 图4：旧SR搭配新/旧BMC 图5：断代更新路径

缩略语清单：

1.特性概述 ​

NPU（AI加速模组）是AI服务器中数量最多、管理最复杂的部件之一。以Atlas 950 SuperPoD为例，单机配置8个NPU，BMC分别通过8路I3C和8路IPMB硬件通道进行管理。当前openUBMC对NPU的管理逻辑集中在compute等上层组件中：组件通过fork协程方式串行下发管理任务，同一时间实际只有单个线程在执行，硬件多通道的并行能力没有被利用；同时管理逻辑与CSR 1.0资源树对象强耦合，无法复用CSR 2.0设备树的标准化南向框架。

本特性将NPU管理能力从compute/general_hardware/network_adapter等上层组件下沉到CSR 2.0设备树（南向驱动），在设备树NPU对象上直接实现AO区与非AO区的日志收集、固件升级、告警监控、信息获取能力，并将并行管理拓扑从PSR配置下发改为设备树对象属性驱动，在兼容存量SR与旧版本BMC的前提下，提升多NPU场景的管理效率，并为后续断代更新（消亡compute等上层管理组件）奠定基础。

1.1目的 ​

本文档以openUBMC需求基线中NPU管理相关需求及社区评审方案（https://discuss.openubmc.cn/t/topic/6221）为输入，对"NPU管理下沉设备树"特性进行设计，明确总体架构、兼容策略、各Use Case的模块改造点和设备树接口定义，作为后续开发、测试和北向接口适配的指导。

1.2范围 ​

本特性覆盖NPU模组按硬件通道划分的两部分管理能力，以及多通道并行管理的线程模型：

• AO区（I3C通道）：邮箱机制、日志收集、NPU/VRD固件升级、告警监控
• 非AO区（IPMB通道）：BLACKBOX/DEVICE日志收集，NPU、NPU端口、NPU网口/光模块的信息获取
• 并行管理：设备树NPU对象新增ThreadGroupId属性，南向上报拓扑、compute下发分组，南向按通道并行调度
• 兼容：新旧SR与新旧BMC的四种组合共存，以及断代更新路径

不包含：NPU卡（MCU侧）管理、HCCS/QL CDR等链路监控需求的下沉（后续版本规划）；AO区告警SR配置的重写（当前版本保留旧配置）。

表1 特性场景相关性分析

1.3特性需求列表 ​

本特性对应《openUBMC需求规格基线》部件管理特性中NPU模组管理相关需求。其中"支持按硬件通道并行管理NPU"原规划26.06上车（NPUConfig私有对象已通过社区评审），其设备树下沉实现随本特性在openUBMC 26.12落地。

表2 特性需求列表

2.需求场景分析 ​

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

openUBMC南向正从CSR 1.0资源树向CSR 2.0设备树演进，部件管理逻辑需要逐步下沉到设备树对象，最终消亡compute等上层管理组件。在已有部件下沉实践的基础上，NPU作为部件管理中规模最大、场景最全的部件（涉及信息获取、日志收集、固件升级、多通道并行调度等完整场景），其下沉可以进一步验证和完善设备树的升级、日志、并行调度框架，为后续部件下沉提供参考。

价值：多NPU场景下日志收集/升级/轮询耗时随通道数近似线性下降；管理逻辑下沉后北向与资源模型解耦，支持存量SR与设备树SR共存，平滑断代。

2.2特性场景分析 ​

2.3特性影响分析 ​

2.3.1硬件限制 ​

• 通道数与机型相关：Atlas 950 SuperPoD为8路I3C+8路IPMB，其他机型通道数不同，线程/任务数必须由拓扑配置动态决定，不能硬编码。
• I3C为单主多从总线，从机（BMC侧）无法主动触发通信，必须依赖AO区主机写数据后触发中断寄存器，即邮箱机制。
• BMC侧CPU核数、内存有限，线程池规模需与通道数匹配并受控，不能按NPU数量无限制创建线程。

2.3.2技术限制 ​

• 操作系统：BMC嵌入式Linux；编程语言：Lua（compute/general_hardware/network_adapter组件、南向插件）、C++（设备树框架）。
• 依赖CSR 2.0设备树框架先支持I3C总线配置（CSR 2.0 I3C配置）以及升级、日志采集接口的注册能力。
• 规避：设备树框架能力不满足的接口（bmc.dev.Upgrade、bmc.dev.NPU.LogCollection、bmc.dev.NPU.Oem）本特性同步新增定义。

2.3.3对License的影响分析 ​

本特性为openUBMC自有代码重构与新增，不引入新的第三方开源软件，无License影响。

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

正向影响：8通道机型下，非AO区日志收集、固件升级、信息轮询理论上可获得接近8倍的并发度提升（实际受I3C/IPMB总线带宽和NPU侧处理能力限制）。

资源代价：新增固定大小的线程池模型（每组1个线程+strand，见6.2），线程总数=通道分组数，而非NPU数量；新增设备树对象及属性内存开销随NPU数量线性增长，在可接受范围内。

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

下沉过程采用新旧路径共存、标记使能的方式，单NPU通道异常（邮箱超时、I3C/IPMB通信失败、日志类型查询失败）不得影响其他NPU的管理任务，失败时按默认日志范围收集并上报告警。

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

四种SR/BMC组合必须全部兼容，行为矩阵见3.2。北向接口（Redfish/CLI/SNMP/Web）对NPU信息、日志、升级的语义和返回保持不变，上层仅从"资源树对象取数"切换为"设备树对象取数"。

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

• 与CSR 2.0设备树框架：强依赖，需框架支持I3C配置、新接口注册、对象Oem属性扩展。
• 与部件管理其他部件下沉：NPU下沉沿用已有的设备树下沉框架，其升级/日志/线程绑定模式可供后续部件复用。
• 与升级冗余/备件自动升级（26.09）：下沉后的bmc.dev.Upgrade是后续备件自动升级、VRD无感升级的统一入口。
• 与compute组件：并行拓扑原由compute按PSR配置自行起任务，改为compute将拓扑写入设备树对象属性；compute进入消亡路径但当前版本仍保留。

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

OpenBMC等社区BMC的部件管理普遍基于实体树（entity-manager + dbus-sensors范式）：管理对象由配置发现，驱动以服务/进程形式按总线实例并行运行，总线上的扫描与监控天然按instance隔离。openUBMC CSR 2.0设备树与之思路一致，本特性的ThreadGroupId+strand绑定即对应"按总线实例并行调度"，同时保留了openUBMC资源树时代的PSR拓扑配置和新旧SR共存能力，适合存量机型平滑演进。

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

3.1目标 ​

1. NPU的AO区、非AO区管理能力全部可在CSR 2.0设备树对象上实现，对上层暴露标准接口。
2. 按硬件通道数并行管理，并行度由拓扑配置驱动；NPU管理任务之间互不阻塞。
3. 新旧SR × 新旧BMC四种组合行为正确，可灰度、可回退，并预留断代更新路径。
4. 北向接口无感：日志收集、固件升级、信息获取的触发方式和结果不变。

3.2总体方案 ​

自描述记录（SR，Self-Description Record）分为产品自描述记录（PSR，Product Self-Description Record）和部件自描述记录（CSR，Component Self-Description Record）。本特性涉及部件管理从CSR 1.0资源树模型向CSR 2.0设备树模型演进，PSR中的产品级配置（如并行管理拓扑）继续保留并作为设备树属性的下发来源。

NPU模组管理按硬件通道分为两部分，管理框图见图1。

• BMC通过I3C与AO区交互：AO区日志收集、固件升级、告警监控。
• BMC通过IPMB与非AO区交互：非AO区日志收集、信息获取（NPU、NPU端口、光模块）。

整体方案分三个层面：

1. 设备树建模：NPU模组Path为/bmc/dev/NPUBoards/:BoardId/NPUs/:Id，Interfaces遵循南向草案；新增bmc.dev.Upgrade（NPU固件和VRD固件升级）、bmc.dev.NPU.LogCollection（AO区和非AO区日志收集）、bmc.dev.NPU.Oem（含ThreadGroupId属性，U8，默认255表示无效）。
2. 能力下沉：compute/general_hardware/network_adapter中按bustype和Model判断的NPU分支逻辑，迁移为设备树对象的方法实现与插件；邮箱机制（I3C中断收发）在南向插件中实现。
3. 并行调度：compute不再自行起并行任务，而是把PSR中的并行拓扑翻译为每个NPU对象的ThreadGroupId写入；南向按ThreadGroupId维护线程池+strand，同一NPU的任务串行（strand保序），同组不同NPU共享线程、不同组并行。

新旧SR/BMC兼容矩阵见表3，四种组合分别见图2～图5。

表3 新旧SR/BMC兼容矩阵

实现手法：在SR上配置虚拟连接器，再加载一级内置SR；内置SR上配置CSR 2.0对象用于南向驱动管理，并给原NPU对象配置一个标记用于启用设备树能力。

4. Use Case一实现：AO区管理下沉（I3C通道） ​

4.1设计思路 ​

AO区为常供电区域，BMC经I3C管理。由于I3C从机不能主动发起通信，引入邮箱机制：主机（AO区）发送完数据后触发中断寄存器；从机（BMC）检测到中断后，从规定的数据区域读取并解析数据。邮箱机制在compute插件中已验证，随本特性迁移为设备树南向插件实现。

代码参考（现状）：compute组件include/hwproxy/plugins/compute/init.lua，对外接口：

• plugins_mailbox_read
• plugins_mailbox_write
• plugins_i3c_single_file_upgrade
• plugins_i3c_collect_log
• plugins_reset_npu

前置条件：CSR 2.0先支持I3C配置。

4.2约束条件 ​

• 依赖设备树框架完成CSR 2.0的I3C总线/设备配置能力。
• 邮箱数据区布局、中断寄存器定义须与AO区固件约定一致。
• AO区告警当前仍由旧SR以chip对象配置直接上报，本期不改动代码；断代更新时再迁移到新SR。

4.3详细实现 ​

AO区包含三个功能流：

1. 日志收集：一键收集触发；先动态查询设备支持的日志类型，查询失败时按默认范围收集。现状入口：general_hardware组件src/lualib/unit_manager/class/unit/acu/npu_board.lua的collect_i3c_log。下沉后由设备树bmc.dev.NPU.LogCollection方法承载，经I3C邮箱完成命令与数据交互。
2. 固件升级：支持NPU固件升级与VRD固件升级。现状实现：compute组件src/lualib/upgrade/npu/i3c_channel.lua，其中判断bustype为I3C_BUS_TYPE的分支即本次下沉范围。下沉后由bmc.dev.Upgrade承载，单文件升级复用plugins_i3c_single_file_upgrade流程。
3. 告警监控：保留旧SR配置，AO抽象为chip对象直接上报，不涉及代码修改。

时序（日志收集）：北向一键收集 → compute/日志框架调用设备树LogCollection → 南向插件经邮箱写日志类型查询命令 → AO区触发中断 → BMC读数据区解析支持类型 → 逐类型发起收集 → 失败回退默认范围 → 打包返回。

4.4子系统间接口 ​

• 新增设备树接口bmc.dev.Upgrade：NPU固件、VRD固件升级方法。
• 新增设备树接口bmc.dev.NPU.LogCollection：AO区/非AO区日志收集方法（含日志类型查询）。
• 南向I3C插件接口沿用plugins_mailbox_read/write、plugins_i3c_single_file_upgrade、plugins_i3c_collect_log、plugins_reset_npu的语义，注册到设备树对象。

4.5子系统详细设计 ​

• CSR 2.0：新增I3C总线配置与NPU AO设备对象，绑定上述接口。
• compute：升级模块中I3C_BUS_TYPE分支改为调用设备树Upgrade接口；移除直接I3C通道操作（保留资源树路径供旧SR组合）。
• general_hardware：npu_board.lua的collect_i3c_log改为转发设备树LogCollection。
• network_adapter：不涉及AO区。

4.6 DFX属性设计 ​

性能：单文件升级、日志传输走独立I3C通道，多NPU间按ThreadGroupId并行，互不阻塞。

异常处理：邮箱读超时、校验失败按通道级故障处理，记录维护日志并告警；日志类型动态查询失败回退默认收集范围，保证一键收集成功。

可测性：支持注入邮箱中断、数据区读写、I3C通信故障；覆盖NPU固件与VRD固件两类升级的成功/中断/回滚。

安全设计：升级镜像需校验签名/版本后再下发；升级、复位等高危操作记录审计日志。

4.7系统外部接口 ​

北向触发方式不变（一键收集Web/Redfish、升级入口），仅数据源和执行路径切换到设备树。

4.8自测用例设计 ​

• AO区日志类型动态查询成功/失败两条路径，校验默认回退范围。
• NPU固件、VRD固件单文件升级成功与失败提示。
• 多NPU同时收集/升级时各通道独立、失败隔离。
• 新SR+旧BMC组合下仍走资源树路径，功能不回退。

5. Use Case二实现：非AO区管理下沉（IPMB通道） ​

5.1设计思路 ​

非AO区经IPMB管理，包含日志收集和信息获取两类能力。信息获取对象在资源树时代分散在三个组件：NPU本体在compute（npud子服务）、NPU端口在compute的port处理、NPU网口和光模块在network_adapter（同一物理部件的不同抽象）。下沉后统一挂到设备树NPU对象及其端口子对象。

5.2详细实现 ​

1. 日志收集：支持BLACKBOX、DEVICE日志分别收集，也支持同时收集；每个大类可细分小类，先尝试获取支持的小类，失败按默认类型获取；通过北向接口触发。现状入口：compute组件NPU对象的DumpLog方法（npu_service:dump_log），下沉到bmc.dev.NPU.LogCollection的IPMB实现。
2. NPU信息：温度、功耗、利用率、固件版本等，各属性轮询周期不同。现状入口：compute组件src/service/npud.lua（npud即为并行管理NPU而创建的子服务），下沉为设备树对象属性的周期刷新。
3. NPU端口：现状代码compute组件src/lualib/processor/port/npu_port.lua，下沉为NPU对象下的端口对象属性。
4. NPU网口和光模块：物理上仍是NPU端口，同一物理部件的不同抽象。现状在network_adapter组件，所有判断NetworkAdapter的Model为NPU_UB和NPU_UBoE的代码均属本次下沉范围，迁移到设备树端口/光模块对象。

5.3并行管理子服务的演进 ​

npud当前按PSR拓扑由compute在上层起并行任务；新方案下compute将拓扑信息传给南向驱动：设备树NPU对象提供可读写属性ThreadGroupId，由compute设置，南向据此完成线程绑定（见Use Case三）。

5.4自测用例设计 ​

• BLACKBOX/DEVICE单独与组合收集；小类查询失败回退默认。
• 温度/功耗/利用率/版本按各自周期刷新，断链后恢复。
• NPU_UB、NPU_UBoE两种Model下网口与光模块属性与迁移前一致。
• 北向Redfish/CLI/SNMP/Web取值与旧路径结果比对一致。

6. Use Case三实现：按硬件通道并行管理 ​

6.1 设计思路 ​

为充分利用多通道硬件优势，按通道个数并行管理（Atlas 950 SuperPoD起8路）。拓扑来源沿用PSR中的并行管理拓扑配置，但执行点从compute上层下沉到南向驱动：compute读取拓扑后，将分组信息写入每个NPU设备树对象的ThreadGroupId。

设备树接口：bmc.dev.NPU.Oem，属性ThreadGroupId，类型U8，默认值255（无效值）。

6.2 线程绑定方案 ​

1. 设备树NPU对象新增ThreadGroupId属性，默认255（无效）。compute将其修改为有效值后，触发后续任务创建。
2. 创建线程池，线程池线程数固定为1（每组一个线程）。
3. 创建一个strand，把strand绑定到这个专用线程池。
4. 把该NPU的任务全部绑定到这个strand（保证同一NPU任务保序、无锁）。
5. 如果ThreadGroupId重复，说明线程已创建：则为新增NPU创建自己的strand，再绑定到已有的线程池。

效果：同组NPU共享1个线程、各自strand独立保序；不同组分布在不同线程上并行。线程总数等于分组数（通道数），不随NPU任务量膨胀。

6.3 异常与可靠性 ​

ThreadGroupId为255时不创建任务，NPU保持未调度状态，避免半配置下误起任务；运行期分组变化（配置刷新）需先停旧strand任务再重建，禁止同一NPU同时挂到多个线程。单通道任务异常不影响同线程其他strand。

6.4 自测用例 ​

• 8通道拓扑下8组并行，验证日志收集总耗时相对串行显著下降。
• ThreadGroupId重复时复用线程池、新建strand，任务保序。
• 默认值255下不调度；配置下发后任务正确启动。

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

7.1冗余设计 ​

NPU管理无状态化设计：拓扑、对象配置来源于自描述记录（PSR/CSR），线程与任务可随BMC重启或对象重建自动恢复；升级进度、日志任务失败后可由北向重新触发，不产生需要主备同步的关键状态。

7.2故障管理 ​

• 检测：I3C邮箱超时、IPMB通信失败、日志类型/小类查询失败、升级失败均检测并记录。
• 隔离：以通道/strand为隔离域，单NPU故障不扩散到其他NPU和其他通道。
• 恢复：日志查询失败回退默认范围；通信瞬断在下次轮询周期自动恢复；AO区告警沿用chip对象SR上报，保证故障可见性不降低。

7.3过载控制设计 ​

并行度上限=通道分组数（线程池每组固定1线程），不因北向高频触发而扩张。日志收集、固件升级等重任务以strand排队方式执行，同NPU任务天然串行削峰；北向批量触发时由各组分别承接，优先保障周期监控类轻任务。

7.4升级不中断业务 ​

固件升级走独立I3C通道，单NPU升级不阻塞其他NPU监控；特性自身升级（BMC版本升级）依赖SR/BMC兼容矩阵保证新老版本共存与回退：新SR搭配旧BMC自动退回资源树路径，回退无风险。

7.5人因差错设计 ​

NPU复位（plugins_reset_npu）、固件升级等高危操作经北向原有二次确认与审计日志约束；下沉不改变北向鉴权与操作确认流程。

7.6故障预测预防设计 ​

温度、功耗、利用率等周期属性下沉后保持原有周期采集，为告警和Redfish遥测（26.09 NPU遥测指标）提供数据；线程池任务失败计数、通道通信失败统计可供故障预测采集。

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

8.1可测试性 ​

覆盖：四种SR/BMC组合的路径选择；AO/非AO日志成功与回退；NPU/VRD升级；ThreadGroupId默认值、正常值、重复值；NPU_UB/NPU_UBoE两类Model；多通道并发下的耗时与隔离。建议提供南向桩件模拟AO区邮箱中断与HDK opcode返回。

8.2可服务性 ​

保留并完善通道级、NPU级维护日志（邮箱收发、升级阶段、日志收集范围与回退原因、线程绑定关系），一键日志中包含NPU管理链路自身的诊断信息。

8.3可演进性 ​

设备树接口（Upgrade/LogCollection/Oem.ThreadGroupId）按通用方式定义，升级与日志接口不限定NPU专属命名，可被后续其他部件（硬盘、网卡等）下沉复用；断代窗口到来时可直接重写SR、北向对接设备树对象并删除compute上层路径。

8.4开放性 ​

设备树对象Path与Interfaces遵循CSR 2.0南向草案，Oem扩展仅用于并行拓扑等厂商相关属性（ThreadGroupId）；北向继续遵循Redfish标准模型。

8.5兼容性 ​

新旧SR×新旧BMC四组合兼容（见3.2矩阵）；旧SR或旧BMC在网时一律走资源树对象管理；北向上报字段与语义不变。

8.6可伸缩性/可扩展性 ​

并行度、NPU数量均由拓扑与对象配置驱动，线程数等于分组数，适配1～N路通道机型；新增NPU端口/光模块属性只扩展设备树对象，不影响调度框架。

8.7可维护性 ​

设备树对象提供属性可观测（当前ThreadGroupId、调度状态）；关键流程结构化日志；compute中保留资源树路径直至断代，便于问题定位时对比两条路径结果。

8.8资料 ​

9.数据结构设计 ​

NPU设备树对象（CSR 2.0）：

• Path：/bmc/dev/NPUBoards/:BoardId/NPUs/:Id
• Interfaces：NPU标准接口（见南向草案）
• 新增接口：
  • bmc.dev.Upgrade：支持NPU固件和VRD固件升级
  • bmc.dev.NPU.LogCollection：支持AO区（I3C）和非AO区（IPMB）日志收集，含日志类型/小类动态查询
  • bmc.dev.NPU.Oem：ThreadGroupId，U8，默认255（无效），可读写，由compute按PSR拓扑设置

并行拓扑（配置于PSR，沿用topic/6221评审结论：新增私有对象NPUConfig，不持久化，ReadOnly）：

"NPUConfig": {
  "IPMBInstanceGroups": [
    { "IPMBInstanceGroup": [1, 3, 5, 7] },
    { "IPMBInstanceGroup": [2, 4, 6, 8] }
  ]
}

IPMBInstanceGroups签名为a{ay}，描述IPMB通道数量及其管理的NPU id；compute据此为每个NPU生成ThreadGroupId写入设备树对象。

10.参考资料清单 ​

1. 社区评审：按硬件通道并行管理NPU，https://discuss.openubmc.cn/t/topic/6221（评审结论：同意新增私有对象NPUConfig）
2. 《openUBMC需求规格基线》部件管理-NPU模组管理：支持按硬件通道并行管理NPU（openUBMC26.06）等需求
3. 现状代码：
   • compute：include/hwproxy/plugins/compute/init.lua（邮箱机制）
   • compute：src/lualib/upgrade/npu/i3c_channel.lua（I3C升级）
   • compute：src/service/npud.lua（NPU并行子服务）
   • compute：src/lualib/processor/port/npu_port.lua（NPU端口）
   • general_hardware：src/lualib/unit_manager/class/unit/acu/npu_board.lua（collect_i3c_log）
   • network_adapter：NetworkAdapter Model为NPU_UB/NPU_UBoE的分支