4. 一致性内存分配API详解

一致性内存（Coherent Memory）是PCIe DMA传输中保证CPU与设备端看到相同内存视图的关键机制。Linux内核提供两套API用于管理一致性内存：通用对偶API（dma_alloc_coherent / dma_free_coherent）和池化API（dma_pool_create / dma_pool_alloc）。本章从原理、接口、参数、调试角度逐一拆解。

4.1 dma_alloc_coherent / dma_free_coherent

这对API是最常用的一致性内存分配接口，适用于大多数PCIe设备驱动。它们分配物理连续的内存，并返回CPU虚拟地址和DMA总线地址。

4.1.1 函数原型与参数

#include <linux/dma-mapping.h>

dma_addr_t dma_handle;
void *cpu_addr;

cpu_addr = dma_alloc_coherent(dev, size, &dma_handle, gfp_flags);
// 使用内存...
dma_free_coherent(dev, size, cpu_addr, dma_handle);

4.1.2 分配流程与内存布局

dma_alloc_coherent在内核中的执行路径涉及多个子系统：内存管理、DMA API层、IOMMU（如果启用）。下图展示了从驱动调用到物理内存分配的完整流程。

4.1.3 调试要点与常见问题

• 内存泄漏：每次dma_alloc_coherent必须配对dma_free_coherent，否则导致DMA内存区域耗尽。使用kmemleak工具可检测。
• 大小限制：单次分配大小受限于连续物理内存可用性。在长时间运行的系统中，大块分配（>4MB）容易失败。
• GFP标志选择：在中断上下文必须使用GFP_ATOMIC，否则可能导致睡眠报错。
• 地址对齐：返回的dma_handle自动满足设备DMA地址对齐要求（通常至少256字节对齐）。

4.2 dma_pool_create / dma_pool_alloc

当驱动需要频繁分配和释放大量固定大小的一致性内存块（如DMA描述符、网络数据包缓冲区）时，使用dma_pool可以显著减少分配开销和内存碎片。

4.2.1 池化API的优势

4.2.2 API使用示例

#include <linux/dmapool.h>

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

// 创建DMA池：名称、设备、对象大小、对齐边界、分配边界
pool = dma_pool_create("my_desc_pool", &pdev->dev,
                       sizeof(struct my_desc), 64, 0);
if (!pool) {
    dev_err(&pdev->dev, "Failed to create DMA pool\n");
    return -ENOMEM;
}

// 从池中分配一个对象
cpu_addr = dma_pool_alloc(pool, GFP_KERNEL, &dma_handle);
if (!cpu_addr) {
    dev_err(&pdev->dev, "Failed to allocate from DMA pool\n");
    dma_pool_destroy(pool);
    return -ENOMEM;
}

// 使用对象...

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

// 销毁整个池（必须在所有对象释放后调用）
dma_pool_destroy(pool);

4.2.3 参数详解

4.2.4 内部结构图

DMA池在内核中维护一个页链表，每个页被划分为固定大小的槽位。分配和释放操作在槽位级别进行，避免了频繁的页分配。

4.3 调试方法对比

4.4 选择指南

• 优先使用dma_pool：当分配对象大小固定且分配/释放频率较高时（如网络驱动中的RX/TX描述符、USB传输缓冲区）。
• 使用dma_alloc_coherent：当需要一次性分配大块内存（如帧缓冲区、DMA环形缓冲区）或对象大小不固定时。
• 避免混合使用：不要对同一块内存同时使用dma_alloc_coherent和dma_pool_alloc管理，会导致释放混乱。
• 注意对齐要求：如果设备要求特定对齐（如64字节对齐），在dma_pool_create中设置align参数，dma_alloc_coherent自动满足常见对齐。