Devicetree Sources Coding Style

DTS 이름과 허용 문자

Devicetree Source(DTS)를 작성할 때 이 지침을 따라야 합니다. 이 규칙은 Devicetree Specification과 `dtc` compiler가 이미 표현하는 규칙, 즉 `W=1` 및 `W=2` build를 포함한 규칙을 보완합니다. 개별 architecture와 subarchitecture는 더 엄격한 추가 규칙을 정의할 수 있습니다.

Devicetree Specification은 node와 property 이름에 넓은 문자 범위를 허용하지만, 이 coding style은 code 가독성을 높이기 위해 범위를 좁힙니다. Node와 property 이름에는 소문자 `[a-z]`, 숫자 `[0-9]`, dash `-`만 사용할 수 있습니다. Label에는 소문자 `[a-z]`, 숫자 `[0-9]`, underscore `_`만 사용할 수 있습니다.

Bus가 다르게 정의하지 않는 한 unit address는 leading zero padding 없이 소문자 hexadecimal digit을 사용해야 합니다. `reg` 같은 property의 hex 값도 소문자 hex를 사용하며, 이때 address 부분은 leading zero로 padding할 수 있습니다.

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

Node 순서

Child에 unit address를 사용하는 모든 bus의 node는 unit address 오름차순으로 정렬해야 합니다. 일부 subarchitecture에서는 이 순서를 깨더라도 같은 종류의 node를 한데 묶을 수 있습니다. 예를 들어 모든 I2C controller를 연속해서 둘 수 있습니다.

Unit address가 없는 node는 node 이름의 영숫자 순으로 정렬해야 합니다. 일부 node 종류는 주 property를 기준으로 정렬할 수 있습니다. 예를 들어 pin configuration state는 `pins` property 값 순으로 둘 수 있습니다.

Board DTS에서 `&label`로 node를 확장할 때 entry는 영숫자 순으로 정렬하거나 DTSI의 순서를 유지해야 하며, 어느 방식을 쓸지는 subarchitecture에 따릅니다. 이러한 규칙은 review에서 쉽게 강제할 수 있고, 같은 파일에 node를 동시에 추가할 때 conflict 가능성을 줄이며 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의 property 순서

Device node property의 권장 순서는 `compatible`, `reg`, `ranges`, 표준/common property, vendor-specific property, 해당하는 경우 `status`, 그리고 각 node 앞에 blank line을 둔 child node입니다. 표준/common property는 vendor prefix 없이 common binding에서 정의된 속성을 뜻합니다.

`status`의 기본값은 `okay`이므로 생략할 수 있습니다. 이 순서는 가장 중요한 `compatible`과 unit address에 맞추는 bus addressing을 node 앞에 두고, 모든 node에서 common property를 비슷한 위치에 배치하며, board resource가 필요한지를 표시하는 최종 정보인 `status`를 마지막에 두려는 방식입니다.

각 group 안의 개별 property는 property 이름의 natural sort order를 따라야 합니다.

/* 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-0v9-supply = <&board_vreg1>;
        vdd-1v8-supply = <&board_vreg4>;
        vdd-3v3-supply = <&board_vreg2>;
        vdd-12v-supply = <&board_vreg3>;
        status = "okay";
}

들여쓰기와 줄바꿈

들여쓰기와 줄바꿈은 `Documentation/process/coding-style.rst`를 따릅니다. 두 IO address를 담는 `reg`처럼 여러 cell을 가진 array에서는 각 entry를 `<>`로 감싸야 합니다.

여러 줄에 걸친 array는 item 경계에서 나누고 이어지는 entry를 첫 줄의 여는 `<`에 맞추는 방식을 권장합니다. 개별 item이 line wrap 제한을 크게 넘지 않는 한 item 자체를 나누는 것은 피합니다.

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 파일은 hardware의 공통되고 재사용 가능한 부분을 나타내도록 구성해야 합니다. 일반적으로 전체 SoC 내용을 담되 SoC에 없는 hardware node는 포함하지 않는 DTSI, 해당하는 경우 System-on-Module 전체처럼 공통 또는 재사용 가능한 hardware 부분을 담는 DTSI, 그리고 board를 나타내는 DTS로 나눕니다.

Board에 존재하는 hardware component는 SoC나 SoM DTSI가 아니라 board DTS에 두어야 합니다. 부분적인 예외는 공통 external reference SoC input clock입니다. 이를 SoC DTSI에 `fixed-clock`으로 작성하고 각 board DTS가 frequency를 제공할 수 있습니다.