裝置樹詳解

在Linux3.x版本後，arch/arm/plat-xxx和arch/arm/mach-xxx中，描述板級細節的程式碼（比如platform_device、i2c_board_info等）被大量取消，取而代之的是裝置樹，其目錄位於arch/arm/boot/dts

1.裝置樹的組成

1個dts檔案+n個dtsi檔案，它們編譯而成的dtb檔案就是真正的裝置樹

• soc廠商會把soc公共的特性和多塊開發板公用的特性提煉為dtsi，而dts則負責描述某個具體的產品（開發板）的特性。dts直接或間接的包含多個dtsi（類似於c語言的標頭檔案），就體現了一個完整的產品（開發板）所有的特性。以solidrun公司的hummingboard為例，其組成為

imx6dl-hummingboard.dts
        |_imx6dl.dtsi
        |   |_imx6qdl.dtsi
        |_imx6qdl-microsom.dtsi
        |_imx6qdl-microsom-ar8035.dtsi

• 此外，dts/dtsi相容c語言的一些語法，能使用巨集定義，也能包含.h檔案

2.裝置樹的結構

下面分別是是imx6dl-hummingboard.dts以及imx6dl.dtsi檔案，我們以它們為例來分析，不難發現dts檔案內容很少，只有一些板級的特徵，大部分公共的硬體描述都在dtsi檔案中

• imx6dl-hummingboard.dts 檔案節選

/dts-v1/;
#include "imx6dl.dtsi"
#include "imx6qdl-microsom.dtsi"
#include "imx6qdl-microsom-ar8035.dtsi"

