4. PCIe驱动开发环境搭建：QEMU虚拟PCIe设备模拟、内核编译配置与调试工具

在PCIe驱动开发的实战中，一个可复现、可调试的软硬件环境是成功排查链路故障与错误处理的基础。本章将系统讲解如何搭建一套完整的PCIe驱动开发环境，涵盖QEMU虚拟PCIe设备模拟、内核编译配置（特别是CONFIG_PCI_DEBUG）以及lspci/setpci工具的使用。

4.1 QEMU虚拟PCIe设备模拟

QEMU提供了强大的PCIe设备模拟能力，允许开发者创建自定义的PCIe端点设备（Endpoint）或交换机（Switch），并模拟链路训练、配置空间访问、MSI/MSI-X中断以及AER错误注入等场景。

4.1.1 QEMU PCIe模拟架构

QEMU的PCIe模拟基于PCIe总线模型，支持多级总线拓扑。开发者可以通过QEMU的命令行参数或设备后端（Device Backend）来定义设备。

4.1.2 启动QEMU并添加PCIe设备

以下是一个典型的QEMU启动命令，用于创建一个包含PCIe根端口和一个自定义PCIe端点设备的虚拟机：

# 启动 QEMU，添加一个 PCIe 端点设备（使用 pcie-root-port 和 pcie-endpoint）
qemu-system-x86_64 \
  -machine q35,accel=kvm \
  -m 4G \
  -kernel /path/to/bzImage \
  -initrd /path/to/initramfs.cpio.gz \
  -append "console=ttyS0 root=/dev/ram0" \
  -device pcie-root-port,id=rp1,bus=pcie.0,addr=1c.0,slot=1 \
  -device my-pcie-device,bus=rp1,addr=00.0 \
  -nographic

4.1.3 自定义PCIe设备后端开发

QEMU允许通过C语言编写设备后端（Device Backend），注册为PCIe设备。以下是一个最小化的设备模型框架：

/* my_pcie_device.c - 最小化 QEMU PCIe 端点设备后端 */
#include "hw/pci/pci.h"
#include "hw/pci/pcie.h"
#include "qemu/module.h"

#define TYPE_MY_PCIE_DEVICE "my-pcie-device"
OBJECT_DECLARE_SIMPLE_TYPE(MyPCIDeviceState, MY_PCIE_DEVICE)

typedef struct {
    PCIDevice parent_obj;
    MemoryRegion mmio;
} MyPCIDeviceState;

static void my_pcie_device_realize(PCIDevice *pci_dev, Error **errp) {
    MyPCIDeviceState *dev = MY_PCIE_DEVICE(pci_dev);
    // 配置 Vendor ID / Device ID
    pci_config_set_vendor_id(pci_dev->config, 0x1af4);  // Red Hat
    pci_config_set_device_id(pci_dev->config, 0x1111);  // 自定义
    // 注册 MMIO 区域
    memory_region_init_io(&dev->mmio, OBJECT(dev), &my_mmio_ops, dev,
                          "my-pcie-mmio", 0x1000);
    pci_register_bar(pci_dev, 0, PCI_BASE_ADDRESS_SPACE_MEMORY, &dev->mmio);
    // 使能 PCIe 能力
    pcie_endpoint_cap_init(pci_dev, 0x80);
}

static void my_pcie_device_class_init(ObjectClass *klass, void *data) {
    DeviceClass *dc = DEVICE_CLASS(klass);
    PCIDeviceClass *k = PCI_DEVICE_CLASS(klass);
    k->realize = my_pcie_device_realize;
    k->vendor_id = 0x1af4;
    k->device_id = 0x1111;
    k->revision = 0x01;
    k->class_id = PCI_CLASS_OTHERS;
}

static const TypeInfo my_pcie_device_info = {
    .name = TYPE_MY_PCIE_DEVICE,
    .parent = TYPE_PCIE_ENDPOINT_DEVICE,
    .instance_size = sizeof(MyPCIDeviceState),
    .class_init = my_pcie_device_class_init,
};

static void my_pcie_device_register(void) {
    type_register_static(&my_pcie_device_info);
}
type_init(my_pcie_device_register);

4.2 内核编译配置：CONFIG_PCI_DEBUG 与调试选项

内核的PCIe子系统提供了丰富的调试与追踪选项。正确配置这些选项，可以在驱动开发过程中输出详细的链路状态、配置空间访问以及错误处理日志。

4.2.1 关键内核配置项

4.2.2 内核编译与调试日志启用

