pcie_device ​

版本信息 ​

1. 组件概述 ​

1.1 组件简介 ​

pcie_device组件是OpenUBMC系统中PCIe设备管理的核心组件，承载了BMC对PCIe设备的端到端管理能力，涵盖业务拓扑（BizTopo）的解析建链到终端PCIe设备的纳管。

1.2 解决什么问题 ​

• PCIe拓扑关系自动化：通过解析CSR、PSR配置信息，自动建立CPU、SerDes、UBC/UBCDD、Riser卡到PCIe槽位的完整业务拓扑链路，消除人工配置的复杂性和出错风险。
• PCIe设备零配置纳管：结合带内Host上报的BDF信息与IMU读取的设备四元组（VID/DID/SubVID/SubDID），实现标准PCIe设备的自动发现和加载。
• 高速链路实时检测：通过SMC周期性读取线缆连接信息，与白名单配置进行比对，实时检测线缆错插、漏插等异常并上报告警。
• 故障诊断与RAS能力：提供PCIe设备错误事件设置、链路状态监控、错误计数器统计等RAS功能，辅助运维人员快速定位故障。

1.3 核心功能 ​

• PCIe业务拓扑建立：基于CSR和PSR配置，自动建立从CPU SerDes到PCIe槽位的完整业务拓扑链路，为BIOS生成丝印文件提供数据基础。
• PCIe设备加载与管理：接收带内Host上报的设备BDF信息，通过IMU获取设备四元组，自动触发框架自发现加载PCIe设备CSR，实现对标准PCIe设备（PCIe卡、OCP卡、NVMe盘等）的纳管。
• 高速线缆检测与告警：实时读取高速链路线缆连接信息，与PSR白名单配置进行比对，在线缆错插、漏插时产生精确告警。
• PCIe设备故障诊断：支持设置各类错误事件状态（UCE、CE、降带宽、降速率、诊断故障、预故障等），提供RAS错误计数器的读取和清零能力。

1.4 关键术语表 ​

1.5 外部交互边界图 ​

pcie_device组件与以下外部系统交互：

• BIOS组件：订阅Bios对象的PcieCardBDF、OCPCardBDF、PcieDiskBDF属性变化，接收带内Host上报的设备BDF信息；通过PcieAddrInfo对象为BIOS生成丝印文件提供数据。
• IMU（带内）：通过设备BDF向IMU查询PCIe设备的四元组信息，用于匹配设备CSR并触发加载。
• SMC：通过SMC命令字读取线缆连接信息（UID、SrcPortName、TargetPortId等），用于线缆检测和拓扑建立。
• FruCtrl：订阅PowerState属性变化，感知系统上下电状态，驱动设备加载/卸载流程。
• Connector（框架自发现）：通过设置Connector对象的Presence、Id、AuxId等属性，触发框架自发现加载PCIe设备CSR。
• FruData/Board：订阅BoardSerialNumber、BoardPartNumber属性，用于PCIe卡信息关联。
• devmon（设备树方式）：监听设备树方式加载的PCIe设备（PCIeGpuCard、PCIeNicCard），手动创建对应的资源树对象。

2. API 使用说明与示例 ​

2.1 资源协作接口 ​

/bmc/kepler/Systems/${SystemId}/PCIeDevices/${Id} - GetDeviceName ​

功能说明 ​

获取PCIe设备丝印信息，返回设备的名称标识。

参数说明 ​

返回值与异常 ​

/bmc/kepler/Systems/${SystemId}/PCIeDevices/${Id} - GetPCIeCardNum ​

功能说明 ​

获取当前System下PCIeCard的数量。

参数说明 ​

无输入参数。

返回值与异常 ​

/bmc/kepler/Systems/${SystemId}/PCIeSlots/${ID} - PowerControl ​

功能说明 ​

控制PCIe槽位的上下电状态，支持对指定PCIe槽位执行电源控制操作。

参数说明 ​

限制条件 ​

需要槽位支持热插拔功能，且对应PCIe设备已完成初始化。

2.2 IPMI命令 ​

pcie_device组件注册了以下IPMI命令，用于与带内Host交互：

2.3 资源树对象模型 ​

PCIeDevice ​

PCIe设备的核心管理对象，承载了PCIe总线相关属性定义和故障诊断标识。

PCIeDevice.RAS接口（bmc.kepler.Systems.PCIeDevices.PCIeDevice.RAS）：

PCIeCard ​

PCIe卡的管理对象，承载PCIe卡的基本信息。不同类型的PCIe卡（如SDI卡）通过继承扩展。

OCPCard ​

OCP卡的管理对象，属性同PCIeCard，路径为/bmc/kepler/Systems/${SystemId}/PCIeDevices/OCPCards/${Id}。

PcieAddrInfo ​

PCIe地址信息对象，承载槽位的地址映射关系，是拓扑建立的核心输出对象。

PCIeFunction ​

PCIe功能对象，包含RAS错误计数器，路径为/bmc/kepler/Systems/${SystemId}/PCIeDevices/${Id}/PCIeFunctions/${PCIeFunctionId}。

PCIeSlot ​

