设备树DTS使用总结-基于MT76X8

一、Linux设备树的起源

在Linux 2.6中，arch/arm/plat-xxx和arch/arm/mach-xxx中充斥着大量的垃圾代码，相当多数的代码只是在描述板级细节，而这些板级细节对于内核来讲，不过是垃圾，如板上的platform设备、resource、i2c_board_info、spi_board_info以及各种硬件platform_data。
在Linux3.x版本后，arch/arm/plat-xxx和arch/arm/mach-xxx中，描述板级细节的代码（比如platform_device、i2c_board_info等）被大量取消，取而代之的是设备树，其目录位于arch/arm/boot/dts。设备树最早用于PowerPC等其他体系架构，后来应用到ARM架构。

二、设备树原理

1.DTS的加载过程

首先用户要了解硬件配置和系统运行参数，并把这些信息组织成Device Tree source file。
通过DTC（Device Tree Compiler），可以将这些适合人类阅读的Device Tree source file变成适合机器处理的Device Tree binary file（也叫DTB，device tree blob）。
在系统启动的时候，boot program（例如：firmware、bootloader）可以将保存在flash中的DTB copy到内存（或通过bootloader的交互式命令加载DTB，或者firmware可以探测到device的信息，组织成DTB保存在内存中），并把DTB的起始地址传递给client program（例如OS kernel，bootloader或者其他特殊功能的程序）。对于计算机系统（computer system），一般是firmware->bootloader->OS，对于嵌入式系统，一般是bootloader->OS。
本质上，Device Tree改变了原来用hardcode方式将HW 配置信息嵌入到内核代码的方法，改用bootloader传递一个DB的形式。

image

2.DTS的描述信息

Device Tree由一系列被命名的结点（node）和属性（property）组成，而结点本身可包含子结点。所谓属性，其实就是成对出现的name和value。在Device Tree中，可描述的信息包括（原先这些信息大多被hard code到kernel中）：
- CPU的数量和类别
- 内存基地址和大小
- 总线和桥
- 外设连接
- 中断控制器和中断使用情况
- GPIO控制器和GPIO使用情况
- Clock控制器和Clock使用情况

注意：

对于可以动态探测到的设备是不需要描述的，例如USB device。
一个SoC可能对应多个多个产品和电路板，势必这些.dts文件需包含许多共同的部分，Linux内核为了简化，把SoC公用的部分或者多个machine共同的部分一般提炼为.dtsi，类似于C语言的头文件。

三、设备树常见概念

DT : Device Tree
FDT : Flattened DeviceTree
OF : Open Firmware
DTS : Device Tree Source
DTSI : Device Tree Source Include
DTB : Device Tree Blob
DTC : Device Tree Compiler

1.DTS的组成结构

1个root结点"/"
root结点下面含一系列子结点
子结点下又含有一系列子结点
各结点都有一系列属性，属性类型有
- 空属性：empty-property
- 字符串属性：string-property
- 字符串列表属性：string-list-property
- Cells(u32整型)属性：cell-property
- 二进制数属性：binary-property

2.快速编译设备树---DTC (device tree compiler)

将.dts编译为.dtb的工具
DTC的源代码位于内核的scripts/dtc目录，在Linux内核使能了Device Tree的情况下，编译内核的时候主机工具dtc会被编译出来
在Linux内核的arch/arm/boot/dts/Makefile中，描述了当某种SoC被选中后，哪些.dtb文件会被编译出来，如与EXYNOS对应的.dtb包括：

dtb-$(CONFIG_ARCH_EXYNOS) += exynos4210-origen.dtb \
    exynos4210-smdkv310.dtb \
            exynos4412-origen.dtb \

我们可以单独编译Device Tree文件。当我们在Linux内核下运行make dtbs时，若我们之前选择了ARCH_EXYNOS，上述.dtb都会由对应的.dts编译出来
DTC除了可以编译.dts文件以外，其实也可以“反汇编”.dtb文件为.dts文件，其指令格式为：
./scripts/dtc/dtc -I dtb -O dts -o xxx.dts arch/arm/boot/dts/xxx.dtb

