[TOOLS] Add DTC (Devicetree Compiler) tools

Signed-off-by: GuEe-GUI <[email protected]>

Author: GuEe-GUI

.gitignore

@@ -11,6 +11,7 @@
 *.ilk
 *.old
 *.crf
+*.dtb*
 build
 Debug
 .vs

documentation/6.components/device-driver/ofw/dtc.md

@@ -0,0 +1,270 @@
+# DTC (Devicetree Compiler)
+
+## Introduction to the DTC
+
+Device Tree Compiler, dtc, takes as input a device-tree in a given format and outputs a device-tree in another format for booting kernels on embedded systems.
+Typically, the input format is "dts" (device-tree source), a human readable source format, and creates a "dtb" (device-tree binary), or binary format as output.
+
+> If you not install dtc tools in your host system, the dtc module will tell you how to do.
+
+### Generate DTS
+
+When you get a DTB or FDT file from firmware or the other runtime system, you may want to convert it to dts for reading easier. Just do in your Python or SConscript, dummpy.dtb, eg.:
+
+```python
+import os, sys
+
+RTT_ROOT = os.getenv('RTT_ROOT')
+sys.path.append(RTT_ROOT + '/tools')
+
+from building import *
+import dtc
+
+dtc.dtb_to_dts(RTT_ROOT, "dummpy.dtb")
+```
+
+Then you will get a `dummpy.dts` in current directory, dts file will replace if exists before, so you can try another name like this:
+
+```python
+[...]
+
+dtc.dtb_to_dts(RTT_ROOT, "dummpy.dtb", "dummpy-tmp.dts")
+# or
+dtc.dtb_to_dts(RTT_ROOT, "dummpy.dtb", dts_name = "dummpy-tmp.dts")
+```
+
+### Generate DTB
+
+First, you may want to know some knowledge about dts: [DeviceTree Specification](https://devicetree-specification.readthedocs.io/en/latest/chapter2-devicetree-basics.html)
+
+#### Include and Macros
+
+Gog, dtc is not supports preprocess like C preprocessor (cpp), but you can use cpp to do it in the dts, don't worry, we have appended the step in dtc module.
+
+When you have some `dt-bindings` include files or macros, like this:
+
+```c
+/*
+ * Used "#include" if header file need preprocessor,
+ * `components/drivers/include` and current directory path is default.
+ */
+#include <dt-bindings/size.h>
+#include "dummy.dtsi"
+/* Well, if dtsi is simple, you can use "/include/", it is supported by dtc */
+/include/ "chosen.dtsi"
+
+#define MMIO_BASE   0x10000
+#define MMIO_SIZE   SIZE_GB
+#define MEM_BASE    (MMIO_BASE + MMIO_SIZE)
+
+#ifndef CPU_HARDID
+#define CPU_HARDID  0
+#endif
+
+#ifndef SOC_INTC
+#define SOC_INTC    intc_a
+#endif
+
+/ {
+    #address-cells = <2>;
+    #size-cells = <2>;
+    /*
+     * Macros after "&" will be replaced,
+     * there will affect the interrupt controller in this SoC.
+     */
+    interrupt-parent = <&SOC_INTC>;
+
+    [...]
+
+    memory {
+        /* When there is a calculation, please use "()" to include them */
+        reg = <0x0 MEM_BASE 0x0 (3 * SIZE_GB)>;
+        device_type = "memory";
+    };
+
+    cpus {
+        #size-cells = <0>;
+        #address-cells = <1>;
+
+        /* Macros after "@" will be replaced */
+        cpu0: cpu@CPU_HARDID {
+            reg = <CPU_HARDID>;
+            device_type = "cpu";
+        };
+    };
+
+    /* Macros replace support phandle name, too */
+    intc_a: intc-a {
+        interrupt-controller;
+    };
+
+    intc_b: intc-b {
+        interrupt-controller;
+    };
+
+    [...]
+};
+```
+
+Generate DTS, now:
+
+```python
+import os, sys
+
+RTT_ROOT = os.getenv('RTT_ROOT')
+sys.path.append(RTT_ROOT + '/tools')
+
+from building import *
+import dtc
+
+dtc.dts_to_dtb(RTT_ROOT, ["dummpy.dts"]
+```
+
+Append more include path, like SoC DM directory:
+
+```python
+[...]
+
+dtc.dts_to_dtb(RTT_ROOT, ["dummpy.dts"], include_paths = ['dm/include', 'firmware'])
+```
+
+Maybe you have other ideas?
+
+#### Multiple DTB
+
+SoC have different SBC, eg. `dummy.dtsi`:
+```c
+/* SoC dummy */
+/ {
+    #address-cells = <2>;
+    #size-cells = <2>;
+    model = "Dummy SoC Board";
+
+    [...]
+
+    chosen {
+        bootargs = "cma=8M coherent_pool=2M";
+    };
+
+    reserved-memory {
+        #address-cells = <2>;
+        #size-cells = <2>;
+
+        isp_shm@100000 {
+            reg = <0x0 0x100000 0x0 0x100000>;
+        };
+
+        dsp_shm@200000 {
+            reg = <0x0 0x200000 0x0 0x100000>;
+        };
+    };
+
+    dsp {
+        status = "okay";
+    };
+
+    buddy {
+        isp = <&{/reserved-memory/isp_shm@100000}>;
+        dsp = <&{/reserved-memory/dsp_shm@200000}>;
+    };
+
+    uart0: uart {
+        status = "disabled";
+    };
+
+    i2c0: i2c {
+        status = "okay";
+    };
+
+    [...]
+};
+```
+
+If you want to enable or disable a device in vendorA:
+
+```c
+/* vendorA dummy */
+#include "dummy.dtsi"
+
+/ {
+    /* No phandle name can modify in place */
+    chosen {
+        bootargs = "console=uart0 cma=8M coherent_pool=2M";
+    };
+};
+
+/* Reference and modify direct if has phandle name */
+&uart0 {
+    status = "okay";
+    pinctrl-0 = <&uart0_m1>;
+};
+
+&i2c0 {
+    status = "disabled";
+};
+```
+
+Some nodes will parse by kernel without "status", disable them by this way:
+
+```c
+/* vendorB dummy */
+#include "dummy.dtsi"
+
+/delete-node/ &dsp_shm;
+
+/ {
+    /* Delete in place if no phandle name */
+    /delete-node/ dsp;
+
+    /* Delete property */
+    buddy {
+        /delete-property/ dsp;
+    };
+};
+```
+
+New device on bus?
+
+```c
+/* vendorC dummy */
+#include "dummy.dtsi"
+
+&i2c0 {
+    rtc@0 {
+        clock-frequency = <32768>;
+    };
+};
+```
+
+Build dtb together:
+
+```python
+[...]
+
+dtc.dts_to_dtb(RTT_ROOT, ["dummpy-vendorA.dts", "dummpy-vendorB.dts", "dummpy-vendorC.dts"])
+```
+
+Will get `dummpy-vendorA.dtb`, `dummpy-vendorB.dtb`, `dummpy-vendorC.dtb`
+
+### Warnings
+
+Irrelevant warnings are annoying, but dtc do it, you can remove them like this:
+
+```python
+[...]
+
+dtc.dts_to_dtb(RTT_ROOT, ["dummpy.dts"], ignore_warning = ["simple_bus_reg", "unit_address_vs_reg", "clocks_is_cell", "gpios_property"])
+```
+
+**Confirm your dts is right, please :)**
+
+### Raw options
+
+DTC have more raw options than generate dts show by `dtc --help`, like to append them like this:
+
+```python
+[...]
+
+dtc.dtb_to_dts(RTT_ROOT, "dummpy.dtb", options = "--quiet")
+dtc.dts_to_dtb(RTT_ROOT, ["dummpy.dts"], options = "--quiet ")
+```

