4. 描述符生命周期管理：分配(alloc)、提交(submit)、完成(complete)、释放(free)全流程

DMA 描述符的生命周期是驱动高带宽传输的核心脉络。一个描述符从创建到销毁，依次经历 分配、提交、完成、释放 四个阶段。每个阶段都涉及特定的数据结构操作、硬件交互和内存屏障，任何环节的疏漏都可能导致数据错乱或系统崩溃。

4.1 分配 (Alloc)

描述符的分配通常在驱动初始化阶段或运行时从 DMA 内存池 中获取。分配的核心目标是获取一块物理连续、对齐的内存，用于存放描述符结构体。

• 内存来源：使用 dma_pool_alloc() 或 dma_alloc_coherent()，保证描述符所在内存不会被 CPU 缓存污染（coherent 映射），或通过 dma_map_single() 进行流式映射。
• 初始化：分配后立即清零，设置默认标志位，绑定对应的 DMA 缓冲区地址。
• 并发安全：分配操作通常受 spin_lock 保护，或使用 per-CPU 描述符缓存以减少锁竞争。

/* 描述符分配示例 */
struct dma_desc *desc;
dma_addr_t desc_dma;

desc = dma_pool_alloc(priv->desc_pool, GFP_KERNEL, &desc_dma);
if (!desc)
    return -ENOMEM;

memset(desc, 0, sizeof(*desc));
desc->buf_addr = cpu_to_le32(desc_dma);
desc->flags = 0;
/* 初始化完成回调上下文 */
desc->callback = my_complete_cb;
desc->cb_data = my_data;

4.2 提交 (Submit)

提交阶段将填充好的描述符“交给”DMA 引擎。驱动需要确保描述符内容对硬件可见，然后触发 DMA 开始传输。

/* 描述符提交示例 */
static void submit_desc(struct my_priv *priv, struct dma_desc *desc)
{
    unsigned long flags;

    spin_lock_irqsave(&priv->lock, flags);

    /* 将描述符加入硬件环形缓冲区 */
    priv->ring[priv->prod_idx] = desc;
    priv->prod_idx = (priv->prod_idx + 1) & (RING_SIZE - 1);

    /* 保证描述符写入完成 */
    dma_wmb();

    /* 通知硬件：更新 tail 寄存器 */
    writel(priv->prod_idx, priv->ioaddr + DMA_TAIL_REG);

    spin_unlock_irqrestore(&priv->lock, flags);
}

4.3 完成 (Complete)

DMA 引擎完成传输后，通过 中断 或 轮询 通知驱动。驱动在完成处理函数中遍历已完成的描述符，提取传输状态，并调用用户注册的回调。

• 中断模式：在 ISR 中读取硬件状态寄存器，确定哪些描述符已完成，然后调用 napi_schedule() 或直接处理。
• 轮询模式：驱动定时检查描述符的 done 标志位（由硬件写入），适用于低延迟或中断合并场景。
• 状态提取：读取描述符中的传输字节数、错误标志、时间戳等。

/* 描述符完成处理示例 */
static void process_completed(struct my_priv *priv)
{
    struct dma_desc *desc;
    u32 completed_idx = readl(priv->ioaddr + DMA_HEAD_REG);

    while (priv->cons_idx != completed_idx) {
        desc = priv->ring[priv->cons_idx];

        /* 确保硬件写入对 CPU 可见 */
        dma_rmb();

        if (desc->status & DESC_ERROR) {
            dev_err(priv->dev, "DMA transfer error\n");
            /* 错误处理逻辑 */
        }

        /* 调用完成回调 */
        if (desc->callback)
            desc->callback(desc->cb_data, desc->trans_len);

        priv->cons_idx = (priv->cons_idx + 1) & (RING_SIZE - 1);
    }
}

4.4 释放 (Free)

描述符使用完毕后，必须归还给内存池或空闲链表。释放操作必须确保 DMA 引擎已经不再访问该描述符，否则可能造成 use-after-free 错误。

/* 描述符释放示例 */
static void free_desc(struct my_priv *priv, struct dma_desc *desc, dma_addr_t dma)
{
    /* 确保描述符不再被硬件使用 */
    WARN_ON(desc->flags & DESC_IN_FLIGHT);

    /* 归还给 DMA 内存池 */
    dma_pool_free(priv->desc_pool, desc, dma);
}

/* 批量释放所有描述符（驱动卸载时） */
static void free_all_descs(struct my_priv *priv)
{
    int i;
    for (i = 0; i < RING_SIZE; i++) {
        if (priv->ring[i]) {
            dma_pool_free(priv->desc_pool,
                          priv->ring[i],
                          priv->ring_dma[i]);
            priv->ring[i] = NULL;
        }
    }
}

4.5 生命周期中的内存屏障策略

描述符管理中的内存屏障是保证数据一致性的关键。下表总结了各阶段所需的屏障类型及位置：

4.6 异常路径处理

在实际系统中，描述符生命周期可能因错误而中断。驱动必须处理以下异常场景：

• 描述符分配失败：返回 -ENOMEM，停止提交新描述符，等待已完成描述符释放后再重试。
• DMA 超时：重置 DMA 通道，回收所有飞行中的描述符，调用错误回调。
• 描述符泄漏：在环形缓冲区中，如果 prod_idx 追上 cons_idx，驱动必须停止提交，等待硬件消费。
• 中断丢失：使用 watchdog 定时器定期检查描述符完成状态，防止死锁。

/* 超时恢复示例 */
static void dma_timeout_recovery(struct my_priv *priv)
{
    unsigned long flags;

    spin_lock_irqsave(&priv->lock, flags);

    /* 停止 DMA 引擎 */
    writel(0, priv->ioaddr + DMA_CTRL_REG);

    /* 回收所有飞行中的描述符 */
    while (priv->cons_idx != priv->prod_idx) {
        struct dma_desc *desc = priv->ring[priv->cons_idx];
        desc->flags &= ~DESC_IN_FLIGHT;
        if (desc->error_callback)
            desc->error_callback(desc->cb_data, -ETIMEDOUT);
        priv->cons_idx = (priv->cons_idx + 1) & (RING_SIZE - 1);
    }

    /* 重置硬件指针 */
    writel(0, priv->ioaddr + DMA_TAIL_REG);
    writel(0, priv->ioaddr + DMA_HEAD_REG);

    spin_unlock_irqrestore(&priv->lock, flags);
}