文档中心
整机类适配快速上手
更新时间： 2026/08/20
在Gitcode上查看源码

整机类适配快速上手 ​

前置说明：本文假设您已经阅读了 硬件适配总览，理解了整机类适配与部件类适配的差异、整机板卡层次（插卡 / EXU / BCU / SEU / CLU / 板载NIC / Riser）以及硬件自发现（hwdiscovery）框架的工作原理。本文聚焦整机类适配的具体操作，手把手带您完成一款新整机 / 一块新板卡的硬件接入。

BMC 作为一款服务器带外管理软件，差异性的硬件适配是 BMC 最常见的业务场景。openUBMC 通过 MDS 数据模型 + CSR 硬件自描述 + 硬件自发现（hwdiscovery）+ 对象组（ObjectGroup）分发的组合，把"新增一款整机 / 新增一块板卡"从"写死固定配置"变为配置化、增量式的接入方式。与部件类适配（针对网卡/硬盘/RAID卡等具体部件、侧重驱动库 component_drivers）不同，整机类适配侧重板卡拓扑与对象树，主要工作在 vpd（存放 CSR）、组件（业务逻辑）与 mdb_interface（资源接口）等仓。

本文覆盖整机类适配的两条典型路径：

  1. 场景一：新增/切换整机机型——从平台/产品维度接入一款全新整机；
  2. 场景二：新增一块板卡（板卡拓扑适配）——在已有整机上新增/替换一款板卡。

两场景都遵循同一套通用流程：CSR 配置 → 组件构建 → 整包构建 → 整包测试。

一、前置准备 ​

开始适配前，请先完成如下准备：

  1. 环境与源码：参考 环境搭建 准备编译环境，并拉取本次适配需要的仓库，通常包括：

    • vpd：存放机型 root.sr、platform.sr 及各类板卡的 CSR；
    • mdb_interface：资源协作接口定义（接口、路径、属性）；
    • 组件仓（如 pcie_device、sensor、power_mgmt 等）：承载对应板卡对象的业务逻辑。

  2. 理解 CSR 与自发现流程：CSR（Component Self-description Record）是 openUBMC 用软件描述性语言描述一块硬件具体信息的载体；硬件自发现会读取 root.sr、platform.sr，通过 Connector 逐级加载，并把对象经 ObjectGroup 分发给各业务组件。细节见 硬件自发现。

  3. 明确整机板卡层次与加载顺序：整机自发现按以下顺序逐级还原硬件拓扑：

每两份 CSR 之间一定通过 Connector 相关联。您新增的板卡需要在其上一级板卡 CSR 中通过 Connector 挂接，才能被自发现逐级加载。

二、场景一：新增 / 切换整机机型 ​

当需要接入一款全新整机（机型形态、组件依赖、板卡组合与既有机型不同）时，采用本场景。总体思路是：在 manifest 中定义机型 → 在 vpd 中配置整机 CSR 入口 → 为各级板卡编写 CSR → 构建升级并验证自发现。

步骤 1：新增机型产品配置 ​

在 manifest 中新增/切换产品配置（base、dependencies、gpp、tosupporte 等字段），定义机型形态与组件依赖。具体参见 新增产品。

步骤 2：配置整机 CSR 入口 ​

在 vpd 仓对应的机型路径（如 vendor/<厂商>/<机型>/）下配置整机 CSR 入口文件：

  • root.sr：描述产品芯片链路拓扑（插卡，硬件自发现入口）；
  • platform.sr：描述软件配置对象信息。

步骤 3：为整机各级板卡编写 CSR ​

依据整机实际板卡组合，为各级板卡编写 CSR：扩展板（EXU）、基础板（BCU）、硬盘背板（SEU）、风扇板（CLU）、板载网卡（NIC）等，并按 Connector 建立层级关系。每类板卡的具体配置方法，请遵循对应的板卡 CSR 配置指导书（见 第四节：板卡配置指导书索引）。

步骤 4：组件 / 整包构建 ​

CSR 及组件修改完成后依次构建：

bash
# 1) 构建受影响组件（如 vpd），并更新其版本
bingo build --stage=stable
# 2) 在 manifest 中把对应组件版本更新为实际构建版本
# 3) 整包构建
bingo build

步骤 5：升级与自发现验证 ​

