Linux PCI 驱动框架详解：从设备树到 probe 的完整指南

1. 从设备树到 probePCI 驱动到底在什么时候接管硬件很多人第一次看 Linux PCI 驱动代码都会被一堆pci_driver、pci_device_id、probe、remove绕晕。明明字符设备驱动那套file_operations已经够用了为什么 PCI 设备还要多一层框架我刚开始接触这块的时候也有同样的疑问直到自己在板子上接了一块 PCIe 网卡才发现如果不理解 PCI 框架连设备什么时候被系统识别、驱动什么时候被调用都说不清楚。这一篇接着上一部分继续往下拆。上一篇我们主要聊了 PCI 总线的拓扑结构、配置空间、BAR 空间这些偏底层的概念这一篇重点放在驱动框架本身一个 PCI 驱动从注册到被调用中间到底经历了什么probe函数里该做什么、不该做什么以及实际调试时最容易踩的坑。先把结论摆出来Linux PCI 驱动框架本质上是一套总线-设备-驱动模型的典型实现。总线负责匹配设备负责描述自己驱动负责在匹配成功后接管硬件。听起来简单但真正写起来细节非常多。尤其是当你面对的是pci express root port、多 BAR 设备、MSI 中断这些场景时稍不注意就会掉进坑里。这篇文章适合已经写过简单字符设备驱动、想进一步理解 PCI 子系统的朋友也适合做嵌入式 Linux、服务器驱动开发、国产化平台适配的同行参考。我会尽量用大白话把机制讲清楚同时给出可以直接抄的代码骨架和调试命令。2. PCI 驱动框架的整体设计与匹配逻辑2.1 为什么 PCI 驱动不能像字符设备那样直接注册字符设备驱动的套路大家都熟申请设备号、注册cdev、实现file_operations用户空间open的时候就能找到你。但 PCI 设备不一样它有几个天然特点决定了不能这么干。第一PCI 设备是可枚举的。系统启动时PCI 总线会扫描整条总线读取每个设备的配置空间知道有哪些设备、厂商 ID、设备 ID 是多少。这个信息是硬件层面自动获取的不需要驱动去猜。第二PCI 设备可能热插拔。尤其是 PCIe支持热插拔的场景越来越多设备可能在你驱动已经加载之后才出现也可能在运行中消失。这就要求驱动框架必须支持动态匹配和动态卸载。第三一个 PCI 设备可能有多个功能function每个功能有自己的配置空间和 BAR。比如一块双口网卡可能就是两个 PCI function需要分别匹配驱动。基于这些特点Linux 采用了pci_driver结构体来抽象 PCI 驱动核心字段包括static struct pci_driver my_pci_driver { .name my_pci_dev, .id_table my_pci_ids, .probe my_pci_probe, .remove my_pci_remove, };其中id_table是关键它告诉内核我这个驱动能支持哪些设备。内核在枚举到新 PCI 设备时会拿设备的 vendor/device ID 去和所有已注册驱动的id_table比对匹配成功就调用对应的probe。这种设计的妙处在于驱动不需要关心设备什么时候出现只需要声明自己能支持什么。匹配这件事交给总线层去做驱动只管在probe里干活。这就是总线-设备-驱动模型的核心思想。2.2 id_table 的匹配规则与常见写法pci_device_id结构体看起来字段不少但常用的就几个static const struct pci_device_id my_pci_ids[] { { PCI_DEVICE(0x1234, 0x5678) }, { PCI_DEVICE_CLASS(PCI_CLASS_NETWORK_ETHERNET, 0xffffff) }, { 0, } }; MODULE_DEVICE_TABLE(pci, my_pci_ids);PCI_DEVICE(vendor, device)是最精确的匹配vendor 和 device 都指定。PCI_DEVICE_CLASS则按设备类别匹配适合写通用驱动。最后那个{ 0, }是结束标记不能少否则内核会越界读取。这里有个细节很多人忽略MODULE_DEVICE_TABLE这个宏不是给内核运行时用的而是给模块加载工具用的。它会把设备 ID 信息写进模块的.modinfo段这样在设备热插拔时用户空间的udev或mdev才能根据设备 ID 自动加载对应模块。如果你写的是内置驱动built-in这个宏可以不加但加上也没坏处。匹配优先级上内核会先匹配精确的 vendor/device再匹配 class。如果两个驱动都能匹配同一个设备先注册的那个赢。所以如果你写的是通用驱动最好把 class 匹配的范围收窄一点避免抢了专用驱动的活。提示调试匹配问题时/sys/bus/pci/drivers/下面每个驱动目录里都有new_id和bind、unbind文件可以手动触发匹配和绑定非常方便验证 id_table 写得对不对。2.3 probe 函数的职责边界probe是 PCI 驱动里最重要的函数但它的职责边界很多人搞不清楚。我的经验是probe 只做资源获取和初始化不做耗时操作不做可能睡眠很久的事情。具体来说probe 里通常要做这几件事使能 PCI 设备pci_enable_device()申请 BAR 资源pci_request_regions()映射 BAR 到内核虚拟地址pci_iomap()设置 DMA 掩码dma_set_mask_and_coherent()申请中断pci_alloc_irq_vectors()request_irq()初始化硬件寄存器注册字符设备、网络设备、或其他子系统设备反过来probe 里不应该做的事长时间msleep等待硬件大量内存分配尤其是GFP_KERNEL大块分配用户空间交互复杂的业务逻辑原因很简单probe 是在内核枚举设备的过程中被调用的如果 probe 卡住整个枚举流程都会受影响。我见过有人在 probe 里等硬件上电稳定msleep(2000)结果系统启动时 PCI 枚举直接超时其他设备都识别不到。这种坑踩一次就记住了。正确的做法是把耗时初始化放到工作队列或者延迟任务里probe 只做必要的资源申请和快速初始化。3. 核心细节解析BAR 空间、中断与 DMA 的实操要点3.1 BAR 空间映射的正确姿势BARBase Address Register是 PCI 设备暴露给主机的地址窗口。设备通过 BAR 告诉主机我需要多大空间是内存空间还是 IO 空间。驱动要做的就是把这个窗口映射到内核虚拟地址然后像访问内存一样访问设备寄存器。映射的标准写法int bar 0; resource_size_t bar_len; void __iomem *regs; bar_len pci_resource_len(pdev, bar); if (!bar_len) { dev_err(pdev-dev, BAR%d is empty\n, bar); return -ENODEV; } if (!(pci_resource_flags(pdev, bar) IORESOURCE_MEM)) { dev_err(pdev-dev, BAR%d is not memory space\n, bar); return -ENODEV; } regs pci_iomap(pdev, bar, bar_len); if (!regs) { dev_err(pdev-dev, Failed to map BAR%d\n, bar); return -ENOMEM; }这里有几个容易出问题的地方。第一BAR 长度要先检查。有些设备的 BAR 是空的或者长度是 0直接映射会失败。更隐蔽的是有些设备 BAR 长度不是 2 的幂映射时可能只映射了一部分访问越界就会出问题。第二要区分 MEM 和 IO 空间。现代 PCIe 设备基本都是 MEM 空间IO 空间已经很少用了。但如果你遇到老设备一定要检查IORESOURCE_MEM标志否则ioread32之类的函数用错了会直接崩。第三映射之后要用ioread32/iowrite32访问不能直接解引用。因为pci_iomap返回的是void __iomem *在有些架构上比如 ARM这个地址和普通内存地址不在一个空间直接解引用会触发异常。我见过有人在 x86 上写代码直接*(u32 *)regs在 x86 上跑得好好的换到 ARM 平台就崩了就是这个原因。第四卸载时要pci_iounmap并且顺序要和映射相反。先 unmap再 release regions最后 disable device。3.2 中断申请从 INTx 到 MSI/MSI-XPCI 设备的中断方式有三种INTx、MSI、MSI-X。INTx 是传统的中断线方式MSI 和 MSI-X 是基于消息的中断现代 PCIe 设备基本都用 MSI-X。申请中断的推荐写法int nvec; nvec pci_alloc_irq_vectors(pdev, 1, 4, PCI_IRQ_ALL_TYPES); if (nvec 0) { dev_err(pdev-dev, Failed to alloc irq vectors\n); return nvec; } for (i 0; i nvec; i) { irq pci_irq_vector(pdev, i); ret request_irq(irq, my_isr, 0, my_pci, my_priv); if (ret) { dev_err(pdev-dev, Failed to request irq %d\n, irq); goto err_free_vectors; } }pci_alloc_irq_vectors这个函数很聪明它会优先尝试 MSI-X不行再试 MSI最后才用 INTx。参数里的1, 4表示最少要 1 个向量最多要 4 个。PCI_IRQ_ALL_TYPES表示三种类型都接受。这里有个经验如果你的设备支持 MSI-X一定要用 MSI-X。INTx 是共享中断线多个设备可能共用一根线中断处理函数里还要判断是不是自己的设备触发的效率低还容易出问题。MSI-X 每个向量独立还能绑定到不同 CPU 核对多队列设备特别友好。释放的时候顺序也要注意先free_irq再pci_free_irq_vectors。如果顺序反了free_irq的时候向量已经没了会报 warning。3.3 DMA 掩码设置与一致性映射PCI 设备做 DMA 之前必须告诉内核设备的 DMA 地址位宽。这个信息通过dma_set_mask_and_coherent设置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)); if (ret) { dev_err(pdev-dev, No usable DMA mask\n); return ret; } }先试 64 位不行再退到 32 位。这是标准做法。为什么要先试 64 位因为 64 位 DMA 可以访问整个内存空间不需要 bounce buffer性能更好。如果设备只支持 32 位 DMA内核会启用 bounce buffer数据要先拷贝到低 4G 内存再 DMA性能损失明显。DMA 映射分两类一致性映射dma_alloc_coherent和流式映射dma_map_single。一致性映射适合长期存在的缓冲区比如描述符环流式映射适合一次性传输的数据。/* 一致性映射 */ dma_addr_t dma_handle; void *cpu_addr dma_alloc_coherent(pdev-dev, size, dma_handle, GFP_KERNEL); /* 流式映射 */ dma_addr_t dma_addr dma_map_single(pdev-dev, buf, len, DMA_TO_DEVICE); /* ... 传输 ... */ dma_unmap_single(pdev-dev, dma_addr, len, DMA_TO_DEVICE);流式映射用完必须 unmap否则会泄漏 DMA 地址空间。一致性映射则要dma_free_coherent释放。注意DMA 缓冲区如果要做 cache 一致性维护一定要用 DMA API不要自己手动 flush cache。不同架构的 cache 操作方式不一样手动操作很容易出错。4. 完整实操从零写一个可加载的 PCI 驱动骨架4.1 驱动骨架代码与逐行说明下面这个骨架是我在实际项目中反复用过的去掉业务逻辑之后可以直接当模板#include linux/module.h #include linux/pci.h #include linux/interrupt.h #include linux/dma-mapping.h #define DRV_NAME my_pci_drv struct my_pci_priv { struct pci_dev *pdev; void __iomem *regs; int irq; struct device *dev; }; static const struct pci_device_id my_pci_ids[] { { PCI_DEVICE(0x1234, 0x5678) }, { 0, } }; MODULE_DEVICE_TABLE(pci, my_pci_ids); static irqreturn_t my_pci_isr(int irq, void *arg) { struct my_pci_priv *priv arg; u32 status; status ioread32(priv-regs 0x10); if (!(status 0x1)) return IRQ_NONE; /* 清中断 */ iowrite32(status, priv-regs 0x10); return IRQ_HANDLED; } static int my_pci_probe(struct pci_dev *pdev, const struct pci_device_id *id) { struct my_pci_priv *priv; int ret; priv devm_kzalloc(pdev-dev, sizeof(*priv), GFP_KERNEL); if (!priv) return -ENOMEM; priv-pdev pdev; priv-dev pdev-dev; pci_set_drvdata(pdev, priv); ret pcim_enable_device(pdev); if (ret) return ret; ret pcim_iomap_regions(pdev, BIT(0), DRV_NAME); if (ret) return ret; priv-regs pcim_iomap_table(pdev)[0]; 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)); if (ret) return ret; ret pci_alloc_irq_vectors(pdev, 1, 1, PCI_IRQ_ALL_TYPES); if (ret 0) return ret; priv-irq pci_irq_vector(pdev, 0); ret devm_request_irq(pdev-dev, priv-irq, my_pci_isr, 0, DRV_NAME, priv); if (ret) return ret; dev_info(pdev-dev, probe done, irq%d\n, priv-irq); return 0; } static void my_pci_remove(struct pci_dev *pdev) { struct my_pci_priv *priv pci_get_drvdata(pdev); dev_info(pdev-dev, remove\n); /* devm 会自动释放资源 */ } static struct pci_driver my_pci_driver { .name DRV_NAME, .id_table my_pci_ids, .probe my_pci_probe, .remove my_pci_remove, }; module_pci_driver(my_pci_driver); MODULE_LICENSE(GPL); MODULE_AUTHOR(your name); MODULE_DESCRIPTION(PCI driver skeleton);这个骨架里我用了pcim_系列函数和devm_系列函数好处是资源自动释放remove函数里几乎不用写清理代码。pcim_enable_device、pcim_iomap_regions、devm_request_irq都是托管版本设备卸载时内核会自动回收。pcim_iomap_regions(pdev, BIT(0), DRV_NAME)里的BIT(0)表示只映射 BAR0。如果要映射多个 BAR用BIT(0) | BIT(2)这种写法。映射之后通过pcim_iomap_table(pdev)[0]拿到 BAR0 的虚拟地址。4.2 编译、加载与验证的完整流程Makefile 很简单obj-m my_pci_drv.o KDIR : /lib/modules/$(shell uname -r)/build PWD : $(shell pwd) all: $(MAKE) -C $(KDIR) M$(PWD) modules clean: $(MAKE) -C $(KDIR) M$(PWD) clean编译加载make sudo insmod my_pci_drv.ko dmesg | tail -20如果设备存在且 ID 匹配你应该能在dmesg里看到probe done的打印。如果没看到先检查设备是否被系统识别lspci -nn lspci -vvv -s 00:01.0lspci -nn会显示设备的 vendor:device ID确认和你id_table里写的一致。lspci -vvv能看到 BAR 分配情况、中断信息、驱动绑定情况。查看驱动绑定ls /sys/bus/pci/drivers/my_pci_drv/ ls -l /sys/bus/pci/devices/0000:00:01.0/driver如果设备已经被其他驱动绑定了需要先 unbindecho 0000:00:01.0 | sudo tee /sys/bus/pci/drivers/old_driver/unbind echo 0000:00:01.0 | sudo tee /sys/bus/pci/drivers/my_pci_drv/bind这种手动 bind/unbind 的方式在调试时特别有用不用反复加载卸载模块。4.3 用 sysfs 和 debugfs 观察驱动状态驱动跑起来之后怎么确认它工作正常除了dmesg还可以通过 sysfs 观察。/sys/bus/pci/devices/0000:00:01.0/下面有很多有用的文件resourceBAR 的物理地址和长度irq中断号enable设备使能状态driver绑定的驱动config配置空间原始数据读取配置空间sudo cat /sys/bus/pci/devices/0000:00:01.0/config | hexdump -C这个在排查设备 ID 识别错误、BAR 分配异常时非常有用。如果驱动里创建了 debugfs 节点还可以通过 debugfs 导出更详细的运行时状态。我一般会在驱动里加一个 debugfs 文件把寄存器快照、中断计数、DMA 统计都导出来调试的时候一目了然。5. 常见问题与排查技巧实录5.1 probe 不执行的几种典型原因这是问得最多的问题模块加载了lsmod能看到但probe就是不执行。原因通常有这几类现象可能原因排查方法probe 完全不执行id_table 不匹配lspci -nn对比 vendor/deviceprobe 不执行但设备存在设备已被其他驱动绑定查看/sys/bus/pci/devices/.../driverprobe 执行但返回错误资源申请失败看 dmesg 里的错误码模块加载失败依赖符号未解析modinfo看 depends设备根本没枚举到硬件或 BIOS 问题lspci是否能看到设备我遇到过一次特别隐蔽的设备 ID 匹配但 probe 就是不执行。最后发现是id_table最后忘了加{ 0, }结束标记内核读取越界匹配逻辑直接乱了。这种问题看代码很难发现因为语法上完全合法。还有一个常见原因是驱动注册顺序。如果你的驱动和另一个驱动都能匹配同一个设备先注册的赢。内置驱动在启动时就注册了模块驱动加载晚自然抢不过。解决办法是把内置驱动加入黑名单或者用bind/unbind手动切换。5.2 BAR 映射失败与资源冲突处理BAR 映射失败通常有几个原因第一BAR 没被 BIOS 分配。有些平台 BIOS 配置不当PCI 设备的 BAR 没有被分配地址pci_resource_len返回 0。这种情况需要检查 BIOS 设置或者在内核启动参数里加pcirealloc让内核重新分配。第二资源冲突。两个设备抢同一段地址空间后申请的那个会失败。dmesg里会有cant reserve之类的报错。用cat /proc/iomem可以看到当前地址空间分配情况。第三映射长度不对。pci_iomap的长度参数如果超过 BAR 实际长度会映射失败。正确做法是用pci_resource_len获取实际长度。第四64 位 BAR 处理。64 位 BAR 占用两个 BAR 寄存器映射时要用pci_resource_len和pci_resource_start的 64 位版本不能只处理低 32 位。提示遇到error: insufficient pci resources detected这类报错基本可以确定是 BAR 地址空间不够。可以尝试内核参数pcirealloc或者调整 BIOS 里的 Above 4G Decoding 选项。5.3 中断不触发与 DMA 数据异常的定位思路中断不触发先确认三件事中断号是否申请成功cat /proc/interrupts看有没有你的中断设备是否真的产生了中断读设备的中断状态寄存器中断是否被屏蔽检查设备的中断使能寄存器如果中断号申请了但计数一直是 0说明设备没产生中断或者中断线没接对。MSI-X 的话检查lspci -vvv里的 MSI-X 配置确认向量表地址写对了。DMA 数据异常更麻烦常见原因DMA 掩码设置不对设备访问了非法地址缓冲区没有正确映射设备读到的是物理地址而不是 DMA 地址cache 一致性问题CPU 看到的数据和设备写入的不一致描述符环没有正确初始化设备读到垃圾描述符排查 DMA 问题我一般会先确认dma_set_mask_and_coherent返回值再看dma_map_single返回的 DMA 地址是否合理。如果 DMA 地址是 0 或者明显不对基本可以确定是映射问题。5.4 卸载驱动时的资源释放顺序卸载驱动时资源释放顺序错了轻则报 warning重则内核崩溃。正确顺序是停止设备工作关闭中断使能、停止 DMAfree_irq释放中断pci_free_irq_vectors释放向量dma_free_coherent释放 DMA 缓冲区pci_iounmap解除 BAR 映射pci_release_regions释放 BAR 资源pci_disable_device禁用设备用devm_和pcim_系列函数的话这些大部分会自动处理但中断和 DMA 缓冲区最好还是显式释放避免设备还在工作中就被卸载。我踩过的一个坑在remove里先pci_disable_device再free_irq结果设备被禁用后中断线状态异常free_irq卡住。后来改成先关中断再禁用设备问题解决。这个顺序在文档里没写但实际调试中很关键。6. 调试工具与实战经验补充6.1 lspci、setpci 与 sysfs 的组合用法lspci是最常用的 PCI 调试工具但很多人只用lspci看设备列表其实它的选项非常丰富lspci -nn # 显示 vendor:device ID lspci -vvv # 显示详细配置包括 BAR、中断、能力 lspci -t # 显示 PCI 拓扑树 lspci -s 00:01.0 -xxx # 显示配置空间原始数据setpci可以直接读写配置空间调试时很有用setpci -s 00:01.0 0x04.w # 读 command 寄存器 setpci -s 00:01.0 0x04.w0x06 # 写 command 寄存器不过setpci操作有风险写错寄存器可能导致设备挂死生产环境慎用。sysfs 里的resource文件可以看 BAR 分配cat /sys/bus/pci/devices/0000:00:01.0/resource输出格式是每行一个 BAR起始地址、结束地址、标志。标志里0x...200表示 MEM 空间0x...100表示 IO 空间。6.2 内核启动参数对 PCI 枚举的影响有些 PCI 问题不是驱动的问题而是内核枚举策略的问题。常用的启动参数pcirealloc重新分配 BAR 资源解决资源不足pcinocrs忽略 ACPI 的 CRS 资源描述强制重新枚举pciassign-busses重新分配总线号pcinoacpi不使用 ACPI 枚举用传统方式这些参数在调试国产化平台、虚拟机、老主板时特别有用。我遇到过一块国产主板BIOS 分配的 BAR 地址和系统内存冲突加上pcirealloc之后问题解决。注意这些参数会影响整个系统的 PCI 枚举生产环境使用前一定要充分测试避免影响其他设备。6.3 国产化平台适配 PCI 驱动的几点体会国产化平台适配 PCI 驱动和通用 x86 平台有几个明显区别。第一设备树和 ACPI 的差异。有些国产平台用设备树描述 PCI 主机桥有些用 ACPI。设备树方式下PCI 设备的枚举依赖of_pci相关代码配置空间访问方式可能和标准 ECAM 不一样。适配时要先确认平台用的是哪种枚举方式。第二BAR 空间分配策略不同。国产平台的 BIOS 或固件可能对 BAR 分配有自己的策略有时候会出现 BAR 地址不在预期范围的情况。调试时先用lspci -vvv确认 BAR 实际分配再决定驱动里怎么映射。第三中断控制器的差异。国产平台的中断控制器可能是 GIC 的变种MSI-X 的向量分配方式和标准平台不完全一样。申请中断时如果失败先检查pci_alloc_irq_vectors的返回值再确认平台是否支持 MSI-X。第四DMA 一致性维护。有些国产平台的 cache 一致性协议实现和标准 ARM 平台有差异DMA 缓冲区可能需要额外的 cache 操作。这种情况优先用 DMA API不要自己手动 flush。我在一个国产平台上调试 PCIe 网卡时遇到过 DMA 数据偶发错误的问题。最后发现是平台的 cache line 大小和驱动假设的不一致调整了 DMA 缓冲区的对齐方式之后问题解决。这种问题很难从代码上看出来只能靠实际测试和对比。6.4 从字符设备框架到 PCI 框架的思维转换最后聊一个偏思维层面的东西。很多从字符设备驱动转过来的朋友会习惯性地把 PCI 驱动也写成注册一个设备节点等用户空间来 open的模式。这个思路在 PCI 场景下是不完整的。PCI 驱动的核心不是提供文件接口而是接管一个硬件设备。文件接口只是驱动对外暴露能力的一种方式不是必须的。很多 PCI 驱动根本不创建字符设备节点而是注册到网络子系统、块子系统、或者 V4L2 子系统。比如一块 PCIe 采集卡驱动会注册 V4L2 设备用户空间通过/dev/videoX访问但驱动本身是 PCI 驱动不是字符设备驱动。所以写 PCI 驱动时先想清楚这个设备属于哪个子系统应该注册成什么类型的设备。PCI 框架只负责帮你找到设备、分配资源具体怎么用这些资源取决于设备的功能和所属子系统。这个思维转换过来之后再看 PCI 驱动代码就清晰多了probe是入口资源申请是准备注册子系统设备是出口中断和 DMA 是工作方式。整个框架就是围绕这四件事展开的。我在实际项目中最大的体会是PCI 驱动调试一半时间花在确认硬件状态一半时间花在确认资源分配。代码逻辑本身反而不复杂复杂的是硬件和平台的差异。所以遇到问题先别急着改代码先用lspci、/proc/iomem、/proc/interrupts把硬件状态确认清楚往往能省下大量时间。