部件类适配快速上手 ​

前置说明：本文假设您已经完成 环境搭建 并阅读了 硬件适配总览，理解了整机类适配与部件类适配的差异，以及部件类适配的资源树适配方案1.0（即部件适配 1.0 方案）与部件驱动适配方案2.0 两种方案的定位。本文聚焦部件类适配的资源树适配方案1.0的最短可操作路径，以一块标准 PCIe GPU 卡为例，手把手带您完成第一个部件的接入与验证。原理细节与复杂场景请参见 硬件适配总览 及文中相应章节的链接。

一、概述 ​

1.1 部件类适配的资源树适配方案1.0 是什么 ​

部件类适配的资源树适配方案1.0 通过一份 CSR（.sr 硬件自描述文件）描述部件的固定信息、管理拓扑、传感器与告警，并将部件通过上级组件的 Connector 挂接到资源树上：

编写部件 SR（Bom_Id_AuxId.sr，存放在 vpd 仓）
        ↓
上级组件 SR 中的 Connector 声明该部件（Bom + Id + AuxId）
        ↓
硬件自发现（hwdiscovery）根据在位状态与四元组信息加载部件 SR
        ↓
部件对象上树（资源协作接口），经 ObjectGroup 分发给各业务组件
        ↓
Web / Redfish / IPMI 正常识别与管理该部件

核心思路：配置为主、代码为辅。部件的管理对象（如 GPU、PCIeDevice、PCIeCard、Component_PCIeCard 等）已在 mdb_interface 中定义时，适配工作主要是新增/修改 SR 配置；只有当部件需要新的带外管理协议等能力时，才需要修改组件业务代码。

1.2 适用场景 ​

部件类适配的资源树适配方案1.0 适用于以下类型部件的适配：

• 标准 PCIe 部件：GPU/xPU 加速卡、PCIe 网卡、RAID 卡、SSD 加速卡等规范 1.0 普通 PCIe 卡；
• 通过上级组件（Riser 卡 / IEU 载板等）接入的部件：部件 SR 由上级 Connector 挂接，IdentifyMode=2（非天池）方式加载，SR 内置于 BMC；
• 管理对象已有标准定义的部件：BMC 已有该类部件的资源对象与业务组件，只需通过配置完成识别、资产信息、传感器、告警的接入。

1.3 与部件驱动适配方案2.0 的适用差异（选型确认） ​

开始前请先确认方案没有选错。两种方案的差异如下：

快速判断：

• GPU 卡、PCIe 卡等品类当前版本已切换部件驱动适配方案2.0，此类部件的新适配请参考《部件驱动接入》章节的概述（Component Drivers 项目概览）；当前版本仍兼容支持 CSR 1.0 配置，若维护存量 1.0 配置或适配尚未迁移 2.0 的部件品类，可按本文的部件类适配的资源树适配方案1.0 执行；
• 若需要为部件编写独立驱动 SO、新增资源接口与驱动框架，请参考 硬件适配总览 第 2.2 节，走部件驱动适配方案2.0。

二、适配前准备 ​

适配前请先收集部件的硬件信息，这些信息将直接用于 Connector 与 SR 配置：

提示：四元组与 BDF 可在整机 OS 下执行 lspci -nn 核对；部件 BOM 编码与槽位连线关系请向硬件获取，并确认整机适配时已配置对应槽位的 PcieAddrInfo 对象（详见常见问题）。

三、端到端适配步骤（以某型号 GPU 卡为例） ​

整体流程共 5 步：收集信息并规划 SR → 配置上级 Connector → 编写部件 SR → （按需）配置带外管理协议 → 构建与部署，最后按第四节完成验证。

步骤 1：收集部件信息并规划 SR ​

1. 按"适配前准备"中的信息表收集部件信息；
2. 确认部件 SR 的文件名：SR 文件名由上级 Connector 中的 Bom + Id + AuxId 拼接而成（如 14140130_1_0.sr）。其中 Id、AuxId 在 IdentifyMode=2 场景下由 BMC 根据 BIOS 上报的 BDF 查询四元组后回填；
3. 确认部件挂接的上级组件（如 Riser 卡）及其 SR 中可用的总线通道。

预期结果：获得一张完整的部件信息表，并明确 SR 文件名与上级组件。

步骤 2：在上级组件 SR 中配置 Connector ​

部件通过上级组件 SR 中的 Connector 对象挂接到资源树。在上级组件（如 Riser/IEU）SR 的 Objects 中为该部件增加 Connector（下文示例中的 // 注释仅为字段说明，SR 为标准 JSON、不支持注释，实际写入时须删除）：

