PCIe Root Complex 这个东西在 x86 平台上你基本感知不到它的存在——BIOS 帮你把一切都配好了插上设备就能认。但一旦切到 Zynq UltraScale 这种嵌入式平台要让它当 RCRoot Complex去枚举下游的 EPEndpoint设备事情就完全不一样了PS 端的配置、PL 端的 IP 核参数、设备树里的 ranges 映射、中断控制器的级联每一环出问题都会让你卡在link up 了但枚举不到设备或者设备认到了但 BAR 地址全是 0xFFFFFFFF这种状态。我前后在 ZCU102 和自制的 MPSoC 板子上搭过三套 PCIe RC 环境踩的坑从 GT 参考时钟选错到设备树 ranges 少写一个 0 都有。这篇就把整个流程从头捋一遍重点放在那些文档里不会明说、但实际调试中一定会遇到的地方。不管你是刚拿到板子的新手还是已经跑通了 PetaLinux 但卡在设备树配置上的老手下面这些内容应该都能帮你省掉几个通宵。1. 先搞清楚 Zynq MPSoC 上 PCIe RC 的硬件拓扑1.1 PS 端 PCIe 控制器和 PL 端 IP 核的区别Zynq UltraScale 的 PCIe 实现有两条路可以走这一点必须先分清楚否则后面选型会走弯路。第一条路是用PS 端集成的 PCIe 控制器。MPSoC 的 PS 里硬核集成了 PCIe Gen2 x4 的控制器部分型号支持 Gen3它直接挂在 AXI 总线上通过 GTR 收发器对外连接。这条路的好处是不占 PL 资源、功耗低、驱动成熟PetaLinux 里直接有现成的xilinx-pcie驱动。缺点是通道数和 lane 数固定灵活性差。第二条路是用PL 端的 PCIe IP 核比如xdma或pcie4_uscale_plus。这条路灵活可以自己配 lane 宽度、可以做成 RC 也可以做成 EP但需要自己处理 GT 的复位时序、参考时钟、AXI 互联复杂度高不少。对于搭建 Root Complex这个需求绝大多数场景用的是 PS 端控制器。原因很简单你要的是让 MPSoC 去枚举和管理下游设备PS 端控制器配合 Linux 内核的pcie-xilinx-nwl或xilinx-pcie驱动就能完成不需要在 PL 里再搭一套。下面讨论的也主要是这条路。1.2 RC 模式下数据流是怎么走的理解数据流对调试至关重要。在 RC 模式下整个链路是这样的CPU 发起一个对下游 EP 设备 BAR 空间的读写请求请求经过 AXI 总线到达 PS 端的 PCIe 控制器控制器把 AXI 事务转换成 PCIe TLPTransaction Layer PacketTLP 经过 GTR 收发器、经过 PCB 走线到达 EP 设备EP 响应后原路返回这里的关键在于地址映射。CPU 看到的是 AXI 地址空间EP 设备看到的是 PCIe 地址空间两者之间需要一个转换关系。这个转换关系就是设备树里ranges属性定义的。很多人在这一步翻车就是因为没搞明白ranges里的三段地址分别代表什么。1.3 硬件设计阶段就要确认的几件事在动手写软件之前硬件原理图上这几项必须确认清楚检查项说明常见问题参考时钟频率GTR 的 REFCLK 是 100MHz 还是 125MHz配错直接 link 不上参考时钟来源来自专用时钟芯片还是 EP 端提供RC 模式下通常由 RC 侧提供PERST# 信号复位信号是否连接到 PS 的 MIO 或 PL 引脚没接的话 EP 无法正常复位lane 映射TX/RX 差分对是否交叉正确TX 接 TX 是经典错误电源时序EP 设备的电源和 PERST# 时序关系时序不对会导致枚举失败提示参考时钟这一项我要特别强调。ZCU102 上 PS 端 PCIe 的参考时钟默认是 100MHz来自 Si5332 时钟芯片。如果你用的是自制板一定要在 Vivado 的 PS 配置里把参考时钟频率设对否则 GT 根本锁不住。2. Vivado 里 PS 端 PCIe 控制器的配置细节2.1 PS 配置界面里那几个容易忽略的选项打开 Vivado 的 Zynq UltraScale MPSoC 配置界面在 PS-PCIe 这一栏里有几个参数需要仔细设置PCIe Controller 0/1 的选择MPSoC 有两个 PCIe 控制器Controller 0 通常映射到 GTR 的 Lane 0-3Controller 1 映射到 Lane 4-7。具体用哪个要看你的板子走线。Lane Width可以选 x1、x2、x4。注意这里选的是 RC 侧支持的最大宽度实际 link 宽度会在训练时协商。如果你只接了 x1 的设备这里选 x4 也没关系会自动降级。Reference Clock Frequency100MHz 或 125MHz必须和硬件一致。Max Link SpeedGen1 (2.5GT/s) 或 Gen2 (5GT/s)。调试阶段建议先设 Gen1稳定后再升 Gen2。2.2 AXI 地址空间的分配逻辑PS 端 PCIe 控制器需要几段 AXI 地址空间AXI-Lite 配置空间用于访问 PCIe 的配置寄存器通常分配 16MB 左右AXI 内存空间下游用于映射 EP 设备的 BAR 空间大小取决于你要接多少设备AXI 内存空间上游/DMA如果 RC 要主动 DMA 到 EP需要这段在 Vivado 的 Address Editor 里这些空间会自动分配但你要检查是否有重叠。我遇到过因为地址空间重叠导致内核启动时直接 hang 住的情况。2.3 生成 XSA 之前的检查清单在 Export Hardware 之前确认以下几点PS 端 PCIe 控制器的时钟已经使能GTR 的参考时钟源选择正确中断已经连接到 GICPL-PS 中断或 PS 内部中断Address Editor 里没有地址冲突黄色警告要处理如果用了 PL 端的中断聚合确认pl_ps_irq已经连接导出 XSA 后就可以进入 PetaLinux 环节了。3. PetaLinux 工程配置与内核选项3.1 创建工程和设备树的初始配置petalinux-create -t project -s xsa文件路径 -n pcie_rc_demo cd pcie_rc_demo petalinux-config --get-hw-description./在petalinux-config的菜单里需要关注这几项Subsystem AUTO Hardware Settings→ 确认 PCIe 相关的硬件信息已经被正确导入DTG Settings→ 设备树生成器的配置后面会用到Image Packaging Configuration→ 确认 rootfs 类型3.2 内核配置里必须打开的选项petalinux-config -c kernel需要确认以下配置项CONFIG_PCIy CONFIG_PCI_MSIy CONFIG_PCIEPORTBUSy CONFIG_PCIE_XILINX_NWLy # 如果用 NWL 驱动 CONFIG_PCIE_XILINXy # 如果用旧版 xilinx-pcie 驱动 CONFIG_PCI_MSI_IRQ_DOMAINy CONFIG_PCI_HOST_GENERICy # 某些情况下需要具体用哪个驱动取决于你的 Vivado 版本和 PS 配置。2019.1 之后的版本通常用pcie-xilinx-nwl更早的版本用xilinx-pcie。选错了驱动内核启动时 PCIe 控制器根本不会初始化。3.3 设备树里 PCIe 节点的关键属性这是整篇文章的核心部分。PetaLinux 生成的设备树里PCIe 节点大概长这样pcie { status okay; reset-gpios gpio 38 GPIO_ACTIVE_LOW; interrupt-map-mask 0 0 0 7; interrupt-map 0 0 0 1 pcie_intc 0, 0 0 0 2 pcie_intc 1, 0 0 0 3 pcie_intc 2, 0 0 0 4 pcie_intc 3; pcie_intc: interrupt-controller { interrupt-controller; #address-cells 0; #interrupt-cells 1; }; };看起来不复杂但每个属性都有讲究。下面逐个拆解。4. 设备树配置的深水区ranges、中断和复位4.1 ranges 属性的三段地址到底怎么填ranges是设备树里最容易出错的地方。它的格式是ranges flags child_address parent_address size;对于 PCIe 节点通常有两段 ranges一段是配置空间一段是内存空间。ranges 0x02000000 0x0 0xE0000000 0x0 0xE0000000 0x0 0x10000000, 0x43000000 0x80 0x00000000 0x80 0x00000000 0x0 0x80000000;第一段0x02000000表示 32 位内存空间child 地址0xE0000000parent 地址也是0xE0000000大小0x10000000256MB。第二段0x43000000表示 64 位预取内存空间。踩坑点child 地址和 parent 地址不一定要相同但如果你不确定设成相同是最安全的。另外 size 字段的位数要和#size-cells匹配PCIe 节点的#size-cells通常是 2所以 size 要写成两个 cell。4.2 中断映射的级联关系PCIe 的中断是级联的EP 设备的 INTx 中断先到 PCIe 控制器的中断控制器pcie_intc然后再映射到 GIC。interrupt-map就是定义这个映射关系的。interrupt-map-mask 0 0 0 7; interrupt-map 0 0 0 1 pcie_intc 0, 0 0 0 2 pcie_intc 1, 0 0 0 3 pcie_intc 2, 0 0 0 4 pcie_intc 3;interrupt-map-mask是0 0 0 7意味着只匹配最后一个 cell 的低 3 位也就是 INTx 的编号 1-4。前面的 0 表示不关心设备号和功能号。如果这里配错了表现是设备能枚举到但中断收不到。调试时可以看/proc/interrupts里有没有对应的 PCIe 中断条目。4.3 reset-gpios 的极性和时序reset-gpios定义的是 PERST# 信号。这里有两个坑极性GPIO_ACTIVE_LOW表示低电平有效也就是拉低时复位。但有些板子的电路上加了反相器实际极性可能相反。如果内核启动时 EP 设备一直枚举不到先查这个。时序PCIe 规范要求 PERST# 在参考时钟稳定后至少保持 100ms 的低电平。内核驱动通常会处理这个时序但如果你用的是自定义 GPIO可能需要自己加延时。4.4 一个完整的设备树配置示例把上面的内容整合起来一个可用的 PCIe RC 设备树节点是这样的pcie { status okay; compatible xlnx,nwl-pcie-2.11; reg 0x0 0xfd0e0000 0x0 0x1000, 0x0 0xfd480000 0x0 0x1000, 0x80 0x00000000 0x0 0x1000000; reg-names breg, pcireg, cfg; interrupts 0 151 4, 0 152 4, 0 153 4, 0 154 4; interrupt-names misc, msi0, msi1, legacy; interrupt-map-mask 0 0 0 7; interrupt-map 0 0 0 1 pcie_intc 0, 0 0 0 2 pcie_intc 1, 0 0 0 3 pcie_intc 2, 0 0 0 4 pcie_intc 3; msi-parent pcie_intc; ranges 0x02000000 0x0 0xE0000000 0x0 0xE0000000 0x0 0x10000000, 0x43000000 0x80 0x00000000 0x80 0x00000000 0x0 0x80000000; pcie_intc: interrupt-controller { interrupt-controller; #address-cells 0; #interrupt-cells 1; }; };注意reg属性里的三段分别对应 breg桥寄存器、pciregPCIe 控制器寄存器和 cfg配置空间。这些地址来自 Vivado 的 Address Editor不能随便填。5. 上电调试从 link up 到设备枚举的完整排查链路5.1 第一步确认 link 是否建立系统启动后第一件事是看 link 状态cat /sys/kernel/debug/pcie/link_status # 或者 lspci -v如果lspci什么都不显示说明 link 没建立。这时候要查GT 参考时钟是否正常用示波器量PERST# 是否已经释放拉高LTSSM 状态机的状态有些驱动会打印5.2 第二步link up 了但枚举不到设备这是最常见的情况。link 建立了但lspci里看不到设备。原因通常有配置空间访问失败检查ranges里的配置空间地址是否正确EP 设备没有正常初始化有些 EP 需要额外的初始化序列地址映射错误BAR 地址读出来是 0xFFFFFFFF排查方法# 查看 PCIe 控制器的寄存器状态 devmem 0xFD0E0000 # 查看内核日志 dmesg | grep -i pcie5.3 第三步设备认到了但 BAR 分配失败如果lspci能看到设备但 BAR 地址是 0xFFFFFFFF 或者分配失败问题在ranges的内存空间配置。检查ranges里的 size 是否足够大是否有地址冲突和其他外设的地址空间重叠内核的pcirealloc参数是否需要加上5.4 第四步中断收不到设备能正常工作但中断不触发检查cat /proc/interrupts | grep pcie如果没有 PCIe 相关的中断条目说明interrupt-map配置有问题。另外要注意 MSI 和 INTx 的区别现代设备通常用 MSI/MSI-X需要确认msi-parent指向正确。5.5 一个真实的排查案例我之前遇到过一块自制板link up 正常lspci能看到设备但读写 BAR 空间时系统直接挂死。排查过程先确认 link 状态 → 正常确认设备枚举 → 正常读写 BAR → hang最后发现是ranges里的内存空间地址和 DDR 的地址范围重叠了。CPU 访问那个地址时AXI 互联不知道该路由到 DDR 还是 PCIe导致总线死锁。把 PCIe 的内存空间改到0xE0000000之后问题解决。这个案例说明ranges 里的地址不能和系统中其他设备的地址空间重叠这是硬性要求。6. 几个能省你大量时间的实操技巧6.1 用 lspci 的 -vvv 看详细信息lspci -vvv这个命令能看到每个设备的 BAR 分配、中断信息、link 状态、协商速率等。调试阶段建议一直开着。6.2 通过 sysfs 直接读写配置空间# 读取配置空间 hexdump -C /sys/bus/pci/devices/0000:01:00.0/config # 写配置空间谨慎操作 echo value /sys/bus/pci/devices/0000:01:00.0/config6.3 内核启动参数里加上 pci 调试信息在bootargs里加上pciverbose pciearlydump这样内核启动时会打印详细的 PCIe 枚举过程方便定位问题。6.4 用 devmem 直接读 PCIe 控制器寄存器# 读取 PCIe 控制器的 link 状态寄存器 devmem 0xFD0E0000 32具体的寄存器偏移要看 Xilinx 的文档UG1085。这个方法在驱动还没加载起来的时候特别有用。6.5 设备树修改后的快速验证流程每次改完设备树不需要重新编译整个系统# 只重新编译设备树 petalinux-build -c device-tree # 把生成的 dtb 拷贝到 SD 卡 cp images/linux/system.dtb /media/sdcard/ # 重启后在 u-boot 里手动加载新的 dtb这样可以节省大量编译时间。7. 关于驱动选型和版本兼容性的经验7.1 nwl-pcie 和 xilinx-pcie 的区别Xilinx 的 PCIe 驱动有两个版本xilinx-pcie旧版驱动支持 Gen1/Gen2代码简单但功能有限nwl-pcie新版驱动基于 Northwest Logic 的 IP支持更多特性是 2019.1 之后的默认选择选哪个取决于你的 Vivado 版本和 PS 配置。如果内核启动时看到xilinx-pcie: probe failed之类的错误大概率是驱动选错了。7.2 内核版本对 PCIe 支持的影响不同版本的 PetaLinux 使用的内核版本不同PCIe 子系统的行为也有差异。比如PetaLinux 版本内核版本PCIe 驱动注意事项2018.34.14xilinx-pcie需要手动配置 ranges2019.24.19nwl-pcie默认配置基本可用2020.25.4nwl-pcie支持 Gen32021.25.10nwl-pcie设备树节点有变化如果你在升级 PetaLinux 版本后 PCIe 不工作了先检查设备树节点的 compatible 属性是否匹配新驱动的要求。7.3 关于 MSI 中断的配置现代 PCIe 设备基本都用 MSI/MSI-X 中断。在设备树里msi-parent属性指向 MSI 控制器msi-parent pcie_intc;如果 MSI 不工作设备可能会回退到 INTx但性能会差很多。检查/proc/interrupts里是否有 MSI 中断条目。8. 写在最后的一些个人体会搭 PCIe RC 这件事硬件和软件的耦合度非常高。我见过太多人软件调了半天最后发现是硬件上参考时钟没接对。所以我的建议是先确认硬件没问题再动软件。具体来说上电后先用示波器确认参考时钟、PERST# 和电源时序这三样没问题了再开始调软件。另外设备树这个东西改的时候一定要小步走。每次只改一个属性改完就验证。我见过有人一次性改了 ranges、中断和复位三个地方结果出问题了根本不知道是哪个引起的。还有一点Xilinx 的文档特别是 UG1085 和 PG201一定要看但不要全信。文档里的示例代码和实际能跑的代码之间往往有差距以实际调试结果为准。最后说一个我踩过的坑有一次用 PetaLinux 2020.2 搭 RC设备树里ranges的 64 位内存空间地址写成了0x0 0x00000000结果内核启动时直接 panic。原因是这个地址和系统 RAM 的起始地址冲突了。改成0x80 0x00000000之后正常。这个教训告诉我64 位地址的高 32 位不能随便填 0要根据实际的地址映射来。