硬件适配总览 ​

openUBMC定位为全栈智能管理软件底座，从产品集成角度出发，需要同时支持整机类适配与部件类适配两种硬件接入路径：整机类适配解决"一台服务器产品如何快速接入 openUBMC"的问题；部件类适配解决"一块具体硬件部件（网卡/硬盘/RAID卡/XPU/电源等）如何被识别并纳入管理"的问题。

本总览作为硬件适配的入口文档，回答"是什么、解决什么问题、核心方案是什么、有哪些典型场景"，并给出深入阅读的文档索引。细节实现请跳转到对应分册。

一、整机类适配 ​

1.1 整机类适配的要求与解决的问题 ​

整机（服务器产品）是由多个板卡通过复杂拓扑互联构成的物理系统，openUBMC需要在系统上电后把整机的真实物理形态映射为一棵可管理、可查询、可同步的对象树，并支撑上下电、散热、监控、告警、故障诊断等上层业务。

整机类适配要满足的核心要求：

• 准确映射整机拓扑：把服务器各板的连接关系逐级还原到对象树；
• 配置化接入：通过 CSR（Component Self-Description Record）硬件自描述数据描述板卡，每块板卡通过 CSR 配置即可接入，无需为每个新机型硬编写一套管理代码；
• 与业务剥离：硬件拓扑的发现结果通过对象组（ObjectGroup）分发，各业务组件按需获取自身对象，实现"南向发现、业务消费"的解耦；
• 支持天池/非天池两类组件：天池组件支持标准命令字、CSR 升级与软硬件解耦；非天池组件依靠 BMC 内置 CSR。

整机类适配主要解决的问题是：改变"固定配置写死、新机型难接入"的旧模式。

1.2 整机适配的核心方案：三个层次与一套流程 ​

整机适配依赖 硬件自发现（hwdiscovery） 框架，其核心是三级板卡对象 + 逐级 Connector 加载。框架能力部分由 openUBMC 的 SDK 承载，部分由 devmon 仓承载，采用 MDS 数据模型 + CSR 硬件自描述双模型架构。分层与自发现的详细设计见 openUBMC devmon 特性设计说明书。

1.2.1 三个板卡层次 ​

说明：基础板（BCU）之下通常还挂接 Riser 卡，Riser 卡上再插入各种 PCIe 卡（网卡/GPU/RAID卡等），由此连接到"部件类适配"场景。

1.2.2 层次关系与加载流程 ​

每两份 CSR 之间一定通过 Connector 相关联，框架通过 Connector 一级一级地进行对象的加载和分发。加载顺序（即硬件拓扑的还原顺序）如下：

自发现的关键工作流程（详见 硬件自发现）：

1. 读取入口 CSR：hwdiscovery 读取系统 flash 区的 root.sr（芯片链路拓扑）、platform.sr（软件配置对象信息）；
2. 解析与对象组发布：解析、校验、解压缩 CSR，依据 MDS 类与组件映射关系，把对象放到 ObjectGroup 并标记 Owner，分发给各业务 app；
3. 并发发现下一级：遍历 Connector 对象，依据 IdentifyMode（1/2/3，详见 1.2.3）和 Presence 在位状态，读取下一级板卡 Eeprom/UID，获取 bom_id_auxid 对应 CSR，多版本比较后进入下一轮解析；
4. 对象重命名保证全局唯一：由"SR对象名 + Position 后缀"组成，Position 由各级 Connector 的 Position 拼接而成（如 NetworkPort_1_010105、ExpBoard_1_0101、RiserCard_1_01010103）；
5. 启动在位检测任务：持续监测板卡在位/热插拔变化。

1.2.3 天池与非天池组件识别 ​

Connector 对象通过 IdentifyMode 标识组件的识别与软硬件接口方式：

• IdentifyMode=1（BoardId 可读）：组件支持 BoardId 读取，需配置 Id 获取方式，通过硬件代理读取寄存器数据；
• IdentifyMode=2（非天池）：组件不支持 BoardId 读取，CSR 存放于 BMC 内置存储，加载方式为拼接 Bom + Id + AuxId 定位 Bom_Id_AuxId.sr，不支持 CSR 升级；
• IdentifyMode=3（天池/天池标准）：通过标准 SMC 命令字承载通用软硬件接口，CSR 存储于板卡 Eeprom，支持 CSR 升级，具有接口标准化、软硬件解耦、前后演进及后向兼容等优点。

IdentifyMode 取值及 BoardId 读取机制的详细定义见 Connector 配置字典，对比归纳可参考 板卡适配指南。

1.3 整机适配典型场景 ​

二、部件类适配 ​

2.1 部件类适配解决的问题 ​

整机类适配解决"这台机器的板卡拓扑怎么被 BMC 认识"；部件类适配则针对具体硬件部件：网卡、硬盘、RAID卡、XPU（GPU/NPU/FPGA）、电源等。部件类适配要解决的问题是：

