3. DMA映射API详解：从dma_map_single到一致性内存分配

在PCIe驱动移植过程中，DMA映射是连接设备与系统内存的核心桥梁。本章将深入剖析Linux内核中DMA映射API的完整体系，包括流式映射与一致性映射两大分支，以及同步操作的关键细节。理解这些API的语义差异和正确使用方式，是避免数据损坏、内存泄漏和硬件故障的前提。

3.1 DMA映射的两大分类

Linux内核将DMA映射分为流式映射（Streaming DMA）和一致性映射（Consistent DMA）两类。流式映射适用于短时、频繁的数据传输，每次传输后需要显式同步；一致性映射适用于长期、共享的数据缓冲区，硬件和CPU可随时访问而无需同步。

3.2 dma_map_single / dma_unmap_single

dma_map_single 将内核虚拟地址（通常是 kmalloc 或栈缓冲区）映射为DMA总线地址，供设备直接访问。其原型如下：

dma_addr_t dma_map_single(struct device *dev, void *cpu_addr,
                          size_t size, enum dma_data_direction dir);

参数说明：

• dev：指向PCIe设备的struct device指针，通常通过 &pdev->dev 获取。
• cpu_addr：CPU侧的虚拟地址，必须对齐到缓存行大小（通常64字节）。
• size：映射的字节数。
• dir：数据传输方向，可选值见下表。

对应的解除映射API：

void dma_unmap_single(struct device *dev, dma_addr_t dma_handle,
                      size_t size, enum dma_data_direction dir);

3.3 dma_map_page / dma_unmap_page

dma_map_page 用于映射 struct page 结构体指向的物理页面，适用于高端内存或从块层/网络层获取的页缓存。其原型：

dma_addr_t dma_map_page(struct device *dev, struct page *page,
                        unsigned long offset, size_t size,
                        enum dma_data_direction dir);

与 dma_map_single 的核心区别：

• 输入不同：dma_map_single 接受虚拟地址，dma_map_page 接受 struct page * + 页内偏移。
• 适用内存类型：dma_map_page 可映射 __get_free_pages 分配的页面、块设备bio中的页面、网络skb中的页面。
• 性能：dma_map_page 在IOMMU环境下可能更高效，因为IOMMU以页为单位建立映射。

// 典型用法：映射网络接收缓冲区
struct page *rx_page = alloc_page(GFP_KERNEL);
dma_addr_t dma_addr = dma_map_page(dev, rx_page, 0, PAGE_SIZE,
                                   DMA_FROM_DEVICE);
if (dma_mapping_error(dev, dma_addr)) {
    __free_page(rx_page);
    return -ENOMEM;
}
// 将 dma_addr 写入设备描述符寄存器...
// 传输完成后：
dma_unmap_page(dev, dma_addr, PAGE_SIZE, DMA_FROM_DEVICE);
__free_page(rx_page);

3.4 dma_sync_single_for_cpu / dma_sync_single_for_device

流式映射在传输完成后，CPU和设备之间可能存在缓存一致性问题。这两个API用于在CPU和设备之间同步数据：

void dma_sync_single_for_cpu(struct device *dev, dma_addr_t dma_handle,
                             size_t size, enum dma_data_direction dir);
void dma_sync_single_for_device(struct device *dev, dma_addr_t dma_handle,
                                size_t size, enum dma_data_direction dir);

使用规则：

• CPU准备写入，设备准备读取：CPU写入数据前调用 dma_sync_single_for_cpu（方向为DMA_TO_DEVICE），写入完成后调用 dma_sync_single_for_device 将数据刷出到设备可见的内存。
• 设备写入，CPU准备读取：设备完成写入后，CPU读取前调用 dma_sync_single_for_cpu（方向为DMA_FROM_DEVICE），使CPU缓存失效，读取到最新数据。
• 双向缓冲区：每次切换访问方时都需要同步，方向参数与当前操作方向一致。

3.5 DMA映射与同步的完整流程

下图展示了PCIe驱动中使用流式DMA进行数据传输的完整生命周期：

3.6 一致性DMA分配：dma_alloc_coherent

对于需要长期共享的缓冲区（如描述符环、状态队列），使用一致性DMA分配：

void *dma_alloc_coherent(struct device *dev, size_t size,
                         dma_addr_t *dma_handle, gfp_t flag);

该API返回两个地址：

• 返回值：CPU侧的虚拟地址，可直接解引用。
• dma_handle：设备侧的DMA总线地址，写入设备寄存器。

释放时调用：

void dma_free_coherent(struct device *dev, size_t size,
                       void *cpu_addr, dma_addr_t dma_handle);

3.7 常见调试问题与排查方法

3.8 总结：API选择决策树

在PCIe驱动移植中，根据缓冲区生命周期和访问模式选择合适的DMA映射API：