tools/dtc.py

@@ -0,0 +1,52 @@
+#
+# Copyright (c) 2006-2023, RT-Thread Development Team
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+# Change Logs:
+# Date           Author       Notes
+# 2023-05-10     GuEe-GUI     the first version
+#
+
+import os, re
+
+from building import *
+
+__dtc_install_tip = """
+You should install dtc (devicetree compiler) in your system:
+    Linux:
+        Debian/Ubuntu: apt-get install device-tree-compiler
+        Arch/Manjaro: pacman -Sy dtc
+
+    MacOS:
+        brew install dtc
+
+    Windows (MinGW):
+        msys2: pacman -S dtc
+"""
+
+def __check_dtc(value):
+    if value != 0 and os.system("dtc -v") != 0:
+        print(__dtc_install_tip)
+
+def dts_to_dtb(RTT_ROOT, dts_list, options = "", include_paths = [], ignore_warning = []):
+    path = GetCurrentDir() + '/'
+    waring_ops = ""
+    for waring in ignore_warning:
+        waring_ops += " -W no-" + waring
+    for dts in dts_list:
+        dtb = dts.replace('.dts', '.dtb')
+        if not os.path.exists(path + dtb) or os.path.getmtime(path + dtb) < os.path.getmtime(path + dts):
+            tmp_dts = dts + '.tmp'
+            Preprocessing(dts, None, output = tmp_dts, CPPPATH=[RTT_ROOT + '/components/drivers/include'] + include_paths)
+            ret = os.system("dtc -I dts -O dtb -@ -A {} {} {} -o {}".format(waring_ops, options, path + tmp_dts, path + dtb))
+            __check_dtc(ret)
+            if os.path.exists(path + tmp_dts):
+                os.remove(path + tmp_dts)
+
+def dtb_to_dts(RTT_ROOT, dtb_name, dts_name = None, options = ""):
+    path = GetCurrentDir() + '/'
+    if dts_name == None:
+        dts_name = re.sub(r'\.dtb[o]*$', '.dts', dtb_name)
+    ret = os.system("dtc -I dtb -O dts {} {} -o {}".format(options, path + dtb_name, path + dts_name))
+    __check_dtc(ret)