2. Linux DMA API 概览：核心分配与映射接口

在 videobuf2 框架中，DMA 内存的分配与映射是驱动开发者必须掌握的基础能力。Linux 内核提供了多套 DMA API，分别适用于不同场景：一致性分配、流式映射、分散/聚集映射 和 DMA 池。本章将逐一剖析这些 API 的语义、适用场景与典型用法。

2.1 dma_alloc_coherent —— 一致性 DMA 缓冲区

dma_alloc_coherent 分配一段 CPU 与 DMA 控制器共享且缓存一致 的内存。硬件在访问该内存时不会产生缓存一致性问题，适合用于描述符环、控制寄存器块等需要频繁同步的数据结构。

// 分配 4KB 一致性缓冲区
dma_addr_t dma_handle;
void *cpu_addr;

cpu_addr = dma_alloc_coherent(dev, SZ_4K, &dma_handle, GFP_KERNEL);
if (!cpu_addr) {
    dev_err(dev, "Failed to allocate coherent DMA memory\n");
    return -ENOMEM;
}

// 使用完毕后释放
dma_free_coherent(dev, SZ_4K, cpu_addr, dma_handle);

2.2 dma_map_single —— 流式映射单缓冲区

dma_map_single 将一段 已存在的内核缓冲区（通常来自 kmalloc 或栈）映射到 DMA 总线地址，并执行必要的 cache 维护操作。它适用于一次性或短时传输，映射开销低，但需要驱动在传输前后显式处理 cache 同步。

void *buffer = kmalloc(buf_size, GFP_KERNEL);
dma_addr_t dma_addr;

dma_addr = dma_map_single(dev, buffer, buf_size, DMA_FROM_DEVICE);
if (dma_mapping_error(dev, dma_addr)) {
    kfree(buffer);
    return -EIO;
}

// 启动 DMA 传输...
// 等待传输完成

dma_unmap_single(dev, dma_addr, buf_size, DMA_FROM_DEVICE);
kfree(buffer);

2.3 dma_map_sg —— 分散/聚集映射

对于非连续的物理内存（如来自 __get_free_pages 或 vmalloc 的页面），dma_map_sg 将 分散/聚集列表（SG list） 映射为 DMA 可访问的地址集合。它是 videobuf2 中处理用户态缓冲区、帧缓冲区的核心映射方式。

struct scatterlist *sgl;
int nents, i;

// 假设 sgl 已初始化，nents 为 SG 条目数
nents = dma_map_sg(dev, sgl, nents, DMA_BIDIRECTIONAL);
if (nents == 0) {
    dev_err(dev, "dma_map_sg failed\n");
    return -ENOMEM;
}

// 遍历映射后的 SG 表
for_each_sg(sgl, sg, nents, i) {
    dma_addr_t dma_addr = sg_dma_address(sg);
    unsigned int dma_len = sg_dma_len(sg);
    // 使用 dma_addr / dma_len 配置 DMA 描述符
}

// 传输完成后解除映射
dma_unmap_sg(dev, sgl, nents, DMA_BIDIRECTIONAL);

2.4 dma_pool —— 小尺寸 DMA 缓冲区池

dma_pool 用于管理 固定大小、频繁分配/释放 的小型 DMA 缓冲区（如 USB 请求块、网络描述符）。它预分配一大块一致性内存，然后从中切分固定大小的对象，减少分配开销和碎片。

struct dma_pool *pool;
dma_addr_t dma_handle;
void *cpu_addr;

// 创建对象大小为 64 字节、16 字节对齐的 DMA 池
pool = dma_pool_create("my_desc_pool", dev, 64, 16, 0);
if (!pool)
    return -ENOMEM;

// 从池中分配一个对象
cpu_addr = dma_pool_alloc(pool, GFP_KERNEL, &dma_handle);
if (!cpu_addr) {
    dma_pool_destroy(pool);
    return -ENOMEM;
}

// 使用 cpu_addr / dma_handle ...

// 释放对象
dma_pool_free(pool, cpu_addr, dma_handle);
dma_pool_destroy(pool);

2.5 API 对比与选型指南

下表从多个维度对比四种 DMA API，帮助你在不同场景下做出正确选择：

2.6 常见错误与调试技巧

• 忘记检查 dma_mapping_error：映射失败时返回的 DMA 地址可能为 0 或特殊标记，必须用 dma_mapping_error 验证。
• 方向错误：DMA_FROM_DEVICE 和 DMA_TO_DEVICE 混淆会导致 cache 刷写方向错误，数据损坏。
• 重复映射：对同一缓冲区多次调用 dma_map_single 而不先 unmap，会造成资源泄漏。
• SG 遍历错误：使用 for_each_sg 时，循环次数应使用 dma_map_sg 的返回值，而非原始 nents。