3.开发固件设备树---Open Firmware Device Tree

Device Tree可以描述的信息包括CPU的数量和类别、内存基地址和大小、总线和桥、外设连接、中断控制器和中断使用情况、GPIO控制器和GPIO使用情况、Clock控制器和Clock使用情况。
设备树信息被保存在一个ASCII 文本文件中，适合人类的阅读习惯，类似于xml文件，在ARM Linux中，一个.dts文件对应一个ARM的machine放置在内核的arch/arm/boot/dts/
设备树是一种数据结构，用于描述设备信息的语言，具体而言，是用于操作系统中描述硬件，使得不需要对设备的信息进行硬编码(hard code)
Device Tree由一系列被命名的结点（node）和属性（property）组成，而结点本身可包含子结点。所谓属性，其实就是成对出现的name和value
设备树源文件dts被编译成dtb二进制文件，在bootloader运行时传递给操作系统，操作系统对其进行解析展开(Flattened)，从而产生一个硬件设备的拓扑图有了这个拓扑图，在编程的过程中可以直接通过系统提供的接口获取到设备树中的节点和属性信息

四、设备树语法

1.节点node

节点名称：每个节点必须有一个“<名称>[@<设备地址>]”形式的名字：
<名称> 就是一个不超过31位的简单 ascii 字符串，节点的命名应该根据它所体现的是什么样的设备。
<设备地址>用来访问该设备的主地址，并且该地址也在节点的 reg 属性中列出，同级节点命名必须是唯一的，但只要地址不同，多个节点也可以使用一样的通用名称，当然设备地址也是可选的，可以有也可以没有
树中每个表示一个设备的节点都需要一个 compatible 属性

1）节点名称name

name描述设备类型，比如网口宜用ethernet；如果有地址，则用@指定地址

[@]

举例：

cpus {}
serial@101F2000 { }
ethernet@0,0 {}

2.属性property

简单的键－值对，它的值可以为空或者包含一个任意字节流。虽然数据类型并没有编码进数据结构，但在设备树源文件中任有几个基本的数据表示形式:
- 文本字符串（无结束符）可以用双引号表示：
  string-property = "a string"
- Cells是 32 位无符号整数，用尖括号限定：
  cell-property = <0xbeef 123 0xabcd1234>
- 二进制数据用方括号限定：
  binary-property = [01 23 45 67];
- 不同表示形式的数据可以使用逗号连在一起：
  mixed-property = "a string", [01 23 45 67], <0x12345678>;
- 逗号也可用于创建字符串列表：
  string-list = "red fish", "blue fish";

1）compatible属性

指定了系统的名称，是一个字符串列表，它包含了一个“<制造商>,<型号>”形式的字符串。重要的是要指定一个确切的设备，并且包括制造商的名字，以避免命名空间冲突。

compatible = "," [, "model"]
#manufacturer指定厂家名，model指定特定设备型号，后续的model指定兼容的设备型号。

对应到具体的驱动文件定义的设备，如spidev 对应于openwrt/build_dir/target-mipsel_24kc_glibc-2.24/linux-ramips_mt7688/linux-4.4.167/drivers/spi/spidev.c的spidev_spi_driver的name。

举例：

compatible = "smc, smc91c11";
compatible = "samsung,k8f1315ebm", "cfi-flash";

2）#address-cells和#size-cells属性

#address-cells = <1>: 基地址、片选号等绝对起始地址所占字长，单位uint32
#size-cells = <1>: 长度所占字长，单位uint32

external-bus {  
    #address-cells = <2>  
    #size-cells = <1>;  

    ethernet@0,0 {  
        compatible = "smc,smc91c111";  
        reg = <0 0 0x1000>;   // 地址占两个cells， 长度占1个cells
        nterrupts = < 5 2 >;  
     };  
}

3）reg属性