/ {
    model = "SolidRun HummingBoard DL/Solo";
    compatible = "solidrun,hummingboard", "fsl,imx6dl";

    ir_recv: ir-receiver {
        compatible = "gpio-ir-receiver";
        gpios = <&
 
gpio1 2 1>;
        pinctrl-names = "default";
        pinctrl-0 = <&pinctrl_hummingboard_gpio1_2>;
    };

    regulators {
        compatible = "simple-bus";

        reg_3p3v: 3p3v {
            compatible = "regulator-fixed";
            regulator-name = "3P3V";
            regulator-min-microvolt = <3300000>;
            regulator-max-microvolt = <3300000>;
            regulator-always-on;
        };
    }

&i2c1 {
    pinctrl-names = "default";
    pinctrl-0 = <&pinctrl_hummingboard_i2c1>;

    rtc: [email protected]68 {
        compatible = "nxp,pcf8523";
        reg = <0x68>;
    };
};

• imx6dl.dtsi檔案節選

/ {
    aliases {

    /*省略無關程式碼*/
    }
    soc {
        #address-cells = <1>;
        #size-cells = <1>;
        compatible = "simple-bus";
        interrupt-parent = <&intc>;
        ranges;

        /*省略無關程式碼*/

        [email protected]00a00600 {
            compatible = "arm,cortex-a9-twd-timer";
            reg = <0x00a00600 0x20>;
            interrupts = <1 13 0xf01>;
            clocks = <&clks IMX6QDL_CLK_TWD>;
        };

        aips-bus@02000000 { /* AIPS1 */
            compatible = "fsl,aips-bus", "simple-bus";
            #address-cells = <1>;
            #size-cells = <1>;
            reg = <0x02000000 0x100000>;
            ranges;

            /*省略無關程式碼*/      

            gpio1: [email protected]0209c000 {
                compatible = "fsl,imx6q-gpio", "fsl,imx35-gpio";
                reg = <0x0209c000 0x4000>;
                interrupts = <0 66 IRQ_TYPE_LEVEL_HIGH>,
                         <0 67 IRQ_TYPE_LEVEL_HIGH>;
                gpio-controller;
                #gpio-cells = <2>;
                interrupt-controller;
                #interrupt-cells = <2>;
            };

            /*省略無關程式碼*/  

            i2c1: [email protected]021a0000 {
                #address-cells = <1>;
                #size-cells = <0>;
                compatible = "fsl,imx6q-i2c", "fsl,imx21-i2c";
                reg = <0x021a0000 0x4000>;
                interrupts = <0 36 IRQ_TYPE_LEVEL_HIGH>;
                clocks = <&clks IMX6QDL_CLK_I2C1>;
                status = "disabled";
            };

        };
            /*省略無關程式碼*/  
    };  
};

基本構造

• {}包圍起來的結構稱之為節點，dts中最開頭的/ {}，稱為根節點。節點的標準結構是[email protected]{…}，xxx是節點的名字，yyy則不是必須的，其值為節點的地址（暫存器地址或其他地址），比如i2c1: [email protected]中的就是一個i2c控制器的暫存器基地址，rtc: [email protected]中的就是這個rtc裝置的i2c地址

屬性：地址

• 有關節點的地址，比如[email protected]，雖然它在名字後面跟了地址，但是正式的設定是在reg屬性中設定的比如：reg = <0x021a0000 0x4000>; reg的格式通常為<address length>，0x021a0000是暫存器基地址，0x4000是長度。address 和length的個數是可變的，由父節點的屬性#address-cells 和#size-cells 決定，比如節點[email protected]的父節點是[email protected]，其#address-cells 和#size-cells均為1，所以下面的i2c節點的reg屬性就有一個address 和length，而i2c節點本身#address-cells 和#size-cells 分別為1和0，所以其下的rtc: [email protected] 的reg屬性就只有一個0x68（i2c地址）了

屬性：相容性

• 如果一個節點是裝置節點，那麼它一定要有compatible（相容性），因為這將作為驅動和裝置（裝置節點）的匹配依據，compatible（相容性）的值可以有不止一個字串以滿足不同的需求，詳見下一節。而根節點的compatible也是非常重要的，也就是"fsl,imx6dl"這個字串，因為系統啟動後，將根據根節點的compatible來判斷cpu資訊，並由此進行初始化

屬性設定的套路

• 一般來說，每一種裝置的節點屬性設定都會有一些套路，比如可以設定哪些屬性？屬性值怎麼設定？那怎麼知道這些套路呢，有兩種思路 
  
  • 第一種是抄類似的dts，比如我們自己專案的平臺是4412，那麼就可以抄exynos4412-tiny4412.dts、exynos4412-smdk4412.dts這類相近的dts
  • 第二種是查詢核心中的文件，比如Documentation/devicetree/bindings/i2c/i2c-imx.txt就描述了imx平臺的i2c屬性設定方法；Documentation/devicetree/bindings/fb就描述了lcd、lvds這類屬性設定方法

節點之間的聯絡

• 節點與節點之間的關聯，通常通過“標號引用”和“包含”來實現 
  
  • 所謂標號引用，就是在節點名稱前加上標號，這樣裝置樹的其他位置就能夠通過&符號來呼叫/訪問該節點，比如上面程式碼ir_recv節點中的gpio屬性，就引用了gpio1標號處的節點
  • 包含則是最基本的方式，比如我們要在i2c1介面新增一個i2c外設，那麼就必須要在i2c1下面新增一個節點，比如上面程式碼中的rtc: [email protected] {}
• 標號引用常常還作為節點的重寫方式，比如下面程式碼是imx6qdl.dtsi中定義的i2c節點，而前面imx6dl-hummingboard.dts中的&i2c1，就是對i2c1標號處節點的一次重寫，在其內部添加了一個rtc裝置
• 如果一個節點是屬性節點（即僅僅是作為屬性被其他節點呼叫），那麼它定義在哪裡其實無所謂，重要的是呼叫的位置，比如lcd螢幕的時序，其實我們完全可以把它定義在其他犄角旮旯，然後在lcd節點下用&來呼叫它，這也是可以的。這有點類似於函式：在哪定義不重要，重要的是在哪呼叫

3.核心（驅動）與節點的匹配

首先，核心必須要知道dtb檔案的地址，這由U-boot來告訴核心，詳見U-boot引導核心流程分析 第6節。只要核心知曉了dtb檔案的地址，那麼驅動就可以通過一些API任意獲取裝置樹的內部資訊

• 對於3.x版本之後的核心，platform、i2c、spi等裝置不再需要在mach-xxx中註冊，驅動程式將直接和裝置樹裡的裝置節點進行配對，是通過裝置節點中的compatible（相容性）來與裝置節點進行配對的，這裡只做簡單介紹，具體的應用詳見 基於i2c子系統的驅動分析、 基於platform匯流排的驅動分析
• 這裡以pcf8523驅動為例，只要驅動中的of_match_table 中的compatible 值和裝置節點中的compatible 相匹配，那麼probe函式就會被觸發。不僅i2c是這樣，platform、spi等都是這個原理

/*定義的of_match_table*/
static const struct of_device_id pcf8523_of_match[] = {
    { .compatible = "nxp,pcf8523" },
    { }
};

/*driver 結構體中的of_match_table*/
static struct i2c_driver pcf8523_driver = {
    .driver = {
        .name = DRIVER_NAME,
        .owner = THIS_MODULE,
        .of_match_table = of_match_ptr(pcf8523_of_match),
    },
    .probe = pcf8523_probe,
    .id_table = pcf8523_id,
};

• i2c和spi驅動還支援一種“別名匹配”的機制，就以pcf8523為例，假設某程式設計師在裝置樹中的pcf8523裝置節點中寫了compatible = "pcf8523";，顯然相對於驅動id_table中的"nxp,pcf8523"，他遺漏了nxp欄位，但是驅動卻仍然可以匹配上，因為別名匹配對compatible中字串裡第二個欄位敏感

4.常見屬性的設定與獲取

當修改或編寫驅動時，常常需要修改gpio、時鐘、中斷等等引數，以前都是在mach-xxx中的device設定的，現在則要在節點裡設定，然後驅動用特殊的API來獲取

• 屬性的獲取常常在probe函式中進行，但是獲取屬性之前，最重要的是，確定哪個節點觸發了驅動。如果一個驅動對應多個節點，那驅動可以通過int of_device_is_compatible(const struct device_node *device, const char *name)來判斷當前節點是否包含指定的compatible（相容性）

gpio的設定與獲取

/*imx6dl.dtsi中gpio1控制器的定義節點*/
gpio1: [email protected]0209c000 {
    compatible = "fsl,imx6q-gpio", "fsl,imx35-gpio";
    reg = <0x0209c000 0x4000>;
    interrupts = <0 66 IRQ_TYPE_LEVEL_HIGH>,
             <0 67 IRQ_TYPE_LEVEL_HIGH>;
    gpio-controller;
    #gpio-cells = <2>;
    interrupt-controller;
    #interrupt-cells = <2>;
};

/*imx6qdl-sabreauto.dtsi中某個裝置節點*/
max7310_reset: max7310-reset {
    compatible = "gpio-reset";
    reset-gpios = <&gpio1 15 1>;
    reset-delay-us = <1>;
    #reset-cells = <0>;
};

• 該裝置節點中設定了reset-gpios = <&gpio1 15 1>;這格式是什麼意思呢？&gpio1 15引用了gpio1節點，故此處含義為gpio1_15這個引腳；最後一個引數1則代表低電平有效，0則為高電平有效。至於gpio1_15具體對應哪個引腳，在imx6的手冊上都有詳細描述
• 其實最後一個引數（高低電平有效）不是必須的，因為gpio1節點中設定了#gpio-cells = <2>;，所以才有兩個引數；某些soc的gpio節點中會設定為#gpio-cells = <1>;，那麼可以不寫最後一個引數
• 驅動一般通過以下介面獲取上面節點中gpio的屬性。該函式第一個引數是節點，一般可以在傳入probe的引數中間接獲得；第二個引數是gpio屬性的名字，一定要和節點屬性中的xxx-gpios相同；最後一個是編號index，當節點中有n個同名的xxx-gpios時，可以通過它來獲取特定的那個gpio，同一節點中gpio同名情況很少存在，所以我們都把index設為0

gpio = of_get_named_gpio(node, "reset-gpios", index);

• 在dts和驅動都不關心gpio名字的情況下，也可直接通過以下介面來獲取gpio號，這個時候編號index就十分重要了，可以指定拿取節點的第index個gpio屬性

gpio = of_get_gpio(node, index);

中斷的設定與獲取

假設某裝置節點需要一個gpio中斷

/*先確定中斷所在的組*/
interrupt-parent = <&gpio6>;

/*表示中斷，GPIO6中的第８個IO，2為觸發型別，下降沿觸發*/
interrupts = <8 2>;

• 而在驅動中使用 中斷號 =irq_of_parse_and_map(node, index)函式返回值來得到中斷號

自定義屬性的設定與獲取

所謂的自定義屬性，有點類似於老核心中的platform_data，我們在裝置節點中可以隨意新增自定義屬性，比如下面這個節點裡面的屬性都是我們自己定義的

reg_3p3v: 3p3v {
    compatible = "regulator-fixed";
    regulator-name = "3P3V";
    regulator-min-microvolt = <3300000>;
    regulator-max-microvolt = <3300000>;
    regulator-always-on;
};

• 針對32位整形的屬性，比如上面的regulator-min-microvolt，可以利用下面這個API來獲取屬性值，第一個引數是節點，第二個引數是屬性名字，第三個是輸出型引數（把讀出來的值放進去）

of_property_read_u32(node, "regulator-min-microvolt", &microvolt);

• 類似的讀取數值的API還有：

int of_property_read_u8(const struct device_node *np, const char *propname, u8 *out_value)

int of_property_read_u16(const struct device_node *np, const char *propname, u16 *out_value)

• 下列API可檢查節點中某個屬性是否存在，存在則返回true，不存在則返回false

bool of_property_read_bool(const struct device_node *np, const char *propname)

• 當節點中存在字串時，可以像下面那樣讀取，比如我們讀取前面reg_3p3v節點中的字串

of_property_read_string(node, "regulator-name", &string)

• 當節點中存在陣列時，可以像下面那樣讀取

/*帶有陣列的某個節點*/
L2: cache-controller@1e00a000 {
    compatible = "arm,pl310-cache";
    arm,data-latency = <1 1 1>;
    arm,tag-latency = <1 1 1>;
};

/*驅動中使用API來讀取陣列， &data為輸出型引數*/
of_property_read_u32_array(node, "arm,pl310-cache", &data, ARRAY_SIZE(data));