1. 课程概述：pci_set_master 关闭后 DMA 传输超时故障排查
本课程聚焦于 Linux 内核 PCI 子系统中一个经典且隐蔽的故障模式：驱动程序调用 pci_set_master(dev, false) 关闭总线主控（Bus Master）后，后续发起的 DMA 传输因无法获取总线控制权而陷入超时。该问题在热插拔、电源管理、设备复位等场景中尤为常见，轻则导致 I/O 停滞，重则引发系统挂死或内核 panic。
1.1 pci_set_master 的作用
pci_set_master 是 Linux 内核 PCI 驱动框架提供的核心接口，用于控制 PCI 设备是否具备总线主控能力。其本质是操作 PCI 配置空间中的 Command 寄存器（偏移 0x04）的第 2 位（Bus Master Enable, BME）。
| 函数原型 | 行为 | 配置空间操作 |
|---|---|---|
pci_set_master(dev) |
使能总线主控，允许设备主动发起内存/IO 访问 | 设置 Command 寄存器 Bit 2 = 1 |
pci_clear_master(dev) |
关闭总线主控，禁止设备主动发起事务 | 清除 Command 寄存器 Bit 2 = 0 |
pci_set_master(dev, false) |
同 pci_clear_master，显式关闭 |
清除 Command 寄存器 Bit 2 = 0 |
关键认知： BME 位控制的是设备作为 总线主控（Initiator） 的资格，而非设备作为 目标（Target） 的响应能力。关闭 BME 后，设备仍然可以被 CPU 通过 MMIO 访问，但无法主动发起 DMA 或中断传递。
1.2 DMA 传输的基本原理
DMA（Direct Memory Access）允许 PCI 设备绕过 CPU，直接在设备本地缓冲与系统内存之间传输数据。一次典型的 DMA 写入流程包含以下步骤：
- 驱动准备： 分配 DMA 缓冲区，调用
dma_map_single获取总线地址，并将描述符写入设备。 - 设备发起： 设备通过 PCI 总线发出 Memory Write 事务，目标地址为步骤 1 获得的总线地址。
- 桥接转发： PCI 桥/根端口将事务转发至内存控制器，数据写入物理内存。
- 完成通知： 设备触发中断或更新 doorbell 寄存器，驱动轮询或等待完成。
DMA 传输的核心前提： 设备必须持有总线主控权（BME=1），才能在步骤 2 中作为 Initiator 发起 PCI 总线事务。若 BME=0，设备发出的任何 Memory Write/Read 请求都会被 PCI 桥或根端口以 Master Abort 终止，数据无法到达目标内存。
1.3 关闭 Master 后导致超时的典型场景
以下四种场景是生产环境中关闭 BME 后触发 DMA 超时的高频诱因：
| 场景 | 触发条件 | 故障表现 | 根因分析 |
|---|---|---|---|
| 热插拔移除 | 驱动在 remove 回调中先关闭 Master，再释放 DMA 资源 |
DMA 完成中断丢失，wait_for_completion 超时 |
关闭 Master 后设备无法完成正在进行的 DMA 事务 |
| 电源管理挂起 | suspend 回调中关闭 Master，但 DMA 引擎未完全停止 |
恢复后 DMA 状态机卡死，超时复位 | 关闭 Master 时仍有 DMA 请求在总线仲裁中 |
| 错误恢复流程 | PCIe AER 处理中调用 pci_clear_master 后未等待 pending DMA |
恢复后设备无法响应，驱动超时 | DMA 完成通知因 Master 关闭而无法送达 |
| 驱动竞态条件 | 多线程中一个线程关闭 Master，另一线程正在提交 DMA | DMA 提交成功但硬件无法执行，超时 | 关闭 Master 与 DMA 提交之间缺少同步屏障 |
排查黄金法则： 在关闭 Master 之前，驱动必须确保：
(1) 所有已提交的 DMA 描述符已被硬件处理完毕（通过查询完成状态或等待中断）；
(2) 不再有新的 DMA 请求被提交（通过状态标志或锁保护）；
(3) 关闭 Master 后，任何未完成的 DMA 事务都会导致不可恢复的总线错误。
(1) 所有已提交的 DMA 描述符已被硬件处理完毕（通过查询完成状态或等待中断）；
(2) 不再有新的 DMA 请求被提交（通过状态标志或锁保护）；
(3) 关闭 Master 后，任何未完成的 DMA 事务都会导致不可恢复的总线错误。
1.4 课程学习路径
本课程将按照以下结构逐步深入：
- 基础篇（第 2-5 章）： PCI 配置空间详解、DMA 引擎与描述符管理、中断与完成通知机制。
- 排查篇（第 6-15 章）： 内核日志分析、PCIe 错误记录解析、硬件逻辑分析仪抓包、驱动代码静态检查。
- 实战篇（第 16-25 章）： 热插拔场景复现、电源管理挂起/恢复测试、AER 错误注入、竞态条件压力测试。
- 修复篇（第 26-30 章）： 驱动修复模式、PCI 子系统补丁示例、回归测试与验收标准。
学习目标： 完成本课程后，学员应能独立定位由
pci_set_master 关闭引发的 DMA 超时问题，掌握从内核日志分析到硬件信号验证的完整排查链路，并具备编写健壮驱动代码的能力。