{
    "Connector_PCIE_1": {
        "Bom": "14140130",
        "Slot": 1,
        "Position": 1,
        "Presence": 0,  // 在位信息由 BIOS 上报 BDF 后，BMC 根据四元组查询结果更新
        "Id": "",
        "AuxId": "",
        "Buses": [
            "I2cMux_9545Chan1"  // 部件管理总线，对应上级组件 SR 中已配置的通道
        ],
        "SystemId": "${SystemId}",
        "ManagerId": "${ManagerId}",
        "ChassisId": "${ChassisId}",
        "IdentifyMode": 2,  // 非天池组件：根据 Bom+Id+AuxId 加载 BMC 内置 SR
        "Container": "Component_RiserCard",
        "Type": "PCIe"
    }
}

关键字段说明：

字段取值的完整定义参见 Connector 配置字典。

预期结果：上级组件 SR 中新增了该部件的 Connector，且 Bom、Buses、IdentifyMode 与实际硬件匹配。

验证方法：该步骤的配置随上级组件构建升级后生效，验证方法见第四节 4.1。

步骤 3：编写部件 SR 文件 ​

在 vpd 仓对应机型目录下新增部件 SR 文件（文件名为 Bom_Id_AuxId.sr）。SR 为合法 JSON，包含 FormatVersion、DataVersion、ManagementTopology、Objects 四部分，格式规则详见 CSR 配置规则。

一个最小可用的 GPU 卡 SR 示例如下（仅含识别与资产信息，可在此基础上按需扩展；示例中的 // 注释仅为字段说明，实际写入 SR 文件时须删除）：

{
    "FormatVersion": "3.00",
    "DataVersion": "1.00",
    "ManagementTopology": {
        "Anchor": {
            "Buses": ["I2cMux_9545Chan1"]  // 与上级 Connector 的 Buses 对应
        }
    },
    "Objects": {
        "Component_PCIeCard": {
            "Instance": "<=/PCIeDevice_1.SlotID",
            "Type": 8,  // 部件类型，对应代码中的 COMPONENT_TYPE*
            "Name": "<=/PCIeDevice_1.DeviceName",
            "FruId": 255,  // 无 Fru 则默认 255
            "Presence": 1,
            "Health": 0,
            "GroupId": 1,
            "SerialNumber": "<=/PCIeCard_1.SerialNumber"
        },
        "Entity_GPUCard": {
            "Id": 11,
            "Name": "GPUCard",
            "PowerState": 1,
            "Presence": 1,
            "Instance": 101
        },
        "PCIeDevice_1": {
            "DeviceName": "PCIe Card $ (RTX A6000)",
            "FunctionClass": 3,  // 3 表示 GPU 卡
            "Container": "${Container}",
            "GroupPosition": "PCIeDevice_${GroupPosition}",  // 同一 SR 内不能重复
            "DeviceType": 8,
            "FunctionProtocol": "PCIe",
            "SlotID": 1,
            "DevBus": 1,
            "DevDevice": 0,
            "DevFunction": 0,
            "SocketID": 0
        },
        "PCIeCard_1": {
            "SlotID": "<=/PCIeDevice_1.SlotID",
            "Name": "RTX A6000",
            "Model": "RTX A6000",
            "FunctionClass": 3,
            "VendorID": 4318,
            "DeviceID": 8752,
            "SubVendorID": 4318,
            "SubDeviceID": 5209,
            "Position": "<=/PCIeDevice_1.Position",
            "Manufacturer": "Nvidia",
            "PartNumber": "0632Y014",
            "DevBus": "<=/PCIeDevice_1.DevBus",
            "DevDevice": "<=/PCIeDevice_1.DevDevice",
            "DevFunction": "<=/PCIeDevice_1.DevFunction",
            "SerialNumber": "<=/GPU_1.SN"
        },
        "GPU_1": {
            "Id": 1,
            "Name": "RTX A6000",
            "Presence": 1,
            "Manufacturer": "Nvidia",
            "Model": "RTX A6000",
            "SN": "",
            "ProcessorType": "2",
            "Health": "#/Component_PCIeCard.Health",
            "Slot": "<=/PCIeDevice_1.SlotID",
            "VendorID": 4318,
            "DeviceID": 8752,
            "SubVendorID": 4318,
            "SubDeviceID": 5209,
            "DevBus": "<=/PCIeDevice_1.DevBus",
            "DevDevice": "<=/PCIeDevice_1.DevDevice",
            "DevFunction": "<=/PCIeDevice_1.DevFunction",
            "Position": "<=/PCIeDevice_1.Position",
            "SerialNumber": "#/PCIeCard_1.SerialNumber"
        }
    }
}

配置要点：

• FormatVersion 当前为 3.00；DataVersion 采用 A.BC 格式（如 1.00）；
• ManagementTopology.Anchor.Buses 中的总线须与上级 Connector 的 Buses 对应；
• 对象间的引用分为 <=/对象名.属性（同步引用）与 #/对象名.属性（引用），语法详见 CSR 配置规则；
• GPU 对象的 Model 字段须与实际部件型号一致，它同时也是步骤 4 中带外协议配置文件的匹配依据。

