4. DMA控制器设备树绑定规范

设备树中DMA控制器的绑定规范是驱动开发者与硬件描述之间的契约。本章详细解析dma-controller节点、#dma-cells属性、dma-channel-mask以及dma-capabilities的核心定义与配置方法。

4.1 dma-controller 节点结构

每个DMA控制器在设备树中必须声明为一个dma-controller节点，该节点是DMA Engine框架识别硬件控制器的入口。节点通常位于soc总线节点下，包含一组标准属性和控制器特定的属性。

以下是一个典型的DMA控制器节点示例：

dma: dma-controller@1c00000 {
    compatible = "vendor,axi-dma-1.0";
    reg = <0x01c00000 0x1000>;
    interrupts = <0 12 4>;
    #dma-cells = <3>;
    dma-channel-mask = <0x3f>;
    dma-capabilities = <0x0007>;
    clocks = <&clk 5>;
    resets = <&rst 5>;
    dma-channels = <6>;
    status = "okay";
};

4.2 #dma-cells 属性详解

#dma-cells是DMA控制器节点中最重要的绑定属性之一，它定义了DMA请求端（consumer）节点中dmas属性所需的参数个数。该属性直接决定了DMA通道、请求线、优先级等信息的编码方式。

consumer节点中的dmas属性使用示例：

/* #dma-cells = <2> 的情况 */
uart0: serial@1f00000 {
    compatible = "vendor,uart";
    reg = <0x01f00000 0x1000>;
    interrupts = <0 20 4>;
    dmas = <&dma 0 2>,  /* 通道0，请求线2（TX） */
           <&dma 1 3>;  /* 通道1，请求线3（RX） */
    dma-names = "tx", "rx";
};

4.3 dma-channel-mask 属性

dma-channel-mask是一个位掩码属性，用于标识DMA控制器中哪些通道是物理可用的。该属性在硬件设计存在通道缺失或保留通道时尤为重要。

属性格式：

dma-channel-mask = <0x3f>;  /* 位0~5有效，共6个通道 */

位掩码的每一位对应一个DMA通道：

• 位0 → 通道0
• 位1 → 通道1
• 位2 → 通道2
• ……
• 位N → 通道N

当某位为1时，表示该通道可用；为0时表示该通道不可用或保留。

4.4 dma-capabilities 属性

dma-capabilities是一个位掩码属性，用于描述DMA控制器硬件支持的能力集。该属性帮助DMA Engine框架在运行时快速判断控制器是否支持特定传输类型或特性，避免无效的通道请求。

标准能力位定义：

配置示例：

/* 支持MEMCPY + MEMSET + SG */
dma-capabilities = <0x000B>;  /* 0x0001 | 0x0002 | 0x0008 */

/* 支持所有标准能力 */
dma-capabilities = <0x003F>;  /* 位0~5全部置1 */

4.5 属性组合与校验流程

DMA控制器设备树绑定的完整校验流程如下：

1. 节点识别：内核通过compatible匹配驱动，调用of_match_node。
2. 资源获取：解析reg、interrupts、clocks等基础资源。
3. 通道解析：读取dma-channel-mask，确定可用通道位图。
4. 能力解析：读取dma-capabilities，填充dma_device的cap_mask。
5. 翻译注册：根据#dma-cells注册of_dma_xlate回调函数。
6. 通道初始化：遍历可用通道位图，为每个通道分配dma_chan结构并初始化。

4.6 常见问题与避坑指南

dev_info(dev, "channel mask: 0x%x\n", chan_mask);
dev_info(dev, "capabilities: 0x%x\n", caps);
dev_info(dev, "#dma-cells: %d\n", cells);

4.7 完整绑定示例

以下是一个完整的DMA控制器设备树绑定示例，包含所有核心属性：

/ {
    soc {
        dma0: dma-controller@10000000 {
            compatible = "arm,pl330", "arm,primecell";
            reg = <0x10000000 0x1000>;
            interrupts = <0 25 4>;
            #dma-cells = <2>;
            dma-channel-mask = <0x0F>;       /* 通道0~3可用 */
            dma-capabilities = <0x000B>;     /* MEMCPY | MEMSET | SG */
            dma-channels = <4>;
            clocks = <&clk 10>;
            clock-names = "apb_pclk";
            status = "okay";
        };

        uart1: serial@10100000 {
            compatible = "arm,pl011";
            reg = <0x10100000 0x1000>;
            interrupts = <0 30 4>;
            dmas = <&dma0 0 2>,  /* 通道0，请求线2（TX） */
                   <&dma0 1 3>;  /* 通道1，请求线3（RX） */
            dma-names = "tx", "rx";
        };
    };
};

该示例中：

• DMA控制器使用PL330 IP核，兼容ARM PrimeCell标准。
• 仅通道0~3可用（掩码0x0F），支持内存拷贝、内存填充和分散/聚集传输。
• UART1使用通道0和通道1，分别对应TX和RX请求线。