4. dmaengine API详解（中）：传输描述符的创建

在DMA驱动开发中，传输描述符（Descriptor）是连接上层业务与底层硬件通道的关键桥梁。Linux dmaengine框架提供了三种核心的描述符创建接口：dmaengine_prep_slave_sg、dmaengine_prep_dma_cyclic 和 dmaengine_prep_interleaved_dma。本章将深入剖析这三个API的语义、适用场景及参数细节，帮助你在实际调优中做出正确的接口选择。

4.1 dmaengine_prep_slave_sg：散聚表传输

dmaengine_prep_slave_sg 是最常用的描述符创建接口，适用于非连续内存区域的批量数据传输。它接收一个散聚表（Scatter-Gather List），将多个不连续的缓冲区组织成一次DMA传输。

4.1.1 函数原型与参数

struct dma_async_tx_descriptor *dmaengine_prep_slave_sg(
    struct dma_chan *chan,
    struct scatterlist *sgl,
    unsigned int sg_nents,
    enum dma_transfer_direction dir,
    unsigned long flags,
    void *context
);

4.1.2 典型使用流程

1. 准备散聚表： 使用 sg_init_table 初始化，sg_dma_address / sg_dma_len 设置物理地址和长度。
2. 映射缓冲区： 调用 dma_map_sg 将虚拟地址转换为DMA可访问的物理地址。
3. 创建描述符： 调用 dmaengine_prep_slave_sg 获得 struct dma_async_tx_descriptor *。
4. 提交与触发： 调用 dmaengine_submit 入队，dma_async_issue_pending 启动传输。

/* 示例：从设备到内存的SG传输 */
struct scatterlist sg;
struct dma_async_tx_descriptor *tx;

sg_init_table(&sg, 1);
sg_dma_address(&sg) = dma_map_single(dev, buf, len, DMA_FROM_DEVICE);
sg_dma_len(&sg) = len;

tx = dmaengine_prep_slave_sg(chan, &sg, 1, DMA_DEV_TO_MEM,
                             DMA_PREP_INTERRUPT, NULL);
if (!tx) {
    dev_err(dev, "Failed to prepare slave sg descriptor\n");
    return -ENOMEM;
}
tx->callback = my_dma_callback;
dmaengine_submit(tx);
dma_async_issue_pending(chan);

4.2 dmaengine_prep_dma_cyclic：循环缓冲传输

循环传输（Cyclic Transfer）专为音频、视频等需要连续数据流的场景设计。它创建一组循环的描述符链，当最后一个描述符执行完毕后自动回绕到第一个，实现无限循环传输。

4.2.1 函数原型与参数

struct dma_async_tx_descriptor *dmaengine_prep_dma_cyclic(
    struct dma_chan *chan,
    dma_addr_t buf_addr,
    size_t buf_len,
    size_t period_len,
    enum dma_transfer_direction dir,
    unsigned long flags
);

4.2.2 循环传输的内部机制

DMA控制器内部将循环缓冲区划分为多个周期（Period），每个周期对应一个硬件描述符。描述符链的最后一个节点指向第一个节点，形成环形结构。当传输进行时，硬件自动加载下一个描述符，无需软件干预。

4.2.3 音频驱动中的典型用法

/* 音频播放场景：循环传输 */
struct dma_async_tx_descriptor *tx;
dma_addr_t dma_buf;

dma_buf = dma_alloc_coherent(dev, AUDIO_BUF_SIZE, &dma_phys, GFP_KERNEL);

tx = dmaengine_prep_dma_cyclic(chan, dma_phys, AUDIO_BUF_SIZE,
                               PERIOD_SIZE, DMA_MEM_TO_DEV,
                               DMA_PREP_INTERRUPT);
if (!tx) {
    dev_err(dev, "Failed to prepare cyclic dma\n");
    dma_free_coherent(dev, AUDIO_BUF_SIZE, dma_buf, dma_phys);
    return -ENOMEM;
}

tx->callback = audio_period_done;
tx->callback_param = my_audio_dev;

dmaengine_submit(tx);
dma_async_issue_pending(chan);

4.3 dmaengine_prep_interleaved_dma：交错传输

交错传输（Interleaved DMA）是dmaengine框架中最高级的描述符创建接口，适用于需要同时操作多个数据帧、多个通道或复杂数据布局的场景，如图像处理、矩阵转置、多通道音频混音等。

4.3.1 函数原型与参数

struct dma_async_tx_descriptor *dmaengine_prep_interleaved_dma(
    struct dma_chan *chan,
    struct dma_interleaved_template *xt,
    unsigned long flags
);

struct dma_interleaved_template 是核心数据结构，定义了源和目标的数据布局：

struct dma_interleaved_template {
    dma_addr_t src_start;      /* 源起始物理地址 */
    dma_addr_t dst_start;      /* 目标起始物理地址 */
    enum dma_transfer_direction dir;
    unsigned int numf;         /* 帧数（Frame Count） */
    size_t frame_size;         /* 每帧大小（字节） */
    struct data_chunk sgl[];   /* 可变长数据块描述数组 */
};

struct data_chunk {
    size_t size;               /* 本块大小 */
    size_t icg;                /* Inter-Chunk Gap，块间间隔 */
    dma_addr_t dst_sgl;        /* 目标端偏移（可选） */
    dma_addr_t src_sgl;        /* 源端偏移（可选） */
};

4.3.2 交错传输的应用场景

4.3.3 交错传输配置示例

/* 图像处理：从640x480图像中提取每行前320像素 */
struct dma_interleaved_template *xt;
struct dma_async_tx_descriptor *tx;

xt = kzalloc(sizeof(*xt) + sizeof(struct data_chunk), GFP_KERNEL);
xt->src_start = src_phys;
xt->dst_start = dst_phys;
xt->dir = DMA_MEM_TO_MEM;
xt->numf = 480;              /* 480行 */
xt->frame_size = 320;        /* 每行取320像素 */
xt->sgl[0].size = 320;       /* 块大小 */
xt->sgl[0].icg = 320;        /* 跳过剩余320像素（640-320） */

tx = dmaengine_prep_interleaved_dma(chan, xt, DMA_PREP_INTERRUPT);
if (!tx) {
    dev_err(dev, "Interleaved DMA prep failed\n");
    kfree(xt);
    return -ENOMEM;
}
tx->callback = image_line_done;
dmaengine_submit(tx);
dma_async_issue_pending(chan);

4.4 三种描述符创建接口对比

4.5 描述符生命周期与资源管理

无论使用哪种创建接口，描述符的生命周期都遵循以下阶段：

1. 创建（Prep）： 分配描述符对象，填充传输参数。
2. 提交（Submit）： 将描述符加入通道的等待队列。
3. 触发（Issue）： 通知DMA控制器开始处理队列中的描述符。
4. 执行（Running）： 硬件正在传输数据。
5. 完成（Complete）： 传输结束，回调函数被调用。
6. 释放（Free）： 描述符被框架回收或显式释放。