4. PCIe配置空间访问：pci_read_config_*/pci_write_config_* API详解、Capability链表遍历、扩展配置空间（ECAM）访问

PCIe配置空间是软件与设备进行初始化、枚举、错误报告和链路管理的基础接口。本章深入剖析Linux内核中访问配置空间的经典API、Capability链表遍历机制以及扩展配置空间（ECAM）的访问原理，帮助驱动开发者准确、高效地操作PCIe设备的配置寄存器。

4.1 配置空间布局概述

PCIe配置空间分为两个区域：标准配置空间（256字节）和扩展配置空间（4096字节）。标准配置空间兼容PCI协议，包含Vendor ID、Device ID、Command、Status、BAR等关键寄存器；扩展配置空间则引入了PCIe特有的Capability结构，如AER、DPC、VC等。

4.2 pci_read_config_* / pci_write_config_* API详解

Linux内核提供了一组标准API用于读写PCIe配置空间。这些API封装了底层访问机制（IO端口或MMIO），驱动开发者无需关心硬件差异。

4.2.1 API函数原型

4.2.2 典型代码示例：读取并打印设备配置

#include <linux/pci.h>

static void dump_device_config(struct pci_dev *dev)
{
    u16 vendor, device;
    u32 bar0;
    u8 rev, irq;

    /* 读取标准头部信息 */
    pci_read_config_word(dev, PCI_VENDOR_ID, &vendor);
    pci_read_config_word(dev, PCI_DEVICE_ID, &device);
    pci_read_config_byte(dev, PCI_REVISION_ID, &rev);
    pci_read_config_byte(dev, PCI_INTERRUPT_LINE, &irq);
    pci_read_config_dword(dev, PCI_BASE_ADDRESS_0, &bar0);

    dev_info(&dev->dev,
             "Vendor=0x%04x Device=0x%04x Rev=0x%02x IRQ=%d BAR0=0x%08x\n",
             vendor, device, rev, irq, bar0);
}

4.2.3 错误处理与返回值检查

所有pci_read_config_*和pci_write_config_*函数均返回int类型：返回0表示操作成功，返回负值（如-EIO）表示硬件访问失败。驱动必须检查返回值，尤其在热插拔或链路故障场景下。

/* 安全读取示例：带错误检查和默认值 */
static u32 safe_read_config_dword(struct pci_dev *dev, int offset)
{
    u32 val = 0xDEADBEEF;  /* 默认错误标记 */
    int ret;

    ret = pci_read_config_dword(dev, offset, &val);
    if (ret != 0) {
        dev_err(&dev->dev,
                "Failed to read config at offset 0x%x (err=%d)\n",
                offset, ret);
        /* 根据场景决定是否返回默认值或触发恢复流程 */
    }
    return val;
}

4.3 Capability链表遍历

PCIe设备通过Capability链表组织扩展功能。每个Capability结构包含Capability ID、Next Pointer（指向下一个Capability的偏移）以及Capability-specific数据。标准配置空间中，Capability链表从偏移0x34处的Capabilities Pointer开始。

4.3.1 手动遍历Capability链表

驱动开发者可以通过pci_find_capability快速定位指定ID的Capability，或使用pci_find_next_capability遍历所有Capability。

/* 手动遍历所有Capability并打印ID和偏移 */
static void traverse_capabilities(struct pci_dev *dev)
{
    int pos;
    u8 cap_id;

    pos = pci_find_capability(dev, PCI_CAP_ID_FIRST);
    while (pos) {
        pci_read_config_byte(dev, pos + PCI_CAP_LIST_ID, &cap_id);
        dev_info(&dev->dev,
                 "Capability: ID=0x%02x at offset 0x%x\n",
                 cap_id, pos);
        pos = pci_find_next_capability(dev, pos, PCI_CAP_ID_FIRST);
    }
}

4.3.2 使用内核封装函数

内核提供了更高层次的封装，如pci_enable_msi、pci_enable_pcie_error_reporting等，这些函数内部自动完成Capability查找和配置。但在调试或特殊需求下，直接操作Capability寄存器仍然必要。

4.4 扩展配置空间（ECAM）访问