PCIe槽位对象，支持电源控制操作，路径为/bmc/kepler/Systems/${SystemId}/PCIeSlots/${ID}。

3. 组件架构说明 ​

3.1 整体架构设计 ​

本组件架构分为接口层、服务层、领域层和基础设施层四个层级。

1. 接口层：作为组件级的对外统一出口，通过RPC（资源协作）和IPMI两种方式提供跨模块交互能力。
2. 服务层：完成内部多个领域对象和外部其他服务之间协调性、组合性的交互逻辑。
   • device_service：设备管理服务，基于PCIeDevice、PCIeCard领域对象，对PCIe设备进行全生命周期管理（加载、查询、故障设置等）。
   • biztopo_service：业务拓扑服务，基于BizTopo、TopoMonitor、DeviceLoader领域对象，整合CSR节点信息构建业务Topo树。
3. 领域层：提供了PCIe设备、PCIe卡、业务TOPO树相关实体类的定义，承载核心业务逻辑。
   • biz_topo：承载业务TOPO的解析与建立，结合整机配置实现CPU与PCIe设备的建链。
   • topo_monitor：提供业务TOPO高速链路故障检测能力。
   • device_loader：基于业务TOPO链路，结合带内上报信息提供PCIe设备纳管和持久化机制。
   • PCIeDevice：对所有PCIe设备抽象出的类定义，承载PCIe总线属性和故障诊断标识。
   • PCIeCard：PCIe卡基本信息管理抽象类，不同类型PCIe卡通过继承拓展。
   • signal_manager：基于signal库的PCIe信号管理机制。
4. 基础设施层：提供对基础协议和通用功能点的封装。
   • common_tools：基于pcie_device业务特点的常用逻辑封装。
   • collection_helper、log_helper：集合库和日志收集库。

3.2 业务拓扑建立 ​

pcie_device组件通过对CSR中的SerDes、BusinessConnector对象和PSR中的UnitConfiguration对象进行解析和关联，建立从CPU到PCIe槽位的完整业务拓扑链路。

整体流程如下：

1. SerDes/BusinessConnector（CSR）、UnitConfiguration（PSR）对象分发加载。
2. BCU内部业务连接器与对应的CPU资源关联对接，IEU内部上行连接器与下行连接器关联对接。
3. 结合UnitConfiguration提供的高速线缆连接关系，将IEU侧业务连接器与BCU侧业务连接器建立联系。
4. 更新PcieAddrInfo对象的SlotID、PortID、SocketID、rootBDF等属性。

详细流程请参见拓扑建立开发指南。

3.3 PCIe设备加载 ​

PCIe设备加载依赖带内Host上报的BDF信息，通过BMC生成的丝印文件建立槽位与BDF的映射关系。

加载流程：

1. BMC拓扑建立完成，更新PcieAddrInfo属性（SlotID、PortID、rootBDF等）。
2. BIOS从BMC读取PcieAddrInfo生成丝印文件，带内Host获取丝印。
3. 带内Host通过IPMI命令上报设备BDF（按OCP卡/PCIe卡/NVMe盘分三次上报）。
4. 监听到Bios对象属性变化，使用设备BDF向IMU查询四元组（VID/DID/SubVID/SubDID）。
5. 通过四元组匹配Connector的Id/AuxId，设置Presence置位，触发框架自发现加载设备CSR。
6. 支持资源树方式（CSR v1.0）和设备树方式（CSR v2.0）两种加载模式。

详细流程请参见PCIe设备加载开发指南。

3.4 高速线缆检测 ​

通过SMC读取高速链路线缆连接信息，与PSR白名单配置进行比对，实现实时线缆连接检测。

检测流程：

1. 初始化端口状态和整机配置信息，识别合法检测区域。
2. 通过TOPO发现命令从SMC读取当前TOPO链路连接信息。
3. 将实时TOPO信息与PSR配置进行比对，分析设备接入状态。
4. 更新链路检测状态，存在非法连接则上报告警。

告警事件：

• 0x28000031 (Cable.UBIncorrectConnection)：线缆错插，BCU端连接正确但对端端口错误。
• 0x28000033 (Cable.UBNotPresent)：线缆漏插，实际连接线缆数少于配置要求。
• 0x28000035 (Cable.UnitNotSupported)：组件不支持，连接的端口不在白名单配置中。
• 0x2800003D (Cable.UnitUBNotPresent)：精细化漏插告警，定位到必插线缆的丝印。

详细流程请参见线缆检测开发指南。

3.5 关键类定义 ​

UnitConfiguration ​

承载BCU和IEU的连接关系（配置在PSR中），主要属性包括SlotType、SlotNumber、Configurations（包含SrcPortName、TargetPortID、Slot、Device等）。

SerDes ​

承载BCU组件内部的CPU资源配置，关键属性为Name、SocketID、LinkWidth、WorkMode、ModeConfigs（包含Device和ControllerIndex）。

BusinessConnector ​

业务连接器，有三种类型：

1. BCU下行连接器：连接SerDes与UBC/UBCDD端口。
2. IEU上行连接器：IEU侧的线缆端口。
3. IEU下行连接器：PCIe槽位连接器，关联PcieAddrInfo和框架Connector。