整包升级后，通过资源协作接口查看硬件自发现结果，确认板卡对象是否按预期分层上树：

bash
busctl --user tree bmc.kepler.hwdiscovery

正常情况下，应能看到与板卡拓扑对应的 Connector 与 ObjectGroup 节点，且各板卡对象正确挂载到对象树。

三、场景二：新增一块板卡（板卡拓扑适配） ​

当在已有整机上新增/替换一款板卡（如新增一块扩展板、一块硬盘背板、一块风扇板）时，采用本场景。总体思路是：确定板卡类型 → 按对应指导书编写 CSR → 挂接到上级 Connector → 存储 CSR → 构建升级并验证。

步骤 1：确定板卡类型 ​

明确待接入板卡属于 BCU / IEU / EXU / SEU / CLU / PSR 中的哪一类，选择对应的板卡 CSR 配置指导书。不同板卡的管理拓扑（Anchor / Buses / Chips / Connectors）、对象与属性配置差异较大，务必以对应指导书为准（见 第四节：板卡配置指导书索引）。

步骤 2：编写板卡 CSR ​

一个完整的 SR 文件包含硬件的版本描述信息、管理拓扑信息、传感器和状态信息、告警与事件信息、装备测试信息，数据结构为 FormatVersion、DataVersion、ManagementTopology、Objects 四大部分。请参考对应板卡配置指导书完成：

  • 版本描述信息：FormatVersion（当前 3.00）、DataVersion、Unit（组件类型 Type 与单板名称 Name）；
  • 管理拓扑 ManagementTopology：配置 Anchor、Buses、Chips、Connectors 的层级关系。

步骤 3：建立 Connector 层级关系 ​

在上一级板卡 CSR 的 Connector 中声明该板卡（每两份 CSR 通过 Connector 关联），并配置：

  • IdentifyMode：天池组件（=3）走标准命令字、CSR 存板卡 EEPROM、支持 CSR 升级；非天池组件（=2）CSR 内置于 BMC；
  • 在位检测相关配置：依据 Presence 在位状态执行下级板卡的并发发现。

步骤 4：存储 CSR ​

  • 天池组件：将 CSR 写入板卡 EEPROM；
  • 非天池组件：将 CSR 内置于 BMC 存储，加载方式为拼接 Bom + Id + AuxId 定位 Bom_Id_AuxId.sr。

步骤 5：构建、升级与验证 ​

bash
# 1) 构建受影响组件并更新版本
bingo build --stage=stable
# 2) 更新 manifest 中组件版本
# 3) 整包构建
bingo build

整包升级后，通过资源协作接口确认新增板卡的 Connector 与板卡对象正确上树、在位检测正常：

bash
busctl --user tree bmc.kepler.hwdiscovery

四、板卡配置指导书索引 ​

在场景一/场景二中编写板卡 CSR 时，请务必先阅读对应板卡类型的配置指导书。规范引导位于 component_csr_guide 下，常用板卡配置指导书如下：

板卡类型说明配置指导书
BCU（基础板）承载主要计算资源，向上连接 EXU，向下引出 Riser基础板 CSR 配置指导书
IEU（部件扩展板）部件扩展接入IEU CSR 配置指导书
EXU（扩展板）与 BMC 插卡直接相连，横向扩展端口/总线EXU CSR 配置指导书
SEU（硬盘背板）承载存储资源SEU CSR 配置指导书
CLU（风扇板）承载散热资源CLU 配置指导书
PSR（整机）整机级配置整机 PSR 配置指导书

若需要从零新建一个 CSR 文件，可参考 如何从零开发一个 CSR。

五、通用流程小结 ​

无论场景一还是场景二，整机类适配的增量开发都遵循以下闭环：

text
① CSR 配置（vpd：root.sr / platform.sr / 板卡 sr）
        ↓
② 组件构建（bingo build --stage=stable/rc，更新版本）
        ↓
③ 整包构建（manifest 更新版本，bingo build）
        ↓
④ 整包测试（升级后通过 busctl 查看对象树与对象接口）

完成上述流程后，新增的整机/板卡即可被硬件自发现识别，其管理对象经 ObjectGroup 分发给各业务组件，供上层业务（上下电、散热、监控、告警等）消费。更深入的板卡适配机制与业务对象接入，可参考 板卡适配指南 与 硬件自发现。