PCIe扩展配置空间（Extended Configuration Access Mechanism, ECAM）是PCIe规范引入的MMIO访问机制。它将设备的配置空间映射到系统内存地址空间，支持对4096字节配置空间的随机访问。

4.4.1 ECAM地址映射原理

ECAM将PCIe段（Segment）、总线（Bus）、设备（Device）、功能（Function）和寄存器偏移（Offset）编码为内存地址：

MMIO地址 = Base + (Bus << 20) | (Device << 15) | (Function << 12) | Offset

其中Base由BIOS/UEFI在系统启动时分配，通常位于高地址区域（如0xC0000000以上）。每个设备功能占用4096字节，每条总线最多支持32个设备×8功能=256个功能。

4.4.2 内核ECAM访问接口

Linux内核通过pci_ecam_ops结构体管理ECAM访问。驱动开发者通常不需要直接操作ECAM映射，而是通过标准pci_read_config_* API间接使用ECAM。但在某些场景（如早期系统初始化、自定义配置空间扫描）下，可能需要直接访问ECAM区域。

/* 直接ECAM访问示例（仅供底层调试使用） */
#include <linux/pci-ecam.h>

static u32 ecam_read_dword(struct pci_ecam_ops *ops,
                           struct pci_bus *bus,
                           unsigned int devfn,
                           int where)
{
    struct pci_config_window *cfg = ops->get_window(bus);
    void __iomem *addr;
    u32 val;

    addr = cfg->win->addr +
           (bus->number << 20) |
           (PCI_SLOT(devfn) << 15) |
           (PCI_FUNC(devfn) << 12) |
           (where & 0xFFC);  /* 32位对齐 */

    val = readl(addr);
    return val;
}

4.4.3 ECAM vs. IO端口访问对比

4.5 实战：遍历并打印所有Capability（含扩展）

以下综合示例演示如何遍历标准Capability和扩展Capability，并打印关键信息。该代码可用于驱动初始化阶段的设备能力探测。

static void dump_all_capabilities(struct pci_dev *dev)
{
    int pos;
    u16 ext_id;
    u8 cap_id, next;

    dev_info(&dev->dev, "=== Standard Capabilities ===\n");
    pos = pci_find_capability(dev, PCI_CAP_ID_FIRST);
    while (pos) {
        pci_read_config_byte(dev, pos + PCI_CAP_LIST_ID, &cap_id);
        pci_read_config_byte(dev, pos + PCI_CAP_LIST_NEXT, &next);
        dev_info(&dev->dev,
                 "  [0x%02x] ID=0x%02x Next=0x%02x\n",
                 pos, cap_id, next);
        pos = next ? pci_find_next_capability(dev, pos, PCI_CAP_ID_FIRST) : 0;
    }

    dev_info(&dev->dev, "=== Extended Capabilities ===\n");
    pos = pci_find_ext_capability(dev, PCI_EXT_CAP_ID_FIRST);
    while (pos) {
        pci_read_config_word(dev, pos + PCI_EXT_CAP_ID, &ext_id);
        dev_info(&dev->dev,
                 "  [0x%03x] ExtID=0x%04x\n",
                 pos, ext_id);
        pos = pci_find_next_ext_capability(dev, pos, PCI_EXT_CAP_ID_FIRST);
    }
}

4.6 常见错误与避坑指南

• 非对齐访问：配置空间寄存器通常要求自然对齐（4字节对齐访问4字节寄存器）。使用pci_read_config_byte读取32位寄存器的低字节是安全的，但写入时需注意字节掩码。
• 热插拔安全：在设备可能被移除的场景下，访问配置空间前应检查设备状态（如pci_device_is_present），并处理返回值。
• Capability链表循环：理论上Capability链表不应成环，但恶意或损坏的设备可能导致无限循环。建议在遍历时增加最大迭代次数保护。
• ECAM映射失效：在PCIe hotplug或SR-IOV使能后，ECAM映射可能动态变化。驱动应通过标准API访问，避免缓存ECAM基地址。
• 原子性：配置空间访问在硬件层面是原子的，但多线程环境下仍需使用pci_lock保护复合操作（如读-修改-写）。