4、CMA分配API：dma_alloc_from_contiguous()、cma_alloc()函数原型、参数含义与返回值

在CMA子系统中，驱动开发者主要通过两个核心API向CMA区域申请连续物理内存：dma_alloc_from_contiguous() 和 cma_alloc()。前者是DMA层封装接口，后者是CMA核心分配函数。理解两者的原型、参数语义与返回值，是正确使用CMA缓冲的基础。

4.1 核心分配函数：cma_alloc()

cma_alloc() 是CMA子系统最底层的分配入口，直接操作CMA区域位图，负责从指定CMA区域中分配连续物理页。其函数原型如下：

struct page *cma_alloc(struct cma *cma, unsigned long count,
                       unsigned int align, bool no_warn);

参数含义详解

返回值语义

• 成功：返回指向连续物理页块首地址的 struct page * 指针。
• 失败：返回 NULL。失败原因包括：CMA区域内存不足、无法满足对齐要求、迁移页面时发生竞争或超时。

4.2 DMA层封装：dma_alloc_from_contiguous()

dma_alloc_from_contiguous() 是DMA子系统对 cma_alloc() 的封装，专为DMA设备驱动设计，自动处理设备与CMA区域的绑定关系。其函数原型如下：

struct page *dma_alloc_from_contiguous(struct device *dev, size_t size,
                                       unsigned int count, unsigned int align,
                                       bool no_warn);

参数含义详解

4.3 分配流程与内部机制

下图展示了从驱动调用到物理页分配完成的完整流程：

4.4 两个API的对比与选择

4.5 典型调用示例

以下代码展示了一个V4L2摄像头驱动在缓冲区初始化阶段使用 dma_alloc_from_contiguous() 的典型模式：

#include <linux/dma-contiguous.h>

static int cam_buf_alloc(struct device *dev, struct cam_buffer *buf,
                         size_t size)
{
    struct page *page;
    unsigned int count, align;
    dma_addr_t dma_handle;

    /* 计算所需页数和对齐阶数 */
    count = PAGE_ALIGN(size) >> PAGE_SHIFT;
    align = get_order(size);  /* 2^align 字节对齐 */

    /* 从设备绑定的CMA区域分配连续内存 */
    page = dma_alloc_from_contiguous(dev, size, count, align, false);
    if (!page) {
        dev_err(dev, "CMA alloc failed: size=%zu, count=%u\n",
                size, count);
        return -ENOMEM;
    }

    /* 将物理页映射到DMA地址空间 */
    dma_handle = dma_map_page_attrs(dev, page, 0, size,
                                    DMA_BIDIRECTIONAL,
                                    DMA_ATTR_SKIP_CPU_SYNC);
    if (dma_mapping_error(dev, dma_handle)) {
        dma_release_from_contiguous(dev, page, count);
        return -EIO;
    }

    buf->page = page;
    buf->dma_addr = dma_handle;
    buf->size = size;
    return 0;
}

4.6 分配失败常见原因

• CMA区域耗尽：所有可移动页面已被锁定，无法迁移出足够连续空间。
• 对齐冲突：请求的对齐阶数超过CMA区域最大对齐能力。
• 迁移超时：页面迁移过程中被高优先级任务抢占，导致分配超时。
• 设备未绑定CMA：dev->cma_area 为NULL，dma_alloc_from_contiguous() 直接返回NULL。