Linux PCI设备驱动核心机制：匹配、BAR映射与DMA配置实战

做PCI设备驱动开发的人大概都有过这种体验：照着范例把struct pci_driver填满，在 probe 里写上一堆初始化代码，编译加载，然后心提到嗓子眼——设备到底有没有被正确挂上？BAR 空间够不够？中断会不会来？我上周调一块 PCIe 采集卡时就撞上了pci out of resources这个经典报错，排查过程让我意识到，与其零散地搜日志，不如把 Linux PCI 驱动框架的运转逻辑完整梳理一遍。这是系列的第二篇，上一篇讲了 PCIe 拓扑和枚举的基本概念，这次聚焦驱动开发真正绕不开的部分：设备匹配流程、资源映射手法、DMA 与中断配置，以及现场怎么排障。内容不追求覆盖每一个 API，而是帮你在脑子里搭出一张"设备从识别到跑数据"的路线图。

1. 先弄清"谁来找谁"：PCI 设备与驱动的匹配机制

刚接触 PCI 驱动的人最容易犯的一个错，是把字符设备驱动的思路直接搬过来：注册一个 file_operations，然后等着用户 open 设备文件。但 PCI 驱动的主动权根本不在驱动这边。内核的pci_bus_type会在总线枚举和后续热插拔事件中主动扫描设备，拿着设备信息去比对所有已注册的pci_driver，找到匹配项之后才调用你的 probe。可以说，设备是"岗位"，驱动是"候选人"，内核是 HR。

1.1 一张 pci_device_id 表就是寻人启事

struct pci_device_id是驱动和设备之间的"约定"。内核匹配时，就是拿设备的 vendor、device、subvendor、subdevice、class 等字段，逐条遍历驱动提供的 id_table，只要任何一条能对上，就认为这个驱动负责这个设备。

