4. 旧版 dmaengine API 回顾：回调机制与事务生命周期管理

在开始升级到新 API 之前，必须深入理解旧版 dmaengine 的核心机制。本章聚焦于 回调机制 与 事务生命周期，这是驱动开发者最容易出错、也是新旧 API 差异最大的两个领域。掌握这些概念，后续的移植工作才能有的放矢。

4.1 事务描述符与回调注册

旧版 API 中，一次 DMA 操作被抽象为一个 dma_async_tx_descriptor 结构体。该结构体不仅描述了传输的源、目的、长度等硬件参数，还内嵌了完成回调函数及其参数。

struct dma_async_tx_descriptor {
    dma_cookie_t cookie;                /* 事务的唯一标识 */
    enum dma_ctrl_flags flags;          /* 控制标志，如 DMA_PREP_INTERRUPT */
    dma_async_tx_callback callback;     /* 完成回调函数指针 */
    void *callback_param;               /* 回调函数的用户参数 */
    struct dma_chan *chan;              /* 所属的 DMA 通道 */
    /* ... 其他硬件描述字段 ... */
};

回调函数的类型定义如下：

typedef void (*dma_async_tx_callback)(void *callback_param);

驱动开发者通过 tx_submit 将描述符提交到硬件队列前，必须先设置好 callback 和 callback_param。这一设计将“传输描述”与“完成通知”紧密耦合在一起。

4.2 事务生命周期：从分配到完成

一个典型的旧版 DMA 事务经历以下五个阶段。理解每个阶段的状态转换，是正确使用 API 的前提。

4.3 tx_submit 与 cookie 机制

tx_submit 是连接软件准备与硬件执行的桥梁。调用该函数后，描述符被移交给 DMA 引擎，引擎返回一个 dma_cookie_t 类型的 cookie，用于后续查询事务状态。

4.4 tx_status 与轮询模式

除了依赖回调，旧版 API 也支持通过 tx_status 轮询事务状态。这在不需要中断通知或需要超时控制的场景中非常有用。

enum dma_status dma_async_tx_status(
    struct dma_chan *chan,
    dma_cookie_t cookie,
    struct dma_tx_state *txstate
);

参数 txstate 是一个输出参数，用于返回更详细的状态信息，包括已传输的字节数（residue）和硬件 DMA 计数器的值。

4.5 回调机制的实现细节

旧版 API 的回调触发点位于 DMA 引擎的中断处理函数中。典型的实现流程如下：

1. 硬件中断到达：DMA 控制器完成一次传输，触发中断。
2. 引擎 ISR 处理：调用 device_tx_status 确认完成状态，从完成队列中取出描述符。
3. 回调执行：在 ISR 上下文中直接调用 desc->callback(desc->callback_param)。
4. 描述符回收：将描述符归还给内存池或空闲链表。

4.6 旧版 API 的局限性总结

在进入新 API 之前，先总结旧版设计的主要痛点，这些正是新 API 要解决的核心问题。