3. DMA传输描述符

DMA 传输描述符是驱动与 DMA 引擎之间的核心契约。它封装了一次传输所需的所有参数：源地址、目的地址、传输长度、硬件链路指针、完成回调以及状态标志。理解描述符的结构与生命周期，是正确使用 DMA 引擎的前提。

3.1 描述符核心结构：struct dma_async_tx_descriptor

该结构体定义在 <linux/dmaengine.h> 中，是 DMA 事务的抽象表示。每个描述符对应一个或多个硬件描述符（取决于引擎是否支持 scatter-gather）。

3.2 描述符生命周期

一个描述符从创建到释放经历四个明确阶段。环形缓冲区设计需要精确管理每个阶段的状态转换。

1. 预备（Prepared）：调用 device_prep_dma_* 系列函数（如 dmaengine_prep_slave_sg()）获得描述符。此时描述符属于驱动，可以设置回调、参数和 flags。
2. 提交（Submitted）：调用 tx_submit 将描述符移交给 DMA 引擎的软件待处理队列。引擎返回一个 cookie，驱动用此 cookie 跟踪传输状态。
3. 触发（Issued）：调用 issue_pending 通知引擎将待处理队列中的描述符写入硬件寄存器或链表，启动实际 DMA 传输。
4. 完成（Completed）：硬件传输结束，引擎调用回调（如果设置了 DMA_PREP_INTERRUPT），驱动在回调中释放描述符或将其归还到空闲池。

3.3 tx_submit：提交描述符

tx_submit 是描述符的方法，调用后将描述符加入 DMA 引擎的软件待处理队列。该函数是原子操作，不能在中断上下文之外睡眠。

struct dma_async_tx_descriptor *desc;
dma_cookie_t cookie;

desc = dmaengine_prep_slave_sg(chan, sgt, nents, dir, DMA_PREP_INTERRUPT);
if (!desc) {
    dev_err(dev, "Failed to prepare DMA descriptor\n");
    return -ENOMEM;
}

desc->callback = my_dma_callback;
desc->callback_param = my_priv;

/* 提交描述符，获得 cookie */
cookie = desc->tx_submit(desc);
if (dma_submit_error(cookie)) {
    dev_err(dev, "Failed to submit DMA descriptor\n");
    desc->desc_free(desc);
    return -EIO;
}

3.4 issue_pending：触发传输

issue_pending 是通道的方法，调用后 DMA 引擎将待处理队列中的所有描述符写入硬件，启动实际传输。该函数通常不阻塞，但具体行为取决于硬件实现。

/* 触发所有待处理的描述符 */
dma_async_issue_pending(chan);

/* 或者直接调用通道方法 */
chan->device->device_issue_pending(chan);

3.5 描述符状态查询

驱动通过 cookie 查询传输状态，常用函数为 dma_async_is_tx_complete() 或 dmaengine_tx_status()。

enum dma_status status;
status = dmaengine_tx_status(chan, cookie, NULL);
if (status == DMA_COMPLETE) {
    /* 传输完成，可以重用描述符 */
} else if (status == DMA_ERROR) {
    /* 传输出错，需要复位通道 */
}

3.6 环形缓冲区中的描述符管理策略

在环形缓冲区设计中，描述符的生命周期与缓冲区槽位绑定。典型策略如下：

• 预备阶段：从空闲池获取描述符，设置源/目的地址指向环形缓冲区当前槽位。
• 提交阶段：调用 tx_submit，将描述符加入软件待处理队列，同时将槽位标记为“提交中”。
• 触发阶段：调用 issue_pending，硬件开始处理。此时槽位数据正在被 DMA 读取或写入。
• 完成阶段：回调中将描述符归还空闲池，槽位标记为“空闲”，唤醒等待的生产者或消费者。