struct pci_device_id { __u32 vendor, device; // 主ID，必须匹配 __u32 subvendor, subdevice; // 子系统ID，可设 PCI_ANY_ID __u32 class, class_mask; // 类别匹配，带掩码 kernel_ulong_t driver_data; // 透传给 probe 的私有数据 };

vendor 和 device 是主干匹配项，几乎不会用PCI_ANY_ID去模糊匹配，因为那等于对所有设备喊"我是你爹"，会把别人的设备抢过来。subvendor 和 subdevice 描述的是"具体板卡"而不仅仅是"芯片"。同一颗芯片可能被多家厂商做成不同板卡，如果你只写 vendor/device 而不约束 subdevice，驱动就会错误绑定到不是你目标的板卡上。

我自己就踩过这个坑。当时有两个子型号，vendor/device 完全一样，只有 subdevice 不同。我偷懒只写了PCI_DEVICE(0x1234, 0x5678)，结果两个型号都被 probe，第二个型号的寄存器布局不一样，初始化直接崩。改成PCI_DEVICE_SUB(0x1234, 0x5678, 0x1234, 0x0002)之后才清净。所以，如果你的硬件有子系统标识，尽量用全约束。

1.2 匹配成功之后，driver_data 和 MODULE_DEVICE_TABLE 在忙什么

driver_data是个kernel_ulong_t，按内核惯例用来存放"指向私有配置结构体的指针取整"。probe 的第二个参数const struct pci_device_id *id会把这一项原样传给你，这样同一个驱动支持多个型号时，你可以在 probe 入口直接根据 id 拿到对应配置，不用到处写 if/else。

static const struct pci_device_id cap_ids[] = { { PCI_DEVICE(0x1234, 0x5678), .driver_data = (kernel_ulong_t)&cap_a_config }, { PCI_DEVICE(0x1234, 0x5679), .driver_data = (kernel_ulong_t)&cap_b_config }, { } }; MODULE_DEVICE_TABLE(pci, cap_ids);

MODULE_DEVICE_TABLE不是给人看的仪式，它会在编译时生成模块的 alias 信息，depmod后写入modules.alias。系统里 udev 在发现 PCI 设备时，会读取设备 sysfs 下的 modalias 文件，内容像一串编码，比如pci:v00001234d00005678sv...，然后用它去 modules.alias 里反查该加载哪个 .ko。所以哪怕你在板子上手动insmod没问题，如果忘了写MODULE_DEVICE_TABLE，开箱时驱动基本不会被自动加载——这不是内核 bug，是你不小心砍掉了自动加载链路。

1.3 class 匹配的适用场景

除了精确 ID 匹配，pci_device_id 还支持按设备类别匹配，比如匹配某个网卡或者显卡类别下的所有设备。class 字段本身是编码形式，class_mask用来屏蔽不需要比较的位。实操中 class 匹配用得少，因为同一个类别下不同设备的寄存器差异巨大，强行匹配进去，probe 里还得再靠 vendor/device 二次区分，不如直接精确匹配干净。真正的典型用途是某种"通用类驱动"，比如某些 vendor 提供的通用 PCIe 驱动，先按 class 兜底，再在内部分流派。新手不建议模仿。

一句话总结匹配机制：id_table 是门禁，driver_data 是进门后递给你的工牌，MODULE_DEVICE_TABLE 是让门卫知道"今天有你这个候选人"的通讯录。三者配合，probe 才会在一个"设备真实存在"的前提下被调用。

2. probe 不是随便写写：驱动的出生、存活与退休

probe是 PCI 驱动的核心主战场，但很多人把它当成"初始化硬件"的地方，这个理解太窄。probe 更准确的定位是"资源申请清单"。设备枚举是内核做的，驱动能做的只是把自己需要的资源申请下来，做好映射，然后让设备可被系统其他子系统使用。

2.1 probe 里该干的七件事和对应释放

我按自己写 PCIe 驱动的习惯，给出 probe 的标准动作：

static int my_pci_probe(struct pci_dev *pdev, const struct pci_device_id *id) { struct my_dev *dev; int ret; dev = kzalloc(sizeof(*dev), GFP_KERNEL); if (!dev) return -ENOMEM; dev->pdev = pdev; pci_set_drvdata(pdev, dev); ret = pci_enable_device(pdev); if (ret) goto err_free; ret = pci_request_regions(pdev, "my_driver"); if (ret) goto err_disable; dev->bar = pci_iomap(pdev, 0, pci_resource_len(pdev, 0)); if (!dev->bar) goto err_release; pci_set_master(pdev); 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) goto err_unmap; } ret = pci_alloc_irq_vectors(pdev, 1, 1, PCI_IRQ_MSI | PCI_IRQ_INTX); if (ret < 0) goto err_unmap; dev->irq = pci_irq_vector(pdev, 0); ret = devm_request_irq(&pdev->dev, dev->irq, my_irq_handler, 0, "my_driver", dev); if (ret) goto err_irq; ret = misc_register(&dev->miscdev); if (ret) goto err_irq; return 0; err_irq: pci_free_irq_vectors(pdev); err_unmap: pci_iounmap(pdev, dev->bar); err_release: pci_release_regions(pdev); err_disable: pci_disable_device(pdev); err_free: kfree(dev); return ret; }

对应的 remove 就是把这套动作倒着做一遍：首先注销 miscdev 这类对外接口，确保不再有用户态路径能摸到设备；然后 free 中断、释放中断向量、iounmap、release regions、disable device，最后 kfree。顺序不能乱，尤其要记住"先断对外接口，再断内部资源"，否则 remove 过程中有进程正在读写，你这边把 ioremap 释放了，那边 read 还在访问非法地址，直接 oops。

2.2 devm 资源：偷懒的前提是搞清楚生命周期

上面的错误处理链里有一堆 goto，写多了容易漏。内核提供了一套 devm（managed device resources）机制，注册的资源会在设备解除绑定或驱动移除时自动释放。比如devm_kzalloc、devm_ioremap、devm_request_irq，以及较新内核里的devm_request_pci_regions和pcim_enable_device。

用 devm 的好处是 probe 中途失败时不用一个个手动回滚，代码里可以少写很多错误处理标签。但副作用也很明确：这些资源按"栈顺序"逆序释放，也就是后申请的反而先释放。如果你的资源之间有依赖关系，就必须仔细设计申请次序。

我现在的习惯是：小驱动直接用 devm 一把梭，减少出错；大驱动则保持手动管理，因为移除顺序我想完全掌控。有一点必须强调，用了devm_request_irq之后，remove 里绝对不要再手动free_irq，否则会重复释放，内核直接炸给你看。

2.3 suspend/resume：别让设备在睡眠中失忆

