Linux PCIe驱动probe不触发？从枚举到稳定性的排查指南

简介面向 Linux 下 PCIe 驱动开发与 Xilinx FPGA 应用场景这套代码包主要服务于内核驱动开发者、FPGA 工程师以及需要为 Xilinx 器件移植驱动的嵌入式人员。内容覆盖 PCIe 设备枚举、资源分配、总线驱动与设备驱动分层、probe 设备匹配、中断注册、DMA 掩码设置、ioremap 地址映射、固件加载和模块卸载清理等环节适合从整体上把握 Linux PCIe 驱动框架。包内共 27 个文件以 C 源码和头文件为主体另有 Makefile 构建脚本、运行结果记录和 logo 示意图整体仅 124KB便于快速阅读和对照编译。已有 1227 人学习下载。借助 xdma 驱动骨架、用户态 sysfs/ioctl 交互接口和调试辅助文件读者可以了解 lspci、dmesg、ethtool 等工具的观察点并通过内核日志定位初始化失败原因掌握从设备匹配到数据通路建立的排错思路为后续裁剪或移植 Xilinx PCIe 驱动提供一个可落地的起点。1. Linux PCIe 驱动为什么 probe 进不来比怎么写代码更值得先搞清楚把 linux_driver.rar 解压、make 出一个 .koinsmod 显示加载成功但 lspci -k 里就是没有你的驱动名probe 死活不调用——这是 Linux PCIe 驱动开发最常见的第一道坎。标题这套组合词linux pcie 驱动 / pcie driver / linux驱动pcie问的就是一件事怎么让一块 PCIe 设备网卡、加速卡、采集卡在 Linux 里被识别、被驱动起来并能稳定地做 DMA 和中断。我按实际调板卡的顺序来写先讲枚举与 pci_driver 骨架再讲编译与匹配最后落到热插拔、AER 和稳定性排查。适合正在做板卡 bringup、写内核模块或者拿到别人的 linux_driver.rar 想快速跑起来的人。2. 从枚举到 probeLinux PCIe 驱动是怎么找到你的设备的很多人拿到驱动源码第一反应是读 probe 函数但 probe 之所以能被调用依赖的是内核在启动阶段完成的 PCIe 总线枚举。不理解枚举你连报错日志都不知道去哪里看。2.1 pcie枚举过程配置空间、BDF 与设备树驱动作者必须知道的三个事实PCIe 是树形总线。系统上电后Root Complex 从 Bus 0 开始向每个 Device/Function 组合读 Vendor ID读到 0xffffffff 就认为槽位为空继续扫下一个。扫描完成后给设备分配 BDFBus:Device.Function、BAR 地址和中断号这就是整个 pcie枚举过程。你看到的 lspci 输出就是内核把枚举结果解析成人话。第二个事实是配置空间。标准配置空间前 256 字节兼容 PCIBAR0~5 在 0x10~0x24Capability 链表指针在 0x34。MSI、MSI-X、PM、AER 这些能力全部通过 Capability 结构暴露而探寻它们不是用指针访问而是用 pci_read_config_byte/word/dword 系列接口。扩展配置空间到 4KBAER 的更多状态在 0x100 之后lspci -vvv 输出的就是内核解析完的配置空间摘要。第三个事实和平台相关。x86 下 PCIe 控制器由 ACPI 描述ARM 平台则常见设备树里的 pcie 节点compatible 通常写 pcie-host-ecam-generic配合 bus-range、ranges、dma-ranges、msi-map 描述总线范围和地址映射。如果在设备树平台调驱动prpbe 之前得先确认 dts 里有没有这个节点不然内核根本不会去扫描这条总线。先用这三条命令确认设备到底在不在系统里# 看整棵 PCIe 树拓扑确认设备挂在哪条总线 lspci -tv # 看单个设备的能力和当前链路状态 lspci -vvv -s 01:00.0 # 打印 vendor:device驱动匹配 id_table 用的就是这两个数字 lspci -n -s 01:00.0lspci -tv 输出里能看到 Root Port、Switch、Endpoint 的层级关系lspci -vvv 能看到 LnkCap/LnkSta、MSI 能力、BAR 大小lspci -n 给出的 1234:5678 这样的编号直接对应驱动里 pci_device_id 表的 vendor/device。我一般先跑这三条再决定要不要继续读源码。2.2 最小可用的 pci_driver 骨架id_table、probe 与 remove 的正确写法注册一个 PCIe 驱动内核不看 module_init只看你的 pci_driver 结构体。下面是一个最小但完整可编译的骨架虚拟 vendor 0x1234、device 0x5678。#include linux/module.h #include linux/pci.h #define DRV_NAME my_pcie_driver static int my_pcie_probe(struct pci_dev *pdev, const struct pci_device_id *id) { int ret; // 1. 使能设备打开 MMIO/IO 访问和总线主控能力 ret pci_enable_device(pdev); if (ret) return ret; // 2. 使能 bus masteringDMA 必需只做 PIO 可以不加 pci_set_master(pdev); // 3. 申请配置空间里的资源BAR避免与其他驱动冲突 ret pci_request_regions(pdev, DRV_NAME); if (ret) { pci_disable_device(pdev); return ret; } // 4. 映射 BAR0 到内核虚拟地址空间 void __iomem *bar0 pci_ioremap_bar(pdev, 0); if (!bar0) { pci_release_regions(pdev); pci_disable_device(pdev); return -ENOMEM; } dev_info(pdev-dev, probe: vendor%04x device%04x bar0%px\n, id-vendor, id-device, bar0); return 0; } static void my_pcie_remove(struct pci_dev *pdev) { dev_info(pdev-dev, remove\n); pci_disable_device(pdev); } static const struct pci_device_id my_pcie_ids[] { { PCI_DEVICE(0x1234, 0x5678) }, { } }; MODULE_DEVICE_TABLE(pci, my_pcie_ids); static struct pci_driver my_pcie_driver { .name DRV_NAME, .id_table my_pcie_ids, .probe my_pcie_probe, .remove my_pcie_remove, }; module_pci_driver(my_pcie_driver); MODULE_LICENSE(GPL);核心逻辑在最后一行module_pci_driver 宏自动生成 module_init/module_exit把 pci_driver 注册进内核的 PCI 总线。probe 在设备与 id_table 匹配时被调用remove 在设备拔出或驱动卸载时被调用。id_table 必须用空条目结尾这个空条目表示“表结束”漏掉它内核会越界读编译能过但运行时会翻车。参数说明PCI_DEVICE(0x1234, 0x5678) 宏检查 vendor 和 device 都相等如果只知道 vendor可以用 PCI_DEVICE 只填 vendor 再配合 .class 字段做粗匹配。pci_enable_device 内部会设置 Command 寄存器的 Memory/IO 位和 Bus Master 位所以顺序一定是先 enable 再 request_regions 再 ioremap。probe 失败时要把前面已经成功申请的逆序释放很多人只写 pci_enable_device 成功分支忘了失败分支也返回错误码导致设备虽然报错却已被标记为“驱动绑定中”后续重试和 lspci -k 表现都很奇怪。3. 把驱动编进内核或独立编译Kconfig、Makefile 与模块加载驱动源码拿到手真正第一笔开销往往在编译环境。内核模块和外层应用程序不一样它编译时依赖运行内核的构建目录版本不一致会出现各种匪夷所思的报错这个环节我先讲清楚怎么搭。3.1 把 linux_driver.rar 跑成 .ko外部模块 Makefile 与三个关键点如果你拿到的是 linux_driver.rar 这类打包解压后里面一般有源码和厂商自带 Makefile。先别急着 make先确认两件事源码树的 include 路径和你当前内核是否匹配以及 obj-m 是否指定了正确的目标名。大多数情况下自带的 Makefile 需要依赖内核构建目录也就是下面这个变量KVER ? $(shell uname -r) KDIR ? /lib/modules/$(KVER)/build obj-m my_pcie_driver.o all: $(MAKE) -C $(KDIR) M$(PWD) modules clean: $(MAKE) -C $(KDIR) M$(PWD) clean这个 Makefile 的逻辑是切换到内核构建目录执行 modules 目标同时把当前目录作为 M 参数传入。内核的 kbuild 系统会编译当前目录下所有 obj-m 指定的模块目标。my_pcie_driver.o 这个名字必须和源码文件名一致如果你的源文件是 pcie_main.c就写 obj-m pcie_main.o而不是乱改目标名。参数说明KDIR 指向 /lib/modules/$(uname -r)/build这个目录是一个符号链接真正指向内核头文件与构建中间文件所在位置。装完内核头文件包才有这个链接否则 make 会报 “no such file or directory”。常见的做法是在 Ubuntu 系先装 linux-headers-$(uname -r)在嵌入式环境则直接让 KDIR 指向你交叉编译用的内核源码树。编译产物是 my_pcie_driver.ko接下来按顺序加载# 加载模块建议先看 dmesg 尾部输出 sudo insmod my_pcie_driver.ko dmesg | tail -20 # 查看模块是否真的绑定了设备 lspci -k -s 01:00.0如果 lspci -k 的 Kernel driver in use 显示 my_pcie_driver说明 probe 成功如果显示设备没有驱动probe 没被调用或者调用后失败了。insmod 只看模块本身加载不保证设备绑定很多新手在这里误判“驱动已经加载成功”。想让 modprobe 自动装载需要把 .ko 拷贝到 /lib/modules/$(uname -r)/extra/然后执行 depmod -a后续用 modprobe my_pcie_driver 加载。3.2 probe 不触发的排查顺序id_table、CONFIG_PCI_DEBUG 与 driver_override这一节是无数人的共同痛点。按下面顺序排查能解决九成 probe 失联问题。# 第一步确认设备真实 id lspci -n -s 01:00.0 # 第二步看内核有没有报绑定相关日志 dmesg | grep -i pci | tail -30 # 第三步确认驱动是否注册成功 ls /sys/bus/pci/drivers/my_pcie_driver/第一个坑是 vendor/device 对不上。厂商手写 id_table 时经常把 device id 写错一位尤其是转贴过来的驱动源码。用 lspci -n 看真实编号对照驱动里 PCI_DEVICE 的参数这是最快的定位。第二个坑是内核开了 CONFIG_PCI_DEBUG 才能打印更多匹配信息如果没开dmesg 里可能什么都没有。第三个坑是设备被其他驱动或 pci_stub 抢先占了lspci -k 会显示另一个驱动的名字解决方法是先卸载那个驱动或者用 driver_override 强制绑定。第四个坑在设备树平台。设备树里的 compatible 要和驱动里的 of_match_table 对得上否则即使 id_table 正确probe 也可能因为 of_node 匹配失败而绕开。常见做法是在驱动里同时提供 pci_device_id 和 of_device_id并让 .driver.of_match_table 指向后者。最后一个坑是驱动编译进了内核而不是模块但设备在 init 之后才出现probe 时机对不上。如果设备是后插的驱动需要在子系统注册时重新扫描这时 driver_override 配合 echo 到 /sys/bus/pci/drivers_probe 可以把设备重新“踢”进探测流程。我一般建议把排查顺序固定成一条命令链先 lspci -n 对 id再 dmesg 扫错误最后看 /sys/bus/pci/drivers 下的绑定关系。这比反复 insmod/rmmod 高效得多。4. 热插拔与 AERPCIe 驱动稳定性的两道坎驱动能 probe 只是开始。PCIe 设备真正上线后死在热插拔和错误处理上的概率比死在初始化上的高得多。初始化崩了是搞笑段子remove 崩了才是线上事故。4.1 pcie热插拔功能为什么是驱动杀手remove、shutdown 与电源管理回调PCIe 热插拔分成两种场景一种是系统管理的热插拔由 hotplug 驱动控制槽位供电和复位顺序可控另一种是 surprise removal卡被直接拔掉内核甚至来不及通知你驱动代码正在访问的设备瞬间从总线上消失。对驱动作者来说内核只保证一点设备还在总线上的时候remove 会被调用资源释放顺序必须严谨。常见的 remove 清理顺序如下这个顺序不能乱static void my_pcie_remove(struct pci_dev *pdev) { struct my_dev *dev pci_get_drvdata(pdev); // 1. 先摘中断确保没有新中断进来 free_irq(pdev-irq, dev); // 2. 等待可能还在跑的工作队列 cancel_work_sync(dev-work); // 3. 释放 BAR 映射 pci_iounmap(pdev, dev-bar0); // 4. 释放配置空间资源 pci_release_regions(pdev); // 5. 关闭设备 pci_disable_device(pdev); }顺序的逻辑是中断处理函数和工作队列都会读写硬件如果先 iounmap 再 free_irq中断来临时访问已释放的映射轻则报错重则触发不可纠正错误。free_irq 还附带一个语义它同步等待所有执行中的中断处理函数返回所以放在第一步等于把并发入口先关掉。IRQF_SHARED 共享中断场景下free_irq 的第三个参数 dev_id 必须和 request_irq 传的完全一致否则内核无法区分是你的中断还是别人的。电源管理回调同样容易被忽略。完整驱动应该在 suspend 里做 pci_save_state 和 pci_set_power_state在 resume 里做 pci_restore_state 和重新使能。缺了这组回调系统休眠再唤醒后经常出现设备无法访问、DMA 不工作、链路掉速这类“玄学问题”实际上只是上下电时序没人管。4.2 AER 与链路降速掉卡、降 speed/lane 的正确诊断姿势AER 是 PCIe 的进阶错误报告机制分 Corrected 和 Uncorrected 两类。Uncorrected 又分 Fatal 和 Non-Fatal。内核里 AER 驱动负责接收和处理这些错误部分错误会导致内核直接把设备从系统中隔离表现就是驱动还在设备已经没了。掉卡和降速是 PCIe 稳定性问题的高频词。降速指的是链路协商从 Gen3 x4 掉到 Gen2 x1甚至 Gen1 x1掉卡则是设备从 lspci 输出里消失。这两类问题先查三样东西# 查当前协商速度和宽度 lspci -vvv -s 01:00.0 | grep -E LnkCap|LnkSta # 查 AER 错误日志 dmesg | grep -i PCIe Bus Error | tail -20 # 查设备是否还挂在总线上 lspci -s 01:00.0LnkSta 显示 Speed 8GT/s、Width x4说明链路健康如果变成 2.5GT/s、x1多半是信号完整性或电源问题驱动里改参数解决不了。AER 日志出现 Corrected 大量累积常见原因是 PCIe 参考时钟的 SSC 展频配置不一致或者连接器/金手指氧化接触不良。有的卡本身被锁在 PCIe 2.0 x1 上比如一些矿卡改的显卡那是固件限制驱动再怎么写也不会超速不必浪费时间。在 x86 平台排查链路问题我一般会先用内核启动参数关掉 ASPM 做对照实验pcie_aspmoff。如果关闭后掉卡频率明显下降说明是电源管理链路训练和板卡兼容性的问题优先查 BIOS 设置和板端供电而不是驱动。驱动侧能做的补救是在 suspend/resume 后重新确认链路状态必要时重新初始化 DMA 描述符。AER 注入测试在支持 CONFIG_PCIEAER_INJECT 的内核里可以做但线上排查用 dmesg 加 lspci 已经够定位九成问题。5. 避坑PCIe 驱动稳定性最常见的 5 个问题现象、原因、解决这一章全是实战里反复出现的翻车点每条都按现象、原因、解决三步写。遇到过的人会庆幸早看见没遇到过的会在某个深夜突然明白。5.1 probe 成功但 remove 就崩溃现象模块卸载或设备热拔出时系统报空指针、内核 panic或者 remove 之后设备在 lspci 里变成半死状态。原因probe 里用了 devm_kzalloc 分配私有数据又手动在 remove 里 kfree 了一次。devm 类函数注册的资源在设备销毁时自动释放重复释放导致双重释放。另一种常见原因是 probe 里写死了 bar0 映射但 remove 里 pci_iounmap 之前已经释放了私有结构体后续 dev_info 访问空指针。解决私有数据全部用 devm_kzalloc中断用 devm_request_irqBAR 映射用 devm_ioremap然后 remove 里什么都不用做只做非 devm 资源的清理。如果坚持手动管理就做一个约定probe 失败的每个错误分支都逆序回滚remove 只释放 probe 成功路径里申请过的东西。5.2 中断申请失败后设备处于半开状态现象probe 返回 -EIO模块加载失败但之后 lspci -k 显示设备仍被这个驱动绑定怎么 insmod 都不再触发 probe。原因probe 里先 pci_enable_device 成功再 request_irq 失败返回错误码之前没有调用 pci_disable_device。内核认为设备已经和驱动绑定后续重新探测时发现已有驱动持有该设备不再调用 probe。解决把 probe 改成单出口模式用 goto err 标签统一回滚失败分支一定执行 pci_disable_device 和 pci_release_regions。顺手养成习惯probe 成功最后再用 pci_set_drvdata 保存私有数据避免中间态。5.3 DMA 地址被截断数据写到了错误位置现象DMA 传输能完成但目标内存里的数据是乱的或者 DMA 写坏了附近的内存。原因没有调用 dma_set_mask_and_coherent。内核默认 DMA 掩码是 32 位如果设备支持 64 位地址而驱动没设置高地址被截断硬件拿到的是错位地址。解决probe 里尽早加上ret dma_set_mask_and_coherent(pdev-dev, DMA_BIT_MASK(64)); if (ret) ret dma_set_mask_and_coherent(pdev-dev, DMA_BIT_MASK(32));同时用 dma_alloc_coherent 或 pci_alloc_consistent 分配 DMA 缓冲区而不是普通 kmalloc。kmalloc 出来的内存物理地址不连续做分散聚合时更容易出错。5.4 读 BAR 触发 Uncorrected整个系统直接挂起现象probe 一执行 readl/ioread32dmesg 瞬间刷出 Uncorrected (Non-Fatal) 或直接死机。原因resource 冲突BAR 对应的物理地址被其他驱动或内核子系统占用pci_request_regions 返回了错误但驱动没检查照样 ioremap 访问。解决probe 里必须检查 pci_request_regions 的返回值失败就返回错误。排查时先 lspci -vvv 看 BAR 地址范围再用 lspci -xxx 看配置空间确认 BAR 是否被正确分配。如果板子和别人共用内存映射区检查设备树里有没有预留对应地址段。5.5 热插拔后中断处理函数还在跑设备已经不在了现象拔卡瞬间系统 panic日志停在中断处理函数附近的地址。原因中断处理函数没有持有设备状态锁remove 已经把设备标记为移除中断线仍被触发。对于 surprise removal物理上设备已消失中断处理里读 BAR 直接触发总线错误。解决中断处理函数第一步检查设备是否还在线配合 dev-removed 标志位remove 里先置标志、再 free_irq、再 cancel_work_sync。如果硬件支持套用 pci_channel_io_normal/io_error 状态机判断链路健康比裸读寄存器安全。6. 进阶验证从 lspci 到仿真压测确认驱动真的可靠驱动写完只是第一步真正要回答的是“它能不能在长时间、高负载、热插拔下不翻车”。我一般把验证拆成四层从配置空间一直压到故障注入。第一层验证配置空间和 BAR 映射。用 lspci -vvv 核对寄存器能力用 devmem 读 BAR 对应的物理地址确认硬件寄存器值和驱动读到的一致。这一步能抓出 BAR 偏移算错、ioremap 地址错误、寄存器位宽读错三类基础问题。第二层验证中断和 DMA 在压力下的稳定性。跑 DMA 压测的同时观察中断计数# 压测前 grep my_pcie_driver /proc/interrupts # 连续读写几 GB 数据后再看一次 grep my_pcie_driver /proc/interrupts中断次数应随数据量线性增长如果卡住或增长异常多半是中断丢失或 DMA 描述符更新失败。压测时同时查 dmesg 里有没有被 AER 上报的 Corrected 错误累积速度异常就要回头查链路。第三层是故障注入。支持 CONFIG_PCIEAER_INJECT 的内核可以把构造的 AER 错误注入到设备验证驱动在收到不可纠正错误后能否正确进入错误分支而不是 panic。常见做法是触发一次 Non-Fatal 错误观察驱动是重试、复位设备还是优雅失败。第四层是仿真。逻辑层面用 QEMU 的 q35 机型模拟 PCIe 拓扑可以观察枚举和热插拔行为FPGA 场景下Xilinx PCIe IP 的仿真环境能提前验证链路训练和 BAR 访问逻辑不用等板卡回来。真机上配合 ftrace 跟踪 irq_handler_entry 和 pci_probe 的调用时间能看出性能瓶颈是在驱动还是硬件。前几年我调一块 FPGA 加速卡时probe 里 ioremap 后直接 readl 读状态寄存器一读就触发 Uncorrected查了两天发现是另一个驱动占了这段 BAR 地址而 pci_request_regions 返回错误时我没检查返回值硬是访问了别人的资源。从那以后我每次板卡 bringup 都先用 lspci -xxx 核对配置空间再写驱动宁可慢十分钟也不要深夜 debug。希望帮到你。本文还有配套的精品资源点击获取