4. 描述符链表初始化：内存分配、描述符填充、链表链接、硬件寄存器配置

描述符链表（Descriptor Chain）是 DMA 传输的核心数据结构，它定义了内存与设备之间的数据搬运路径。初始化阶段需要完成四个关键步骤：内存分配、描述符填充、链表链接和硬件寄存器配置。任何一个环节出错，都会导致 DMA 传输失败或数据损坏。

4.1 内存分配：为描述符预留物理连续区域

描述符链表的内存分配通常使用 dma_alloc_coherent() 或 dmam_alloc_coherent() 函数，这两个函数保证返回物理地址连续且 CPU 与设备缓存一致的内存块。

/* 分配描述符链表内存 - 以 32 个描述符为例 */
#define NR_DESCRIPTORS  32
#define DESC_SIZE       64   /* 每个描述符 64 字节 */

struct dma_chan {
    struct dma_desc *desc_virt;   /* CPU 虚拟地址 */
    dma_addr_t       desc_phys;   /* 设备物理地址 */
    unsigned int     nr_desc;
};

static int alloc_descriptor_chain(struct device *dev, struct dma_chan *chan)
{
    size_t total_size = NR_DESCRIPTORS * DESC_SIZE;

    chan->desc_virt = dma_alloc_coherent(dev, total_size,
                                         &chan->desc_phys, GFP_KERNEL);
    if (!chan->desc_virt)
        return -ENOMEM;

    chan->nr_desc = NR_DESCRIPTORS;
    memset(chan->desc_virt, 0, total_size);

    dev_info(dev, "DMA desc chain: virt=%p phys=%pad size=%zu\n",
             chan->desc_virt, &chan->desc_phys, total_size);
    return 0;
}

4.2 描述符填充：配置传输参数

每个描述符包含传输所需的全部参数：源地址、目标地址、传输长度、控制标志和下一个描述符指针。以下是一个典型的 DMA 描述符结构体定义：

/* 硬件描述符结构 - 以某 SoC 为例 */
struct dma_desc {
    __le32 src_addr;       /* 源地址（物理地址） */
    __le32 dst_addr;       /* 目标地址（物理地址） */
    __le16 transfer_size;  /* 传输字节数 */
    __le16 ctrl;           /* 控制标志位 */
    __le32 next_desc;      /* 下一个描述符物理地址 */
    __le32 reserved;       /* 保留/状态字段 */
} __attribute__((packed));

/* 控制标志位定义 */
#define DESC_CTRL_OWN      BIT(15)  /* 硬件所有权位 */
#define DESC_CTRL_IE       BIT(14)  /* 传输完成中断使能 */
#define DESC_CTRL_CHAIN    BIT(13)  /* 链表模式使能 */
#define DESC_CTRL_FIRST    BIT(12)  /* 链表中的第一个描述符 */
#define DESC_CTRL_LAST     BIT(11)  /* 链表中的最后一个描述符 */

填充描述符时，需要按照传输方向设置源/目标地址，并正确配置控制标志位：

static void fill_descriptor(struct dma_desc *desc,
                            dma_addr_t src, dma_addr_t dst,
                            size_t len, bool is_first, bool is_last)
{
    desc->src_addr      = cpu_to_le32(src);
    desc->dst_addr      = cpu_to_le32(dst);
    desc->transfer_size = cpu_to_le16(len);

    /* 构建控制字 */
    u16 ctrl = DESC_CTRL_OWN | DESC_CTRL_CHAIN;
    if (is_first)
        ctrl |= DESC_CTRL_FIRST;
    if (is_last)
        ctrl |= DESC_CTRL_LAST | DESC_CTRL_IE;  /* 最后一个使能中断 */
    desc->ctrl = cpu_to_le16(ctrl);

    /* next_desc 由链表链接阶段填充 */
    desc->next_desc = 0;
}

4.3 链表链接：构建单向或循环链表

描述符链表有两种常见拓扑：单向链表（最后一个描述符的 next 指针为 NULL）和循环链表（最后一个指向第一个）。循环链表常用于连续数据流场景，如音频、视频采集。

static void link_descriptor_chain(struct dma_desc *base_virt,
                                  dma_addr_t base_phys,
                                  unsigned int count, bool is_circular)
{
    unsigned int i;
    dma_addr_t next_phys;

    for (i = 0; i < count; i++) {
        if (i == count - 1) {
            /* 最后一个描述符 */
            if (is_circular)
                next_phys = base_phys;  /* 回绕到第一个 */
            else
                next_phys = 0;          /* 单向链表结束 */
        } else {
            next_phys = base_phys + (i + 1) * sizeof(struct dma_desc);
        }
        base_virt[i].next_desc = cpu_to_le32(next_phys);
    }
}

4.4 硬件寄存器配置：启动 DMA 引擎

描述符链表构建完成后，需要将链表基地址写入 DMA 控制器的寄存器，并配置传输参数。典型的寄存器配置序列如下：

static void configure_dma_hw(struct device *dev, struct dma_chan *chan,
                              dma_addr_t chain_phys)
{
    void __iomem *base = chan->reg_base;
    int ch = chan->channel_id;

    /* 1. 写入链表基地址 */
    writel(chain_phys, base + DMA_LLP(ch));

    /* 2. 配置控制寄存器：使能通道 */
    writel(DMA_CTL_CH_EN, base + DMA_CTL(ch));

    /* 3. 配置模式寄存器：链表模式 + 完成中断 */
    u32 cfg = DMA_CFG_CHAIN_MODE | DMA_CFG_IE_COMPLETE;
    writel(cfg, base + DMA_CFG(ch));

    /* 4. 软件触发启动 */
    writel(DMA_SW_TRIGGER, base + DMA_SW(ch));

    dev_dbg(dev, "DMA ch%d started: LLP=0x%08x\n", ch, chain_phys);
}

4.5 初始化流程总结

完整的描述符链表初始化流程可以归纳为以下步骤：

1. 分配内存：使用 dma_alloc_coherent() 分配物理连续、缓存一致的内存块。
2. 清零并填充：将内存清零，然后为每个描述符设置源/目标地址、传输长度和控制标志。
3. 链接链表：设置每个描述符的 next_desc 指针，决定单向或循环拓扑。
4. 配置硬件：将链表基地址写入 DMA 控制器的 LLP 寄存器，设置模式并启动。
5. 验证所有权：确认第一个描述符的 OWN 位已置位，硬件已取得控制权。

4.6 初始化后的验证检查清单

完成初始化后，建议逐项检查以下内容，确保描述符链表正确配置：