现代 PCI 驱动很少直接在struct pci_driver里写 suspend/resume 回调，而是用driver.pm = &my_pm_ops挂dev_pm_ops。挂起时主要做三件事：停掉数据流（DMA 停、中断屏蔽）、保存需要恢复的寄存器状态、把设备放到低功耗状态。恢复时反过来：先恢复 PCI 配置空间，再重新初始化设备内部状态，最后开中断、启动 DMA。

这里有个最常见的误解：很多人以为 resume 之后 BAR 地址、DMA 配置由内核全包了。内核确实会恢复标准 PCI 配置空间（pci_restore_state），但设备内部私有寄存器和 DMA 描述符状态属于"设备固件上下文"，内核管不着。如果硬件固件设计得比较偷懒，D3 之后内部状态全丢，resume 里不重新初始化，开起来的 DMA 会像脱缰野马一样访问无效地址。我碰到过一块板卡，resume 后必须重新下发整个描述符环基地址，否则中断永远不来，数据也永远不更新。

3. 地址空间真相：BAR、MMIO 与"pci out of resources"的根因

PCI 设备不直接知道"CPU 物理地址"这个概念。它只知道自己有几个 BAR（Base Address Register），BAR 是设备向系统申报地址空间的窗口。固件在枚举时读取 BAR 的写入行为来判断窗口大小，然后给每个窗口分配一段 PCI 域地址，这段地址再经过 Host Bridge 映射到 CPU 物理地址空间。驱动要访问设备寄存器，本质上就是访问这段被映射进来的内存或 IO 空间。

3.1 从 BAR 描述符读出你要的资源

驱动不要自己去读配置空间里的 BAR 原始值，那是固件和内核枚举阶段的事。内核已经帮你解析好了，直接使用pci_resource_*系列函数：

resource_size_t start = pci_resource_start(pdev, bar); resource_size_t len = pci_resource_len(pdev, bar); unsigned long flags = pci_resource_flags(pdev, bar);

flags 里需要注意两位：IORESOURCE_IO表示 IO 端口空间，IORESOURCE_MEM表示内存映射空间。内存空间里还有IORESOURCE_PREFETCH标志，表示可预取。可预取的含义是"读这个地址没有副作用、数据可以被 CPU 缓存合并"。如果你的 BAR 实际是控制寄存器或者 FIFO，读它本身会改变设备状态，那就绝不该标成 prefetchable。之前调试一块回读 FIFO 的板卡，readl 拿回来的数据偶尔乱序，查到最后就是硬件工程师把 BAR 配成了 prefetchable，软件这边读操作被 CPU 重排合并了。

3.2 从 PCI 域地址到 CPU 指针：ioremap 的三条路

拿到pci_resource_start之后，你还需要把它映射成内核虚拟地址才能用 C 语言访问。最省事的是pci_iomap，它内部会根据资源类型自动选择ioremap还是ioport_map：

void __iomem *bar0 = pci_iomap(pdev, 0, pci_resource_len(pdev, 0)); if (!bar0) { ... } u32 val = ioread32(bar0 + REG_STATUS); iowrite32(0x1, bar0 + REG_CTRL);

这里我建议统一用ioread32/iowrite32而不是readl/writel。两者在 x86 上行为差别不大，但ioread32的语义就是访问 MMIO，移植到 ARM、RISC-V 上更安全。64 位 BAR 也没有玄学，pci_resource_len返回的已经是resource_size_t（64 位），只要内核开启 64 位资源支持，直接按同样方式访问即可。

3.3 排障实战：新卡在老机器上报 no space 的完整排查

这个报错值得单独立一节，因为它不是驱动的锅，而是整个系统资源分配的锅。典型 dmesg 长这样：

pci 0000:03:00.0: BAR 0: no space for resource [mem size 0x01000000] pci 0000:03:00.0: BAR 0: can't assign mem (size 0x01000000)

第一句的意思是：设备想要 16MB 的 MMIO 窗口，但系统当前的 PCI 域地址空间里找不到连续 16MB 的空闲区间。这在老平台和虚拟机上特别常见。PCI 地址空间不是无限的，传统 PC 在 32 位时代只把 3G 到 4G 附近一段留给 PCI 设备，多个设备瓜分完就没了。现代主板 BIOS 里有"Above 4G Decoding"选项，打开之后才允许把 PCI 资源放到 4G 以上的高位地址空间。

我那次遇到的具体情况是：一块板卡 BAR0 要 16MB，插上一台只有 8MB 空闲 MMIO 窗口的旧工控机，报的正是这个错。排查顺序是：

