2. dma_alloc_coherent 函数原型解析

dma_alloc_coherent 是 Linux DMA 子系统中最核心的 API 之一，用于分配 一致性（Coherent）DMA 缓冲区。理解其函数原型、每个参数的含义以及返回值，是定位分配失败问题的第一步。

2.1 函数原型

#include <linux/dma-mapping.h>

void *dma_alloc_coherent(struct device *dev, size_t size,
                         dma_addr_t *dma_handle, gfp_t gfp,
                         unsigned long attrs);

2.2 参数详解

2.3 参数深度解析

2.3.1 dev — 设备指针

• 必须有效：传入 NULL 或未初始化的设备指针会导致内核崩溃或分配失败。
• 决定 DMA 域：设备关联的 IOMMU 决定了 dma_handle 的地址空间范围。
• NUMA 亲和性：分配的内存优先靠近 dev 所在的 NUMA 节点，提升访问性能。
• 调试信息：分配失败时，dev 的名称会出现在内核日志中，帮助定位。

2.3.2 size — 缓冲区大小

• 单位：字节，但底层分配器按 页（PAGE_SIZE） 对齐。
• 常见错误：传入 0 或过大的值（超过系统可用连续内存）。
• 对齐要求：某些 DMA 控制器要求缓冲区对齐到特定边界（如 64 字节、128 字节）。

2.3.3 dma_handle — DMA 总线地址输出

• 关键输出：设备 DMA 引擎使用此地址，而非 CPU 虚拟地址。
• 类型：dma_addr_t 在 32 位系统上为 u32，在 64 位系统上为 u64。
• 检查：分配成功后必须检查 dma_handle 是否在设备支持的地址范围内。

2.3.4 gfp — 内存分配标志

2.3.5 attrs — DMA 属性标志

2.4 返回值含义

2.5 函数调用流程与内存映射关系

下图展示了 dma_alloc_coherent 从调用到返回的完整流程，以及 CPU 虚拟地址、物理地址、DMA 总线地址三者之间的映射关系：

2.6 典型使用模式

dma_addr_t dma_handle;
void *cpu_addr;
size_t buf_size = 4096;  // 4KB

cpu_addr = dma_alloc_coherent(dev, buf_size, &dma_handle,
                              GFP_KERNEL, 0);
if (!cpu_addr) {
    dev_err(dev, "dma_alloc_coherent failed for size %zu\n",
            buf_size);
    return -ENOMEM;
}

// 使用 cpu_addr 和 dma_handle 进行 DMA 操作
// ...

// 释放
dma_free_coherent(dev, buf_size, cpu_addr, dma_handle);