4. Linux DMA引擎框架：dmaengine API概述、dma_device结构体、dma_chan通道管理

Linux内核自2.6.32版本起引入了统一的DMA引擎框架（dmaengine），旨在解决不同DMA控制器驱动接口碎片化的问题。该框架为设备驱动开发者提供了一套标准化的API，用于申请DMA通道、配置传输参数、提交传输请求以及异步等待传输完成。本章将深入剖析dmaengine框架的核心组件：API体系、dma_device结构体以及dma_chan通道管理机制。

4.1 dmaengine API概述

dmaengine API分为两个层次：消费者API（供外设驱动使用）和提供者API（供DMA控制器驱动实现）。消费者API是驱动开发者最常接触的接口，其核心操作流程如下：

1. 通道申请：通过dma_request_chan()或dma_request_slave_channel()获取一个DMA通道。
2. 描述符准备：调用dmaengine_prep_slave_sg()、dmaengine_prep_dma_cyclic()或dmaengine_prep_interleaved_dma()创建传输描述符。
3. 回调绑定：通过dmaengine_submit()将描述符提交到硬件队列前，设置callback和callback_param。
4. 传输启动：调用dma_async_issue_pending()触发硬件开始搬运。
5. 同步等待：使用dma_sync_wait()或DMA完成回调获取传输结果。

4.2 dma_device结构体深度解析

dma_device是DMA控制器驱动向内核注册的核心结构体，它描述了DMA控制器的硬件能力和操作函数集。该结构体定义在include/linux/dmaengine.h中，是连接硬件与框架的桥梁。

struct dma_device {
    unsigned int chancnt;           /* 通道数量 */
    unsigned int max_burst;         /* 最大突发传输长度 */
    u32 src_addr_widths;            /* 支持的源地址宽度位掩码 */
    u32 dst_addr_widths;            /* 支持的目的地址宽度位掩码 */
    u32 directions;                 /* 支持的数据传输方向位掩码 */
    u32 residue_granularity;        /* 剩余数据量粒度 */
    struct list_head channels;      /* 通道链表头 */
    struct dma_cap_mask_t cap_mask; /* 能力掩码 */

    /* 操作函数指针 */
    int (*device_alloc_chan_resources)(struct dma_chan *chan);
    void (*device_free_chan_resources)(struct dma_chan *chan);
    struct dma_async_tx_descriptor *(*device_prep_slave_sg)(
        struct dma_chan *chan, struct scatterlist *sgl,
        unsigned int sg_len, enum dma_transfer_direction direction,
        unsigned long flags, void *context);
    struct dma_async_tx_descriptor *(*device_prep_dma_cyclic)(
        struct dma_chan *chan, dma_addr_t buf_addr, size_t buf_len,
        size_t period_len, enum dma_transfer_direction direction,
        unsigned long flags);
    int (*device_config)(struct dma_chan *chan,
                         struct dma_slave_config *config);
    int (*device_terminate_all)(struct dma_chan *chan);
    enum dma_status (*device_tx_status)(struct dma_chan *chan,
                                        dma_cookie_t cookie,
                                        struct dma_tx_state *txstate);
    void (*device_issue_pending)(struct dma_chan *chan);
};

4.3 dma_chan通道管理

dma_chan是DMA通道的抽象，代表一个物理DMA通道或虚拟通道。每个dma_chan实例关联到一个dma_device，并维护传输状态、回调函数和客户端私有数据。通道管理涉及分配、配置、使用和释放的全生命周期。

4.3.1 通道状态与生命周期

4.3.2 通道管理核心流程

以下代码片段展示了显示驱动中典型的DMA通道管理流程：

/* 1. 申请DMA通道 */
struct dma_chan *dma_chan;
dma_cap_mask_t mask;
dma_cap_zero(mask);
dma_cap_set(DMA_SLAVE, mask);
dma_chan = dma_request_channel(mask, filter_fn, &filter_param);
if (IS_ERR(dma_chan)) {
    dev_err(dev, "Failed to request DMA channel\n");
    return PTR_ERR(dma_chan);
}

/* 2. 配置从设备参数 */
struct dma_slave_config config = {
    .direction = DMA_MEM_TO_DEV,
    .src_addr_width = DMA_SLAVE_BUSWIDTH_4_BYTES,
    .dst_addr_width = DMA_SLAVE_BUSWIDTH_4_BYTES,
    .src_maxburst = 16,
    .dst_maxburst = 16,
    .dst_addr = display_fifo_phys_addr,
};
dmaengine_slave_config(dma_chan, &config);

/* 3. 准备传输描述符 */
struct dma_async_tx_descriptor *tx;
tx = dmaengine_prep_slave_sg(dma_chan, sgl, sg_nents,
                             DMA_MEM_TO_DEV, DMA_PREP_INTERRUPT, NULL);
if (!tx) {
    dev_err(dev, "Failed to prepare slave sg\n");
    dma_release_channel(dma_chan);
    return -ENOMEM;
}

/* 4. 设置完成回调 */
tx->callback = dma_done_callback;
tx->callback_param = completion;

/* 5. 提交并启动传输 */
dma_cookie_t cookie = dmaengine_submit(tx);
dma_async_issue_pending(dma_chan);

/* 6. 等待传输完成（同步方式） */
dma_sync_wait(dma_chan, cookie);

/* 7. 释放通道 */
dma_release_channel(dma_chan);

4.4 虚拟通道与多通道调度

在支持多通道的DMA控制器中，dma_device的channels链表管理着所有可用通道。dmaengine框架引入了虚拟通道（virtual channel）的概念，允许将多个DMA请求映射到有限的物理通道上。虚拟通道通过virt-dma辅助模块实现，核心数据结构为virt_dma_chan：

struct virt_dma_chan {
    struct dma_chan chan;           /* 基类通道 */
    struct tasklet_struct task;     /* 任务软中断 */
    struct list_head desc_allocated; /* 已分配描述符链表 */
    struct list_head desc_submitted; /* 已提交描述符链表 */
    struct list_head desc_issued;   /* 已下发描述符链表 */
    struct list_head desc_completed; /* 已完成描述符链表 */
    spinlock_t lock;                /* 自旋锁保护链表操作 */
};

在显示驱动开发中，理解虚拟通道的链表管理机制至关重要。当使用dmaengine_submit()提交描述符时，描述符首先进入desc_submitted链表；调用dma_async_issue_pending()后，描述符移至desc_issued链表；硬件传输完成后，描述符移至desc_completed链表，并在tasklet中调用用户注册的回调函数。