• 统一部件接入方式：不同厂商、不同型号的同类部件，采用统一的描述（CSR）与统一的驱动 ABI，避免每个厂商各写一套管理系统；
• 新增部件零重编译：新型号部件只需新增 CSR 配置与驱动 SO，无需重编译整个 BMC；
• 即插即用与热插拔：硬件在位即被识别、驱动即被加载；拔出后驱动随之下线并完成资源释放；
• 规范化的生命周期：统一 create/init/start/stop 生命周期，保证资源正确创建与释放；
• 具体部件专有能力：如网卡的带外管理（NCSI/MCTP）、RAID 卡存储管理、电源 PMBus 监控、GPU/xPU 加速卡管理。

2.2 部件适配 1.0 与 2.0：核心思路、演进与特点 ​

部件适配的演进本质是：从"每类部件各写一套、配置写死"走向"自描述 + 动态加载 + 统一契约"。

2.2.1 部件适配 1.0（各写一套，能力绑定部件） ​

核心思路：针对具体部件型号编写专用驱动与接入逻辑，部件信息与业务能力在代码中耦合。

• 每个部件自己完成枚举（enumerate），自描述不统一，配置与能力逻辑需要在组件代码中配置；
• 新增型号需要新增驱动甚至修改框架，部件多样时驱动数量爆炸、维护成本高；
• 缺乏统一的自描述与驱动注册契约，部件接入方式因型号而异。

关键环节包括：

1. 修改 mdb_interface 增加接口、路径和属性：在接口定义仓 mdb_interface 中为部件新增 D-Bus 资源协作接口，定义其接口名、对象路径（Path）与属性（Properties）等；
2. 在 vpd 中增加 sr：在 vpd 产品数据管理组件仓中为该部件新增/配置 sr 自描述文件，供自发现加载与识别；
3. 在部件中修改 model.json 并进行自动生成：在对应部件组件中按 MDS 数据模型修订 model.json，并通过 bingo gen 自动生成接口与对象代码；
4. 修改业务逻辑：在自动生成之后，还需在对应业务组件中修改业务逻辑，例如 pcie_device、network_adapter、storage 等。

定位说明：部件适配 1.0 接入一个部件时，需要散弹式修改 mdb_interface、vpd、部件组件、业务组件等多个仓库的代码，容易造成多个组件耦合；而 2.0 将描述与驱动契约统一收敛到部件驱动框架，更接近"为每个部件量身定制、可独立演进"的驱动形态。

2.2.2 部件适配 2.0（CSR 自描述 + SO 动态加载 + 统一 ABI 契约） ​

核心思路：以 CSR（Component Self-Description Record） 作为部件统一自描述，以 SO 动态加载 接入驱动，以 统一 ABI（register_device_driver） 建立驱动契约，实现"描述与实现分离、发现与加载自动化"。

关键环节包括：

1. CSR 自描述：用 DDS（Device Description Schema，定义接口/路径模式）与 SR（Self-Description Record，定义拓扑/初始属性/Compatible）描述部件；
2. 驱动匹配与动态加载：根据 Compatible 字段定位 lib{driver}.so，dlopen/dlsym 加载并调用导出的 register_device_driver() 注册驱动数组；
3. 统一 ABI：device_driver_t 由 device_name/ctor/init/start/stop 组成，生命周期统一为 创建→初始化→启动→停止；
4. 属性自动注入：借助 MC_REFLECT 反射机制，将 CSR 配置自动映射到对象属性；
5. 横切类型逐步覆盖：在统一契约之上，按品类沉淀规范（网卡/GPU/xPU/硬盘/RAID/电源风扇）。

2.2.3 演进对比 ​

2.3 部件适配典型场景 ​

注：部件类分册的完整导航与选用路径见 部件驱动适配指南。

三、整机适配与部件适配的关系 ​

• 二者是同一硬件管理链路的两个层次：整机适配负责"板卡拓扑与对象树"，重点在 hwdiscovery 框架侧；部件适配负责"具体部件的驱动与专有能力"，重点在 component_drivers 驱动库侧；
• 通过 Riser/PCIe 互联：整机层次中 Riser 卡上的 PCIe 卡（网卡/GPU/RAID卡）正是部件适配的接入对象；
• 共享 CSR 自描述语言：整机的板卡（EXU/BCU/SEU/CLU）与各类部件（网卡/硬盘/RAID卡/电源）均用 CSR 描述，只是描述粒度和归属对象不同；
• 对象分发贯穿两层：硬件自发现把对象经 ObjectGroup 分发给各业务组件，部件驱动注册后的对象同样挂载到对象树并被上层消费。

四、文档索引 ​

整机类适配 ​

• 硬件自发现：整机拓扑发现框架、层次、流程、ObjectGroup 分发
• openUBMC devmon 特性设计说明书：devmon 硬件管理框架的分层插件化架构、MDS+CSR 硬件自发现、部件发现与注册
• 板卡适配指南：板卡类别、加载方式、Connector 配置
• 新增产品：manifest 产品级配置
• 多层级接口定制：产品/客户三级接口差异化定制
• 白牌定制化、散热配置

部件类适配 ​

• 部件驱动适配指南：分册导航与阅读路径
• 部件驱动自发现机制设计：CSR/SO/ABI/生命周期/自发现
• 网卡 4.1 / GPU-xPU 4.2 / 硬盘 4.3 / RAID 4.4 / 电源风扇 4.5
• 部件驱动开发简介：开发/编译（bingo）/测试环境搭建