Devicetree Sources (DTS) Coding Style

编写设备树源 (DTS) 时，请遵守以下准则。它们应被视为对设备树规范和 dtc 编译器（包括 W=1 和 W=2 版本）中已表达的任何规则的补充。

各个架构和子架构可以定义其他规则，从而使编码风格更加严格。

命名和有效字符

设备树规范允许节点和属性名称中使用多种字符，但这种编码风格缩小了范围，以实现更好的代码可读性。

1. 节点和属性名称只能使用以下字符：

• • 小写字符：[a-z]　　
  • 数字：[0-9]
  • 破折号：-

　　 2. 标签只能使用以下字符：　　

• • 小写字母：[a-z]
  • 数字：[0-9]
  • 下划线：_

　　 3. 除非总线有不同的定义，否则单元地址应使用小写十六进制数字，不带前导零（填充）。

　　 4. 属性中的十六进制值（例如“reg”）应使用小写十六进制。地址部分可以用前导零填充。

例子：

gpi_dma2: dma-controller@a00000 {
        compatible = "qcom,sm8550-gpi-dma", "qcom,sm6350-gpi-dma";
        reg = <0x0 0x00a00000 0x0 0x60000>;
}

node顺序

1. 因此，任何总线上的节点都使用子节点的单元地址，应按单元地址升序排序。或者，对于某些子架构，可以将相同类型的节点分组在一起，例如，所有 I2C 控制器一个接一个地分组，即使这会破坏单元地址排序。
2. 没有单元地址的节点应按节点名称的字母数字顺序排序。对于少数节点类型，它们可以按主属性排序，例如，按“pins”属性值排序的引脚配置状态。
3. 通过 &label 扩展board DTS 中的节点时，条目应按字母数字顺序排序或保持 DTSI 的顺序，其中选择取决于子架构。

上述排序规则在审查期间易于执行，减少了同时将新节点添加到文件时发生冲突的可能性，并有助于浏览 DTS Source。

/* SoC DTSI */

/ {
        cpus {
                /* ... */
        };

        psci {
                /* ... */
        };

        soc@0 {
                dma: dma-controller@10000 {
                        /* ... */
                };

                clk: clock-controller@80000 {
                        /* ... */
                };
        };
};

/* Board DTS - alphabetical order */

&clk {
        /* ... */
};

&dma {
        /* ... */
};

/* Board DTS - alternative order, keep as DTSI */

&dma {
        /* ... */
};

&clk {
        /* ... */
};

Device Node中的属性顺序

设备节点中的属性顺序如下：

1. “compatible”
2. “reg”
3. “ranges”
4. 标准/通用属性（由通用绑定定义，例如没有供应商前缀）
5. 供应商特定属性
6. “status”（如果适用）
7. 子节点，每个节点前面都有一个空白行

“status”属性默认为“okay”，因此可以省略。

上述顺序遵循以下方法：

1. 最重要的属性启动节点：compatible，然后总线寻址以匹配单元地址。
2. 每个节点在类似位置都有共同的属性。
3. status是最后的信息，用于注释设备节点是否完成（需要板资源）。

例子：

/* SoC DTSI */

device_node: device-class@6789abc {
        compatible = "vendor,device";
        reg = <0x0 0x06789abc 0x0 0xa123>;
        ranges = <0x0 0x0 0x06789abc 0x1000>;
        #dma-cells = <1>;
        clocks = <&clock_controller 0>, <&clock_controller 1>;
        clock-names = "bus", "host";
        #address-cells = <1>;
        #size-cells = <1>;
        vendor,custom-property = <2>;
        status = "disabled";

        child_node: child-class@100 {
                reg = <0x100 0x200>;
                /* ... */
        };
};

/* Board DTS */

&device_node {
        vdd-supply = <&board_vreg1>;
        status = "okay";
}

缩进和换行

1. 根据 Linux 内核编码风格使用缩进和换行。
2. 具有多个单元格的数组中的每个条目（例如具有两个 IO 地址的“reg”）应括在 <> 中。
3. 对于跨行的数组，最好在项目边界上拆分，并将后续条目与第一行开头的 < 对齐。通常避免拆分单个项目，除非它们明显超出换行限制。

例子：

thermal-sensor@c271000 {
        compatible = "qcom,sm8550-tsens", "qcom,tsens-v2";
        reg = <0x0 0x0c271000 0x0 0x1000>,
              <0x0 0x0c222000 0x0 0x1000>;
        /* Lines exceeding coding style line wrap limit: */
        interconnects = <&aggre1_noc MASTER_USB3_0 0 &mc_virt SLAVE_EBI1 0>,
                        <&gem_noc MASTER_APPSS_PROC 0 &config_noc SLAVE_USB3_0 0>;
};

组织 DTSI 和 DTS

DTSI 和 DTS 文件应以代表硬件的通用、可重用部分的方式组织。通常，这意味着将 DTSI 和 DTS 文件组织成几个文件：

1. DTSI 包含整个 SoC 的内容，不包括 SoC 上不存在的硬件节点。
2. 如果适用：DTSI 包含硬件的通用或可重复使用部分，例如整个系统级模块。
3. DTS 代表主板。

主板上存在的硬件组件应放置在板 DTS 中，而不是 SoC 或 SoM DTSI 中。部分例外是通用外部参考 SoC 输入时钟，它可以在 SoC DTSI 中编码为固定时钟，其频率由每个板 DTS 提供。