3、Linux DMA API详解：dma_alloc_coherent、dma_map_single、dma_pool的使用

在PCIe驱动开发中，DMA（Direct Memory Access）是提升数据传输性能的核心机制。Linux内核提供了一套完善的DMA API，用于管理设备与内存之间的数据搬运。本章将深入剖析三个最常用的DMA接口：dma_alloc_coherent、dma_map_single 和 dma_pool，帮助你在驱动中正确选择和使用它们。

3.1 一致性DMA映射：dma_alloc_coherent

dma_alloc_coherent 用于分配一段 一致性（Coherent） 的DMA缓冲区。所谓“一致性”，是指CPU和设备在任何时刻观察到的内存数据都是一致的，无需额外的缓存刷新操作。该函数返回两个地址：CPU虚拟地址（供驱动访问）和DMA总线地址（供设备访问）。

函数原型与参数

#include <linux/dma-mapping.h>

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

典型使用场景

• 控制结构体：如描述符环（Descriptor Ring）、命令队列控制块。
• 小批量、频繁访问的数据：设备与CPU需要共享状态标志的场景。
• 无需手动同步：硬件保证缓存一致性，适合对延迟敏感的控制路径。

释放接口

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

3.2 流式DMA映射：dma_map_single

流式映射（Streaming Mapping） 是处理大数据块传输的首选方案。它不保证缓存一致性，但通过显式的同步操作（dma_sync_single_for_cpu / dma_sync_single_for_device）来管理数据一致性，从而获得更高的性能和灵活性。

函数原型与参数

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

数据传输方向枚举

同步与解映射

// 同步：在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);

// 解映射：传输完成后释放
void dma_unmap_single(struct device *dev, dma_addr_t dma_handle,
                      size_t size, enum dma_data_direction dir);

3.3 DMA池：dma_pool

dma_pool 是内核提供的一种 固定大小缓冲区预分配机制，专门用于管理大量相同尺寸的DMA缓冲区。它底层基于 dma_alloc_coherent，但通过内存池化技术减少了频繁分配/释放的开销，并避免了内存碎片。

核心API

// 创建DMA池
struct dma_pool *dma_pool_create(const char *name, struct device *dev,
                                 size_t size, size_t align,
                                 size_t boundary);

// 从池中分配一个缓冲区
void *dma_pool_alloc(struct dma_pool *pool, gfp_t mem_flags,
                     dma_addr_t *handle);

// 释放缓冲区回池
void dma_pool_free(struct dma_pool *pool, void *vaddr,
                   dma_addr_t dma);

// 销毁DMA池
void dma_pool_destroy(struct dma_pool *pool);

典型应用场景

• 网络驱动：管理固定大小的SKB数据缓冲区（如1500字节MTU）。
• 存储驱动：管理SCSI命令描述块（CDB）或NVMe队列条目。
• USB/视频驱动：管理等时传输的固定大小数据包。

3.4 三种DMA API对比与选型

3.5 完整使用示例：PCIe驱动DMA初始化

以下代码展示了一个典型的PCIe驱动中，如何组合使用三种DMA API进行初始化：

struct my_pcie_dev {
    struct pci_dev *pdev;
    // 一致性映射：描述符环
    struct desc_ring *ring_cpu;
    dma_addr_t ring_dma;
    // 流式映射：数据缓冲区
    void *data_buf;
    dma_addr_t data_dma;
    // DMA池：命令槽
    struct dma_pool *cmd_pool;
};

static int my_pcie_dma_init(struct my_pcie_dev *dev)
{
    struct device *d = &dev->pdev->dev;

    // 1. 分配一致性内存（描述符环，4KB对齐）
    dev->ring_cpu = dma_alloc_coherent(d, PAGE_SIZE,
                                       &dev->ring_dma, GFP_KERNEL);
    if (!dev->ring_cpu)
        return -ENOMEM;

    // 2. 分配数据缓冲区，并建立流式映射
    dev->data_buf = kmalloc(64 * 1024, GFP_KERNEL);
    if (!dev->data_buf) {
        dma_free_coherent(d, PAGE_SIZE, dev->ring_cpu, dev->ring_dma);
        return -ENOMEM;
    }
    dev->data_dma = dma_map_single(d, dev->data_buf,
                                   64 * 1024, DMA_BIDIRECTIONAL);
    if (dma_mapping_error(d, dev->data_dma)) {
        kfree(dev->data_buf);
        dma_free_coherent(d, PAGE_SIZE, dev->ring_cpu, dev->ring_dma);
        return -ENOMEM;
    }

    // 3. 创建DMA池（每个命令槽256字节，32字节对齐）
    dev->cmd_pool = dma_pool_create("my_cmd_pool", d,
                                    256, 32, 0);
    if (!dev->cmd_pool) {
        dma_unmap_single(d, dev->data_dma, 64 * 1024, DMA_BIDIRECTIONAL);
        kfree(dev->data_buf);
        dma_free_coherent(d, PAGE_SIZE, dev->ring_cpu, dev->ring_dma);
        return -ENOMEM;
    }

    return 0;
}

static void my_pcie_dma_exit(struct my_pcie_dev *dev)
{
    struct device *d = &dev->pdev->dev;

    dma_pool_destroy(dev->cmd_pool);
    dma_unmap_single(d, dev->data_dma, 64 * 1024, DMA_BIDIRECTIONAL);
    kfree(dev->data_buf);
    dma_free_coherent(d, PAGE_SIZE, dev->ring_cpu, dev->ring_dma);
}