reg = ...: addr表明基址，len表明长度，addr由#address-cells个uint32值组成，len由#size-cells个uint32值组成。表明了设备使用的一个地址范围。

/{
compatible = "acme,coyotes-revenge";
#address-cells = <1>;
#size-cells = <1>;
serial@101f2000 {  
        compatible = "arm,pl011";  
        reg = <0x101f2000 0x1000 >;  

    interrupts = < 2 0 >;  
    };
｝

4）中断属性

interrupt-parent - 设备结点透过它来指定它所依附的中断控制器的phandle，当结点没有指定interrupt-parent时，则从父级结点继承。
interrupt-controller - 一个空的属性定义该节点作为一个接收中断信号的设备
#interrupt-cells - 表明连接此中断控制器的设备的interrupts属性的cell大小（个数）
interrupts - 一个中断指示符的列表，对应于该设备上的每个中断输出信号，在ARM GIC中：
- 当#interrupt-cells为3时，interrupts包含三个cells，如interrupts = <0 168 4> [, <0 169 4>]
  - 第一个cell代表中断类型：0 表示SPI中断，1 表示PPI中断
  - 第二个cell代表具体的中断类型：、
    - PPI中断：私有外设中断(Private Peripheral Interrupt)，是每个CPU私有的中断。最多支持16个PPI中断，范围【0 - 15】。
    - SPI中断类型：公用外设中断(Shared Peripheral Interrupt)，最多可以支持988个外设中断，范围【0 - 987】。
  - 第三个cell代表中断触发标志：
    - bits [ 3 ：0 ] 触发类型和级别标志：
      1 = 低- 至- 高边沿触发
      2 = 高- 到- 低边沿触发
      4 = 活跃的高水平- 敏感
      8 = 低电平有效- 敏感
    - bits [ 15 ：8 ] PPI中断cpu掩码。每个位对应于每个位附加到GIC的8个可能的cpu。指示设置为“1”的位中断被连接到该CPU 。只有有效的PPI中断。
- 当#interrupt-cells为2时，interrupts包含2个cells，如interrupts = <2 4>
  - 第一个cell代表具体的中断类型：
    - SGI中断：软件触发中断(Software Generated Interrupt)，通常用于多核间通讯，最多支持16个SGI中断，硬件中断号从ID0~ID15。
    - PPI中断：私有外设中断(Private Peripheral Interrupt)，是每个CPU私有的中断。最多支持16个PPI中断，硬件中断号从ID16~ID31。
    - SPI中断类型：公用外设中断(Shared Peripheral Interrupt)，最多可以支持988个外设中断，硬件中断号从ID32~ID1019。
  - 第二个cell代表中断触发标志：
    - bits [ 3 ：0 ] 触发类型和级别标志：
      1 = 低- 至- 高边沿触发
      2 = 高- 到- 低边沿触发
      4 = 活跃的高水平- 敏感
      8 = 低电平有效- 敏感
    - bits [ 15 ：8 ] PPI中断cpu掩码。每个位对应于每个位附加到GIC的8个可能的cpu。指示设置为“1”的位中断被连接到该CPU 。只有有效的PPI中断。
  备注：ARM GIC V3说明：kernel/Documentation/devicetree/bindings/arm/gic.txt
reg - 指定基物理地址和所述GIC寄存器的大小
- 第一个区域是GIC分销商的注册基数和规模。
- 第二个区域是GIC cpu 接口寄存器的基数和大小。

/ {
    compatible = "acme,coyotes-revenge";
    #address-cells = <1>;
    #size-cells = <1>;
    interrupt-parent = <&intc>;//指定依附的中断控制器是intc

    serial@101f0000 {   //子节点：串口设备
        compatible = "arm,pl011";
        reg = <0x101f0000 0x1000 >;
        interrupts = < 1 0 >;
    };

    intc: interrupt-controller@10140000 { //intc中断控制器
        compatible = "arm,pl190";
        reg = <0x10140000 0x1000 >;
        interrupt-controller;//定义为中断控制器设备
        #interrupt-cells = <2>;
    };
｝

四、设备树文件分析

mt7628/mt7688的设备树管脚配置参考openwrt/build_dir/target-mipsel_24kc_glibc-2.24/linux-ramips_mt7688/linux-4.4.167/arch/mips/ralink/mt7620.c文件

//mt7628an.dtsi文件
/ {
    #address-cells = <1>;
    #size-cells = <1>;
    compatible = "ralink,mtk7628an-soc";

    cpus {
        cpu@0 {
            compatible = "mips,mips24KEc";
        };
    };

    chosen {
        bootargs = "console=ttyS0,57600";
    };

    aliases {
        serial0 = &uartlite;
    };

    cpuintc: cpuintc@0 {
        #address-cells = <0>;
        #interrupt-cells = <1>;
        interrupt-controller;
        compatible = "mti,cpu-interrupt-controller";
    };

    palmbus: palmbus@10000000 {
        compatible = "palmbus";
        reg = <0x10000000 0x200000>;
        ranges = <0x0 0x10000000 0x1FFFFF>;

        #address-cells = <1>;
        #size-cells = <1>;

        sysc: sysc@0 {
            compatible = "ralink,mt7620a-sysc";
            reg = <0x0 0x100>;
        };

        watchdog: watchdog@120 {
            compatible = "ralink,mt7628an-wdt", "mtk,mt7621-wdt";
            reg = <0x120 0x10>;

            resets = <&rstctrl 8>;
            reset-names = "wdt";

            interrupt-parent = <&intc>;
            interrupts = <24>;
        };

        intc: intc@200 {
            compatible = "ralink,mt7628an-intc", "ralink,rt2880-intc";
            reg = <0x200 0x100>;

            resets = <&rstctrl 9>;
            reset-names = "intc";

            interrupt-controller;
            #interrupt-cells = <1>;

            interrupt-parent = <&cpuintc>;
            interrupts = <2>;

            ralink,intc-registers = <0x9c 0xa0
                         0x6c 0xa4
                         0x80 0x78>;
        };

        memc: memc@300 {
            compatible = "ralink,mt7620a-memc", "ralink,rt3050-memc";
            reg = <0x300 0x100>;

            resets = <&rstctrl 20>;
            reset-names = "mc";

            interrupt-parent = <&intc>;
            interrupts = <3>;
        };

        gpio@600 {
            #address-cells = <1>;
            #size-cells = <0>;

            compatible = "mtk,mt7628-gpio", "mtk,mt7621-gpio";
            reg = <0x600 0x100>;

            interrupt-parent = <&intc>;
            interrupts = <6>;

            gpio0: bank@0 {
                reg = <0>;
                compatible = "mtk,mt7621-gpio-bank";
                gpio-controller;
                #gpio-cells = <2>;
            };

            gpio1: bank@1 {
                reg = <1>;
                compatible = "mtk,mt7621-gpio-bank";
                gpio-controller;
                #gpio-cells = <2>;
            };

            gpio2: bank@2 {
                reg = <2>;
                compatible = "mtk,mt7621-gpio-bank";
                gpio-controller;
                #gpio-cells = <2>;
            };
        };

        i2c: i2c@900 {
            compatible = "mediatek,mt7621-i2c";
            reg = <0x900 0x100>;

            resets = <&rstctrl 16>;
            reset-names = "i2c";

            #address-cells = <1>;
            #size-cells = <0>;

            status = "disabled";

            pinctrl-names = "default";
            pinctrl-0 = <&i2c_pins>;
        };

        i2s: i2s@a00 {
            compatible = "mediatek,mt7628-i2s";
            reg = <0xa00 0x100>;

            resets = <&rstctrl 17>;
            reset-names = "i2s";

            interrupt-parent = <&intc>;
            interrupts = <10>;

            txdma-req = <2>;
            rxdma-req = <3>;

            dmas = <&gdma 4>,
                <&gdma 6>;
            dma-names = "tx", "rx";

            status = "disabled";
        };

        spi0: spi@b00 {
            compatible = "ralink,mt7621-spi";
            reg = <0xb00 0x100>;

            resets = <&rstctrl 18>;
            reset-names = "spi";

            #address-cells = <1>;
            #size-cells = <0>;

            pinctrl-names = "default";
            pinctrl-0 = <&spi_pins>;

            status = "disabled";
        };

        uartlite: uartlite@c00 {
            compatible = "ns16550a";
            reg = <0xc00 0x100>;

            reg-shift = <2>;
            reg-io-width = <4>;
            no-loopback-test;

            clock-frequency = <40000000>;

            resets = <&rstctrl 12>;
            reset-names = "uartl";

            interrupt-parent = <&intc>;
            interrupts = <20>;

            pinctrl-names = "default";
            pinctrl-0 = <&uart0_pins>;
        };

        uart1: uart1@d00 {
            compatible = "ns16550a";
            reg = <0xd00 0x100>;

            reg-shift = <2>;
            reg-io-width = <4>;
            no-loopback-test;

            clock-frequency = <40000000>;

            resets = <&rstctrl 19>;
            reset-names = "uart1";

            interrupt-parent = <&intc>;
            interrupts = <21>;

            pinctrl-names = "default";
            pinctrl-0 = <&uart1_pins>;

            status = "disabled";
        };

        uart2: uart2@e00 {
            compatible = "ns16550a";
            reg = <0xe00 0x100>;

            reg-shift = <2>;
            reg-io-width = <4>;
            no-loopback-test;

            clock-frequency = <40000000>;

            resets = <&rstctrl 20>;
            reset-names = "uart2";

            interrupt-parent = <&intc>;
            interrupts = <22>;

            pinctrl-names = "default";
            pinctrl-0 = <&uart2_pins>;

            status = "disabled";
        };

        pwm: pwm@5000 {
            compatible = "mediatek,mt7628-pwm";
            reg = <0x5000 0x1000>;

            resets = <&rstctrl 31>;
            reset-names = "pwm";

            pinctrl-names = "default";
            pinctrl-0 = <&pwm0_pins>, <&pwm1_pins>;

            status = "disabled";
        };

        pcm: pcm@2000 {
            compatible = "ralink,mt7620a-pcm";
            reg = <0x2000 0x800>;

            resets = <&rstctrl 11>;
            reset-names = "pcm";

            interrupt-parent = <&intc>;
            interrupts = <4>;

            status = "disabled";
        };

        gdma: gdma@2800 {
            compatible = "ralink,rt3883-gdma";
            reg = <0x2800 0x800>;

            resets = <&rstctrl 14>;
            reset-names = "dma";

            interrupt-parent = <&intc>;
            interrupts = <7>;

            #dma-cells = <1>;
            #dma-channels = <16>;
            #dma-requests = <16>;

            status = "disabled";
        };
    };

    pinctrl: pinctrl {
        compatible = "ralink,rt2880-pinmux";
        pinctrl-names = "default";
        pinctrl-0 = <&state_default>;

        state_default: pinctrl0 {
        };

        spi_pins: spi {
            spi {
                ralink,group = "spi";
                ralink,function = "spi";
            };
        };

        spi_cs1_pins: spi_cs1 {
            spi_cs1 {
                ralink,group = "spi cs1";
                ralink,function = "spi cs1";
            };
        };

        i2c_pins: i2c {
            i2c {
                ralink,group = "i2c";
                ralink,function = "i2c";
            };
        };

        uart0_pins: uartlite {
            uartlite {
                ralink,group = "uart0";
                ralink,function = "uart0";
            };
        };

        uart1_pins: uart1 {
            uart1 {
                ralink,group = "uart1";
                ralink,function = "uart1";
            };
        };

        uart2_pins: uart2 {
            uart2 {
                ralink,group = "uart2";
                ralink,function = "uart2";
            };
        };

        sdxc_pins: sdxc {
            sdxc {
                ralink,group = "sdmode";
                ralink,function = "sdxc";
            };
        };

        pwm0_pins: pwm0 {
            pwm0 {
                ralink,group = "pwm0";
                ralink,function = "pwm0";
            };
        };

        pwm1_pins: pwm1 {
            pwm1 {
                ralink,group = "pwm1";
                ralink,function = "pwm1";
            };
        };

        pcm_i2s_pins: i2s {
            i2s {
                ralink,group = "i2s";
                ralink,function = "pcm";
            };
        };
    };

    rstctrl: rstctrl {
        compatible = "ralink,mt7620a-reset", "ralink,rt2880-reset";
        #reset-cells = <1>;
    };

    clkctrl: clkctrl {
        compatible = "ralink,rt2880-clock";
        #clock-cells = <1>;
    };

    usbphy: usbphy@10120000 {
        compatible = "ralink,mt7628an-usbphy", "mediatek,mt7620-usbphy";
        reg = <0x10120000 0x1000>;
        #phy-cells = <1>;

        resets = <&rstctrl 22 &rstctrl 25>;
        reset-names = "host", "device";
        clocks = <&clkctrl 22 &clkctrl 25>;
        clock-names = "host", "device";
    };

    sdhci: sdhci@10130000 {
        compatible = "ralink,mt7620-sdhci";
        reg = <0x10130000 0x4000>;

        interrupt-parent = <&intc>;
        interrupts = <14>;

        pinctrl-names = "default";
        pinctrl-0 = <&sdxc_pins>;

        status = "disabled";
    };

    ehci: ehci@101c0000 {
        compatible = "generic-ehci";
        reg = <0x101c0000 0x1000>;

        phys = <&usbphy 1>;
        phy-names = "usb";

        interrupt-parent = <&intc>;
        interrupts = <18>;
    };

    ohci: ohci@101c1000 {
        compatible = "generic-ohci";
        reg = <0x101c1000 0x1000>;

        phys = <&usbphy 1>;
        phy-names = "usb";

        interrupt-parent = <&intc>;
        interrupts = <18>;
    };

    ethernet: ethernet@10100000 {
        compatible = "ralink,rt5350-eth";
        reg = <0x10100000 0x10000>;

        interrupt-parent = <&cpuintc>;
        interrupts = <5>;

        resets = <&rstctrl 21 &rstctrl 23>;
        reset-names = "fe", "esw";

        mediatek,switch = <&esw>;
    };

    esw: esw@10110000 {
        compatible = "mediatek,mt7628-esw", "ralink,rt3050-esw";
        reg = <0x10110000 0x8000>;

        resets = <&rstctrl 23>;
        reset-names = "esw";

        interrupt-parent = <&intc>;
        interrupts = <17>;
    };

    pcie: pcie@10140000 {
        compatible = "mediatek,mt7620-pci";
        reg = <0x10140000 0x100
            0x10142000 0x100>;

        #address-cells = <3>;
        #size-cells = <2>;

        interrupt-parent = <&cpuintc>;
        interrupts = <4>;

        resets = <&rstctrl 26 &rstctrl 27>;
        reset-names = "pcie0", "pcie1";
        clocks = <&clkctrl 26 &clkctrl 27>;
        clock-names = "pcie0", "pcie1";

        status = "disabled";

        device_type = "pci";

        bus-range = <0 255>;
        ranges = <
            0x02000000 0 0x00000000 0x20000000 0 0x10000000 /* pci memory */
            0x01000000 0 0x00000000 0x10160000 0 0x00010000 /* io space */
        >;

        pcie-bridge {
            reg = <0x0000 0 0 0 0>;

            #address-cells = <3>;
            #size-cells = <2>;

            device_type = "pci";
        };
    };

    wmac: wmac@10300000 {
        compatible = "mediatek,mt7628-wmac";
        reg = <0x10300000 0x100000>;

        interrupt-parent = <&cpuintc>;
        interrupts = <6>;

        status = "disabled";

        mediatek,mtd-eeprom = <&factory 0x0000>;
    };
};