预期结果：vpd 仓中新增合法的 Bom_Id_AuxId.sr 文件，JSON 可正常解析。

验证方法：构建升级后执行第四节 4.1、4.2 的检查，确认 GPU_1、PCIeDevice_1 等对象按预期上树。

传感器（ThresholdSensor/Scanner）、告警事件（Event）、散热配置属于扩展配置，配置方法参见 GPU1.0卡适配指导 与 传感器 相关章节。首次适配建议先走通本最小示例，再逐步叠加扩展配置。

步骤 4：（按需）配置带外管理协议 ​

若部件的序列号、固件版本、温度等信息需要通过带外管理协议获取，按以下方式处理：

• NVIDIA GPU：openUBMC 已支持 SMBPBI 协议。协议配置文件位于 general_hardware/src/lualib/hardware_config/ 目录，文件名与 GPU 对象的 Model 字段匹配（如 RTX A6000 对应 RTX_A6000.lua）：若适配型号已有对应配置文件则直接复用；若为新型号，参考同目录下的 Tesla_T4.lua、RTX_A6000.lua 新建 <Model>.lua；
• 非 NVIDIA GPU 或需要新协议的部件：需要修改 general_hardware 组件代码实现新的带外管理协议，规范参见 GPU卡驱动规范；
• 仅做识别与资产信息接入的部件：可跳过本步骤。

预期结果：general_hardware 中新增与部件 Model 匹配的协议配置文件（如适用）。

步骤 5：构建与部署 ​

SR 与组件修改完成后，依次构建并部署：

# 1) 构建受影响组件（vpd、general_hardware 等）并更新其版本
bingo build --stage=stable
# 2) 在 manifest 中将上述组件版本更新为实际构建版本
# 3) 整包构建
bingo build

预期结果：

• 组件与整包构建成功，无报错；
• 将整包升级至目标环境（实机或 QEMU）后，BMC 正常启动。

验证方法：升级完成后，执行第四节全部验证项。

四、适配验证 ​

按以下顺序验证适配结果，全部通过即表示部件已被 BMC 正常识别和管理。

4.1 验证自发现与对象上树 ​

通过资源协作接口查看硬件自发现结果：

# 查看自发现对象树
busctl --user tree bmc.kepler.hwdiscovery

预期结果：对象树中能看到上级 Connector 挂接的部件对象组（ObjectGroup 以部件 Position 命名）。

进一步查看部件 SR 中对象是否分发给业务组件（以 pcie_device 为例）：

# 通过 GetObjects 查看指定 ObjectGroup 分发给组件的对象
busctl --user call bmc.kepler.hwdiscovery /bmc/kepler/ObjectGroup/<Position> \
    bmc.kepler.ObjectGroup GetObjects 'a{ss}s' 0 pcie_device

<Position> 为部件对象组的 Position 标识，可先通过 busctl --user tree bmc.kepler.hwdiscovery 找到对应节点。GetObjects 接口的详细说明见 硬件自发现。

4.2 验证部件识别与资产信息 ​

# 查看部件对象属性（对象名以实际 SR 配置为准）
busctl --user introspect bmc.kepler.pcie_device /bmc/kepler/PCIeDevice/PCIeDevice_1

预期结果：

• GPU_1 / PCIeDevice_1 / PCIeCard_1 等对象存在，Model、Manufacturer、VendorID、DeviceID 等资产属性与实际硬件一致；
• 部件在位状态（Presence）正确。

同时可通过 Web 界面（"系统信息 → PCIe 设备 / GPU"页面）或 Redfish 接口交叉确认部件信息展示正常。

4.3 验证传感器与告警（若已配置） ​

# 查看传感器读值（如 GPU 温度）
ipmitool sensor list | grep -i gpu
# 触发告警后查看事件日志
ipmitool sel list

预期结果：传感器读值在合理区间且随温度变化；温度超阈值时可产生对应事件日志。

4.4 验收检查清单 ​

五、常见问题 ​

1. 部件无法识别

   • 检查上级 Connector 的 Bom 与部件 SR 文件名（Bom_Id_AuxId.sr）是否一致；
   • IdentifyMode=2 时依赖 BIOS 上报 BDF：确认整机适配时已配置对应槽位的 PcieAddrInfo 对象，且 OS 下 lspci -nn 可看到该部件；
   • 检查四元组配置是否与实际硬件一致。

2. 传感器无读值或读值异常

   • 检查 SR 中 ManagementTopology 的总线/芯片链路是否与上级 Connector 的 Buses 匹配；
   • 检查阈值传感器的 M、RBExp 取值是否使读值落在有效区间。详见 CSR 配置规则 与 GPU1.0卡适配指导。

3. 发现当前方案不适用

   • 若适配过程中发现需要新增独立的驱动 SO、新的资源协作接口或部件驱动框架，说明该部件更适合部件驱动适配方案2.0，请转至 《部件驱动接入》概述 与 总线芯片驱动开发指南。