PcieAddrInfo ​

PCIe槽位信息，拓扑建立完成后更新SlotID、PortID、SocketID、Segment、rootBDF等属性。

3.6 PCIe设备故障诊断（RAS） ​

pcie_device组件提供完整的PCIe设备错误检测和诊断能力：

• FDM告警接口：设置各类错误标识（DiagnosticFault、PredictiveFault、UCEByBIOS、BandwidthReduction、LinkSpeedReduced）。
• RAS错误计数器：通过PCIeDevice.RAS接口提供FatalErrorCount、NonFatalErrorCount、BadDLLPCount、BadTLPCount、UnsupportedRequestCount、CorrectableErrorOverfrequencyCount等计数器，支持读取和清零。
• PCIeFunction粒度：在PCIeFunction对象上也提供RAS错误计数器，实现Function级别的故障诊断。
• IMU周期性查询：通过IMU周期性查询PCIe设备的速率和带宽信息，更新LinkSpeed、LinkWidth等属性。

4. 日志说明 ​

4.1 一键日志收集 ​

系统一键日志收集时，pcie_device组件相关日志文件如下：

4.2 关键日志信息 ​

5. 问题定界指南 ​

5.1 典型问题定界 ​

5.2 错误码速查表 ​

5.3 调试方法 ​

开启调试日志 ​

pcie_device组件的调试日志随app.log输出，日志级别由系统统一配置。在调试场景下，可通过以下方式增加日志获取量：

busctl --user call bmc.kepler.pcie_device /bmc/kepelr/compute/MicroComponent bmc.kepler.MicroComponent SetDlogLevel a{ss}sy 0 debug 2

PCIe卡不加载问题排查流程 ​

排查流程遵循PCIe设备加载开发指南中的流程图步骤：

1. 查看BDF上报情况
2. 查看带内设备存在情况
3. 查看丝印信息
4. 查看连接器信息置位情况
5. 查看是否能通过IMU获取四元组
6. 查看sr文件是否存在
7. 查看devmon是否发生coredump

6. 常见问题解答 ​

Q1：PCIe卡不加载如何排查？ ​

• 问题描述：PCIe设备插入槽位后在BMC侧不可见或状态异常
• 一句话答案：按BDF上报 → 丝印检查 → Connector置位 → IMU四元组获取 → SR文件存在的顺序排查
• 根因说明：可能是BDF未上报、丝印错误、IMU通信异常、SR文件缺失或框架加载异常
• 解决方案：按照排查流程图逐项检查
• 规避方案：重启BMC后如数据库有持久化BDF信息可恢复加载
• 适用版本：所有版本
• 相关文档链接：PCIe设备加载开发指南

Q2：丝印文件中的RootPortDeviceId和SlotId不匹配硬件预期？ ​

• 问题描述：BIOS生成的丝印文件中RootPortDeviceId或SlotId与硬件设计值不符
• 一句话答案：检查CSR中SerDes的Device配置和PSR中UnitConfiguration的Slot配置
• 根因说明：PortID来源于SerDes的Device值，SlotID来源于PSR的Slot数组，配置错误会导致丝印不正确
• 解决方案：核对CSR中SerDes的ModeConfigs.Device值与硬件预期一致，核对PSR中Configurations.Slot配置
• 适用版本：所有版本
• 相关文档链接：拓扑建立开发指南

Q3：线缆错插告警如何处理？ ​

• 问题描述：系统上报Cable.UBIncorrectConnection告警
• 一句话答案：检查对应BCU端口的SrcPortName连接的组件端口是否与PSR配置一致
• 根因说明：BCU端SrcPortName匹配但TargetPortID与配置不符
• 解决方案：调整线缆连接使SrcPortName与TargetPortID匹配PSR配置
• 适用版本：所有版本
• 相关文档链接：线缆检测开发指南

Q4：PCIe设备RAS错误计数器如何清零？ ​

• 问题描述：需要清除PCIe设备的错误计数器
• 一句话答案：通过PCIeDevice.RAS接口的写操作可以清零对应的错误计数器
• 根因说明：RAS错误计数器为ResetPer属性，系统复位或写操作可清零
• 解决方案：调用对应的属性写方法将计数器值写为0
• 适用版本：所有版本

Q5：资源树方式和设备树方式的卡加载有何区别？ ​

• 问题描述：PCIe卡加载在两种方式下表现不同
• 一句话答案：资源树方式由框架直接CSR分发加载，设备树方式需pcie_device监听devmon后手动创建对象
• 根因说明：资源树方式CSR FormatVersion为3.00，框架自动分发；设备树方式CSR FormatVersion为5.00，需devmon通知后手动创建PCIeDevice/PCIeCard对象
• 解决方案：根据sr文件的FormatVersion字段判断加载方式
• 适用版本：v1.0+

附录 ​

附录A 参考资料 ​

• 拓扑建立开发指南
• PCIe设备加载开发指南
• 线缆检测开发指南
• pcie_device源码仓库

附录B 修订记录 ​