配置内核时，通过 make menuconfig 进入以下路径：

Device Drivers  --->
  [*] PCI support  --->
    [*] PCI debugging
    [*] PCIe AER error injection support
    [*] PCIe port bus support
    [*] PCI Express Advanced Error Reporting (AER) support

编译完成后，启动内核并挂载debugfs，即可查看PCIe调试日志：

# 挂载 debugfs
mount -t debugfs none /sys/kernel/debug

# 查看 PCI 调试日志（需要 CONFIG_PCI_DEBUG=y）
cat /sys/kernel/debug/pci/*/config

# 动态开启 PCI 子系统的 pr_debug
echo 'file drivers/pci/* +p' > /sys/kernel/debug/dynamic_debug/control

4.3 lspci / setpci 工具使用

lspci 和 setpci 是PCI/PCIe设备调试的瑞士军刀。前者用于枚举和查看设备信息，后者用于直接读写配置空间。

4.3.1 lspci：枚举与诊断

lspci 可以列出所有PCIe设备及其拓扑关系、能力集、链路状态等。

# 列出所有 PCIe 设备，显示详细链路状态
lspci -vvv

# 显示 PCIe 拓扑树
lspci -t

# 查看指定设备的 PCIe 能力（如链路速度、宽度）
lspci -s 01:00.0 -vvv | grep -i "LnkSta\|LnkCap"

典型输出示例：

01:00.0 Non-Volatile memory controller: Device 1af4:1111 (rev 01)
        Subsystem: Red Hat, Inc. Device 1100
        Control: I/O+ Mem+ BusMaster+ SpecCycle- MemWINV- VGASnoop- ParErr- Stepping- SERR- FastB2B- DisINTx+
        Status: Cap+ 66MHz- UDF- FastB2B- ParErr- DEVSEL=fast >TAbort- <TAbort- <MAbort- >SERR- <PERR- INTx-
        Latency: 0
        Interrupt: pin A routed to IRQ 10
        Region 0: Memory at febf0000 (64-bit, non-prefetchable) [size=4K]
        Capabilities: [40] Power Management version 3
        Capabilities: [50] MSI: Enable+ Count=1/1 Maskable- 64bit+
        Capabilities: [70] Express (v2) Endpoint, MSI 00
                DevCap: MaxPayload 128 bytes, PhantFunc 0, Latency L0s <64ns, L1 <1us
                DevSta: CorrErr- UncorrErr- FatalErr- UnsuppReq- AuxPwr- TransPend-
                LnkCap: Port #0, Speed 8 GT/s, Width x4, ASPM L0s L1, Exit Latency L0s <1us, L1 <4us
                LnkSta: Speed 8 GT/s (ok), Width x4 (ok)

4.3.2 setpci：配置空间读写

setpci 允许直接访问PCIe配置空间，用于注入错误、修改设备行为或验证驱动对配置空间的响应。

# 读取 Vendor ID 和 Device ID
setpci -s 01:00.0 0x00.l

# 读取链路状态寄存器（PCIe 能力偏移 0x70 + 0x12）
setpci -s 01:00.0 CAP_EXP+0x12.w

# 写入配置空间：修改 Device Control 寄存器（偏移 0x08），使能 SERR
setpci -s 01:00.0 CAP_EXP+0x08.w=0x0140

# 注入不可校正错误（通过 AER 能力）
setpci -s 01:00.0 CAP_EXP+0x100.l=0x00010000  # 设置 Uncorrectable Error Status

4.3.3 实战：使用 setpci 模拟链路降速

以下步骤演示如何通过 setpci 修改链路控制寄存器，模拟链路降速场景，验证驱动对链路带宽变化的响应：

1. 查看当前链路状态：

   lspci -s 01:00.0 -vvv | grep "LnkSta"

2. 读取 Link Control 寄存器：

   setpci -s 01:00.0 CAP_EXP+0x10.w

3. 设置目标链路速度（例如强制 Gen1）：

   setpci -s 01:00.0 CAP_EXP+0x10.w=0x0020  # 设置 Target Link Speed = 01b (2.5 GT/s)

4. 触发链路重训练：

   setpci -s 01:00.0 CAP_EXP+0x10.w=0x0020:0x0020  # 同时设置 Retrain Link 位

5. 验证链路降速：

   lspci -s 01:00.0 -vvv | grep "LnkSta"

4.4 环境验证与故障排查清单

搭建完环境后，建议按以下清单进行验证，确保所有组件正常工作：