那一次排查的节奏是，先看lspci -vvv -s 03:00.0，发现 Region 0 显示[size=16M]而不是具体地址，说明 BAR 没被分配；再看dmesg | grep -i pci，立刻定位到 no space 日志；最后进 BIOS 确认平台上确实没有 Above 4G 选项。你要是也遇到同样日志，处理手段按优先级来：

1. BIOS 里打开 Above 4G Decoding（有些 BIOS 叫 Large BAR、SR-IOV 支持，都得开）
2. 换插槽，避开集显或其他大 BAR 设备占用的窗口
3. 内核启动参数加pci=realloc，让内核在启动阶段强行重新分配所有 PCI 资源
4. 虚拟机环境则检查虚拟机的 MMIO 窗口配置，有些 hypervisor 默认给 PCIe 预留空间很小

还有一个容易被忽略的细节：pci_enable_device失败时也可能报can't enable device: BAR 0 ... not assigned。很多人以为 enable 只是开电源管理，实际上它内部也会尝试为未分配资源的 BAR 争取空间。如果 BAR 压根没分到地址，这里的报错只是把枚举阶段的问题延迟到了驱动加载阶段而已。

4. 让数据流动起来：DMA 设置与中断选择的若干细节

设备识别了、寄存器能访问了，但一块 PCIe 板卡真正的价值在于数据搬运。这一步绕不开 DMA 和中断，也是驱动开发中出错率最高的部分。

4.1 DMA 掩码：先让设备"够得着"内存

设备做 DMA 时，要往内存总线地址上写数据，但设备本身不知道自己 CPU 物理地址多宽。你需要用dma_set_mask_and_coherent告诉 DMA 层这个设备"认得多少位地址"：

if (dma_set_mask_and_coherent(&pdev->dev, DMA_BIT_MASK(64))) { if (dma_set_mask_and_coherent(&pdev->dev, DMA_BIT_MASK(32))) return -EIO; }

先试 64 位，失败再退化 32 位，这是标准顺序。为什么失败？可能是 IOMMU 限制、设备硬件本身只支持 32 位寻址，或者总线地址宽度不足。注意dma_set_mask和dma_set_coherent_mask可以分开设置，一般情况用dma_set_mask_and_coherent一起设更省事。忘了设掩码的后果是 DMA 映射层不知道设备能力，可能交出 64 位地址，而设备只能写低 32 位，数据写入完全随机，排查时让人抓狂。

4.2 一致性内存与流式映射的分工

DMA 内存分两大类，使用场景完全不同。

一致性内存用dma_alloc_coherent分配，CPU 和设备看到的地址不需要额外同步。适合放描述符环、状态区域、控制块这类需要频繁被双方读写的小块数据：

struct ring { struct desc *cpu; dma_addr_t dma; }; ring->cpu = dma_alloc_coherent(&pdev->dev, ring_size, &ring->dma, GFP_KERNEL);

流式映射用dma_map_single/dma_map_sg，一次映射一段缓冲区，用完就 unmap。适合网络包、块数据这类一次性大块数据传输。速度更快，但 CPU 访问前必须dma_sync_single_for_cpu，设备访问前必须dma_sync_single_for_device。我吃过一次亏：DMA 完成中断里直接读 data buffer，发现数据是旧的，折腾了半天，根源就是忘了在 CPU 读之前做 sync，cache 里的旧数据挡住了新鲜结果。

还要提醒一点：dma_alloc_coherent分配的是页对齐内存，别指望它能分配几十 MB。大块数据老老实实走流式映射，或者自己管理 SG 列表。设备端用什么，驱动端就用对应的映射 API，DMA 地址一定要用 API 返回的dma_addr_t，不要自己拿 virt_to_phys 算，有 IOMMU 的时候这两个值可能完全不一样。

4.3 MSI 与 INTx 的取舍，以及分配向量代码模板

现代 PCIe 设备优先用 MSI/MSI-X，INTx 是针脚共享中断的旧方案，能不用就不用。MSI-X 的优势是每个队列可以分配独立中断向量，多个 CPU 核分别处理不同队列，吞吐量完全不一样。分配代码一般这样写：

