4. DMA 传输描述符：struct dma_async_tx_descriptor

DMA 传输描述符是 DMA 引擎驱动中最重要的数据结构之一。它抽象了一次 DMA 传输任务的所有属性：源地址、目的地址、传输长度、传输方向、硬件链路信息以及完成回调。理解描述符的结构和生命周期，是编写正确、高效 DMA 驱动的核心前提。

4.1 struct dma_async_tx_descriptor 结构体详解

该结构体定义在 include/linux/dmaengine.h 中，是 DMA 事务的通用表示。每个描述符对应一个硬件能够执行的 DMA 传输块（或链中的一个节点）。

struct dma_async_tx_descriptor {
    dma_cookie_t       cookie;          /* 传输的唯一标识 cookie */
    enum dma_status    status;          /* 传输状态：DMA_IN_PROGRESS / DMA_COMPLETE / DMA_ERROR */
    struct list_head   tx_list;         /* 用于硬件链表（DMA 链）的节点 */
    struct dma_chan    *chan;           /* 所属的 DMA 通道 */
    dma_addr_t         phys;            /* 描述符自身的物理地址（硬件链表使用） */
    struct dmaengine_unmap_data *unmap; /* 用于 unmap 和 sync 的辅助数据 */

    /* 回调机制 */
    dma_async_tx_callback      callback;        /* 传输完成回调函数指针 */
    dma_async_tx_callback      callback_result; /* 带结果（残差）的回调 */
    void                      *callback_param;  /* 回调参数 */

    unsigned long              flags;           /* 传输标志：DMA_PREP_INTERRUPT 等 */
    struct dma_descriptor_metadata_ops *metadata_ops; /* 元数据操作（用于 IN 方向） */

    /* 驱动私有数据 */
    struct list_head           node;            /* 用于挂入提交队列 */
    struct list_head           desc_node;       /* 用于挂入通道的已提交/进行中链表 */
};

4.2 描述符的生命周期

一个 DMA 描述符从创建到释放，经历 5 个明确阶段。驱动开发者必须理解每个阶段的职责和约束。

1. 分配（Allocation）： 在 alloc_chan_resources 回调中，驱动预分配一批描述符放入空闲池。避免在数据路径中动态分配内存。
2. 准备（Preparation）： 调用 device_prep_dma_memcpy、device_prep_slave_sg 等回调，填充描述符的源、目的、长度、标志。此时描述符处于“已初始化但未提交”状态。
3. 提交（Submission）： 调用 tx_submit 将描述符放入通道的提交队列，分配 cookie。描述符进入“等待调度”状态。
4. 执行（Execution）： 调用 dma_async_issue_pending 后，驱动将提交队列中的描述符写入硬件寄存器或链表指针，硬件开始传输。
5. 完成与释放（Completion & Free）： 硬件产生中断后，驱动在 tasklet 中更新状态、调用回调，然后将描述符归还空闲池。

4.3 回调函数机制

回调函数是 DMA 引擎向消费者（如块设备层、音频驱动）通知传输完成的异步机制。回调在 tasklet 上下文 中执行，不能睡眠，不能持有锁。

4.3.1 回调注册与触发流程

4.3.2 回调类型与使用场景

4.3.3 驱动中回调的实现要点

/* 消费者设置回调示例 */
struct dma_async_tx_descriptor *desc;
desc = dmaengine_prep_slave_single(chan, buf_dma, len, direction, flags);
if (!desc)
    return -ENOMEM;

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

/* 提交并启动 */
cookie = dmaengine_submit(desc);
dma_async_issue_pending(chan);

/* 回调函数实现（在 tasklet 上下文中执行） */
static void my_dma_callback(void *param)
{
    struct my_priv *priv = param;

    /* 注意：不能睡眠，不能调用 dmaengine_submit 提交同一个 desc */
    complete(&priv->done);  /* 或 wake_up 等轻量同步 */
}

4.4 描述符标志与硬件链

flags 字段控制描述符的行为，常用标志如下：

硬件链（DMA 链表）通过描述符的 tx_list 字段将多个描述符串联。驱动在 device_issue_pending 中将链表首地址写入硬件寄存器，硬件自动遍历执行。

/* 构建 DMA 链示例 */
struct dma_async_tx_descriptor *prev = NULL, *last = NULL;

for (i = 0; i < num_segments; i++) {
    desc = dmaengine_prep_slave_single(chan, sg_dma_address(&sg[i]),
                                       sg_dma_len(&sg[i]), direction,
                                       DMA_PREP_INTERRUPT);
    if (!desc)
        goto err;

    if (prev)
        prev->tx_list.next = &desc->tx_list;  /* 链接 */
    prev = desc;
    last = desc;
}

/* 只有最后一个描述符产生中断 */
last->flags |= DMA_PREP_INTERRUPT;

cookie = dmaengine_submit(last);  /* 提交链尾 */
dma_async_issue_pending(chan);

4.5 描述符管理与内存屏障

描述符的 phys 字段存储描述符自身的物理地址，供硬件通过 DMA 读取。驱动在填充描述符后，必须使用 dma_wmb() 确保描述符内容对硬件可见，然后再将物理地址写入硬件寄存器。

/* 典型硬件链表提交序列 */
desc->src = src_phys;
desc->dst = dst_phys;
desc->len = length;
desc->next = next_desc_phys;

/* 确保描述符内容写入内存 */
dma_wmb();

/* 将描述符物理地址写入硬件链表指针寄存器 */
writel(desc->phys, chan->base + DMA_NEXT_DESC_REG);