4. Endpoint设备硬件基础

编写Linux PCIe Endpoint驱动之前，必须先理解Endpoint设备内部的硬件构成。驱动代码本质上是在“翻译”硬件手册：把寄存器位域、DMA描述符、中断状态机翻译成内核可调度的资源。本章从控制器IP、DMA引擎、中断控制器、内存映射与寄存器接口四个维度，建立Endpoint硬件的整体认知模型。

一、Endpoint控制器IP的整体结构

典型的PCIe Endpoint控制器IP（如Synopsys DWC、Cadence PCIe、Xilinx XDMA等）内部由多个子模块组成。它们通过内部总线互联，对外呈现为一条PCIe链路，对内呈现为可被CPU访问的寄存器空间和DMA通道。

• PCIe Core / PHY：负责链路训练、LTSSM状态机、TLP/DLLP生成与解析，是链路层与物理层的实现。
• 配置空间模块：实现Type 0配置头、Capability结构（PCIe Cap、MSI/MSI-X Cap、Power Management Cap等）。
• BAR与地址译码：将Host发来的Memory TLP按BAR区间译码，转发到内部寄存器或RAM。
• DMA引擎：执行Host内存与设备本地内存之间的批量数据搬运。
• 中断控制器：汇聚本地事件，通过MSI/MSI-X或Legacy INTx向Host上报。
• 应用逻辑/用户逻辑：业务功能实现，如加速器、网卡MAC、NVMe前端等。

下图给出一个典型Endpoint控制器IP的内部结构关系，帮助建立“Host侧—链路—设备侧”的层次感。

二、DMA引擎：数据搬运的核心

Endpoint的DMA引擎负责在Host内存与设备本地内存之间搬运数据，是驱动性能的关键。常见实现有两种：

• 描述符环（Descriptor Ring）：驱动在Host内存中分配环形描述符数组，每个描述符包含源地址、目的地址、长度、控制位。设备读取描述符后执行搬运，完成后写回状态位并触发中断。
• 寄存器直接触发：适用于小数据量场景，驱动写源地址、目的地址、长度寄存器，设备启动一次搬运。

以XDMA为例，驱动需要配置的典型寄存器包括：

// XDMA 引擎控制寄存器示例（偏移量示意）
#define XDMA_ENGINE_CTRL      0x0004  // 启动/停止 DMA 引擎
#define XDMA_ENGINE_STATUS    0x0040  // 引擎状态、错误标志
#define XDMA_DESC_LO          0x4080  // 描述符基地址低32位
#define XDMA_DESC_HI          0x4084  // 描述符基地址高32位
#define XDMA_DESC_ADJUST      0x4088  // 描述符环大小（2^n）
#define XDMA_DESC_CREDIT      0x4090  // 描述符信用计数

// 启动 H2C（Host to Card）通道
writel(0x1, base + XDMA_ENGINE_CTRL);
writel(desc_dma_addr & 0xFFFFFFFF, base + XDMA_DESC_LO);
writel(desc_dma_addr >> 32, base + XDMA_DESC_HI);
writel(ilog2(RING_SIZE), base + XDMA_DESC_ADJUST);

驱动必须保证描述符内存对设备可见，通常使用dma_alloc_coherent()分配一致性内存，避免Cache一致性问题。

三、中断控制器与MSI/MSI-X

Endpoint通过中断通知Host“数据已就绪”或“事件已完成”。现代PCIe设备优先使用MSI-X，因为它支持多个中断向量、每个向量独立屏蔽，且不共享中断线。

驱动初始化MSI-X的典型流程：

// 1. 申请MSI-X向量
int nvec = pci_alloc_irq_vectors(pdev, 1, MAX_VECTORS, PCI_IRQ_MSIX);
if (nvec < 0) {
    dev_err(&pdev->dev, "MSI-X alloc failed\n");
    return nvec;
}

// 2. 为每个向量注册中断处理函数
for (i = 0; i < nvec; i++) {
    irq = pci_irq_vector(pdev, i);
    ret = request_irq(irq, my_handler, 0, "my_ep", priv);
}

// 3. 配置设备端中断使能寄存器
writel(0xFFFFFFFF, base + EP_IRQ_ENABLE);

四、内存映射与寄存器接口

Endpoint的寄存器通常映射到某个BAR（如BAR0），驱动通过pci_iomap()将其映射到内核虚拟地址空间，之后用readl()/writel()访问。

// 映射BAR0
bar0 = pci_iomap(pdev, 0, 0);
if (!bar0) {
    dev_err(&pdev->dev, "pci_iomap BAR0 failed\n");
    return -ENOMEM;
}

// 读取设备ID寄存器
u32 dev_id = readl(bar0 + EP_DEV_ID_REG);
dev_info(&pdev->dev, "Endpoint device ID: 0x%08x\n", dev_id);

// 写控制寄存器启动设备
writel(EP_CTRL_ENABLE | EP_CTRL_DMA_START, bar0 + EP_CTRL_REG);

寄存器接口设计通常遵循以下约定：

• 只读状态寄存器：反映设备当前状态，如链路状态、DMA忙标志、错误计数。
• 读写控制寄存器：驱动写入命令，如启动DMA、使能中断、复位通道。
• 中断状态寄存器：记录中断源，驱动读取后写1清除（W1C）。
• 地址寄存器：存放描述符基地址、数据缓冲地址，通常分高低32位。

五、案例：一个最小Endpoint驱动的硬件初始化顺序

假设我们有一个基于XDMA的Endpoint设备，驱动probe函数的硬件初始化顺序如下：

1. pci_enable_device()：使能设备，分配BAR资源。
2. pci_request_regions()：申请BAR区域，防止冲突。
3. pci_iomap()：映射BAR0到内核虚拟地址。
4. 读取设备ID和版本寄存器，确认硬件匹配。
5. pci_alloc_irq_vectors()：申请MSI-X向量。
6. 注册中断处理函数。
7. 分配DMA一致性内存，初始化描述符环。
8. 写DMA引擎控制寄存器，启动通道。
9. 写中断使能寄存器，打开设备中断。

这个顺序不能随意颠倒：必须先映射BAR才能访问寄存器，必须先申请中断向量才能注册处理函数，必须先初始化描述符环才能启动DMA。

六、常见误区与复盘

• 误区一：直接使用物理地址访问寄存器。在使能IOMMU或SMMU的系统中，物理地址不等于设备可见地址，必须使用DMA API分配和映射。
• 误区二：忽略MSI-X Table的BAR映射。MSI-X Table可能位于BAR1或BAR2，驱动需要确保该BAR也被映射。
• 误区三：DMA描述符内存未做Cache一致性处理。使用dma_alloc_coherent()或正确使用dma_map_single()与dma_sync_single_for_device()。
• 误区四：中断处理函数中做耗时操作。中断上下文应尽快完成，将耗时工作交给tasklet或工作队列。