int nvec = pci_alloc_irq_vectors(pdev, 1, num_queues, PCI_IRQ_MSIX | PCI_IRQ_MSI); if (nvec < 0) { nvec = pci_alloc_irq_vectors(pdev, 1, 1, PCI_IRQ_INTX); if (nvec < 0) return nvec; } for (i = 0; i < nvec; i++) { unsigned int irq = pci_irq_vector(pdev, i); devm_request_irq(&pdev->dev, irq, my_irq_handler, 0, dev_name(&pdev->dev), queue[i]); }

pci_alloc_irq_vectors会按你给的类型优先级依次尝试，返回值是实际分配到的向量数。拿到nvec后，每个向量的 IRQ 号必须用pci_irq_vector查询，不能假设它们是连续的。如果走到 INTx 兜底，request_irq里要加IRQF_SHARED，因为 INTx 本来就是共享中断线，handler 里必须先读取设备中断状态寄存器，确认是不是自己的中断，不是就返回IRQ_NONE。

中断 handler 本身的撰写原则是：在原子上下文里只做最少的事。读状态、清中断、把数据搬进预分配缓冲、置一个标志位、唤起 workqueue，然后返回IRQ_HANDLED。重活放到线程化中断或 workqueue 里，硬中断里做得越少，锁的问题越少，系统延迟越可控。我甚至会把request_threaded_irq的线程化 handler 作为大块数据处理的主战场，硬中断只负责 ack 和唤醒。

5. 现场调试三板斧：sysfs、dmesg 与 lspci 的配合

写 PCI 驱动不是一次就能成功的，准备一套高效的现场排查手段能省下大量时间。我在调试中用的最多的是这三个工具组合：lspci -vvv看设备状态、dmesg看内核日志、sysfs 里的接口做动态试验。

5.1 从 lspci -vvv 读设备当前状态

lspci -nnvvv -s 03:00.0是查看单设备全貌的标准命令。重点看几个字段：

• Region 0: Memory at ...：如果显示的是实际地址，说明 BAR 已分配；如果显示[size=16M]而没有地址，说明资源没分配
• Interrupt: pin A routed to IRQ 51：能看到中断路由状态
• Capabilities: ... MSI-X：确认 MSI-X 能力是否可用
• LnkCap/LnkSta：链路速率和宽度，怀疑物理连接问题时先看这里

每次加载驱动前后都跑一遍，对比设备状态变化，很多时候问题一眼就能看出来。

5.2 模拟热插拔与强制绑定的正确姿势

sysfs 提供了一套不需要断电的热插拔试验环境。把设备从总线逻辑上移除再重新扫描：

echo "0000:03:00.0" > /sys/bus/pci/devices/0000:03:00.0/remove echo 1 > /sys/bus/pci/rescan

这样模拟一次完整的"设备消失-重新枚举"流程，非常适合验证 probe/remove 的配对逻辑。手动绑定驱动则在驱动目录下操作：

echo "0000:03:00.0" > /sys/bus/pci/drivers/my_driver/bind echo "0000:03:00.0" > /sys/bus/pci/drivers/my_driver/unbind

如果设备已经被别的驱动占用了，会绑定失败。这时可以先去占用的驱动目录下 unbind，再回来绑定。另外一个技巧是driver_override，往设备 sysfs 里写驱动名，可以强制指定某个驱动来匹配，这个在测试多个候选驱动时非常管用。

5.3 常见问题速查

调试中反复出现的几类问题，我整理成一个速查表，省得每次现查：

我再分享一个调试 DMA 时屡试不爽的小技巧：在硬件还没有真正跑起来之前，先让设备写一段已知 pattern 到一致性内存里，CPU 这边轮询这段内存，如果能看到 pattern，说明 DMA 写路径和地址映射是通的；再把 CPU 写好的 pattern 让设备读出去，验证读路径。先打通"地址对不对"，再去调"数据对不对"，能少走很多弯路。

最后说点实在的。Linux PCI 驱动框架表面上是一堆结构体和回调，实际上它把"设备发现、资源分配、驱动绑定、生命周期管理"这些脏活全包了。真正考验开发者的，往往不是 API 记不记得住，而是对匹配规则、资源窗口、DMA 语义和中断模型的理解是否到位。如果你照着这个思路把 probe 当资源清单、把 remove 当逆序拆解、把 sysfs 当实验台，绝大多数 PCI 驱动问题都能一步步拆到根因上。下一篇文章我会挑一个具体的 PCIe DMA 驱动示例，从零到一把完整流程跑一遍。