Linux設備驅動之devicetree_ZenDei技術網路在線

Devicetree（設備樹）是用來描述系統硬體信息的樹模型，其旨在unify內核。通過bootloader將devicetree的信息傳給kernel，然後kernel根據這些設備描述初始化相應的板級驅動，達到一個內核多個平臺共用的目的。 ...

Devicetree（設備樹）是用來描述系統硬體信息的樹模型，其旨在unify內核。通過bootloader將devicetree的信息傳給kernel，然後kernel根據這些設備描述初始化相應的板級驅動，達到一個內核多個平臺共用的目的。

Overview

Devicetree主要為描述不可插拔（非動態）設備的板級硬體信息而設計的。它由分層的描述設備信息的節點（node）組成樹結構。每個node包含的內容通過property/value對來表示。除root節點外，每個節點都有parent。如圖所示：
simple example

Node Names

除root節點名用'/'表示外，其餘節點都由node-name@unit-address來命名，且同一層級必須是唯一的。

node-name

表示節點名，由1-31個字元組成。如非必須，推薦使用以下通用的node-name: 
cpu、memory、memory-controller、gpio、serial、watchdog、flash、compact-flash、rtc、interrupt-controller、dma-controller、ethernet、ethernet-phy、timer、mdio、spi、i2c、usb、can、keyboard、ide、disk、display、sound、atm、cache-controller、crypto、fdc、isa、mouse、nvram、parallel、pc-card、pci、pcie、sata、scsi、vme。

unit-address

表示這個節點所在的bus類型。它必須和節點中reg屬性的第一個地址一致。如果這個節點沒有reg屬性，則不需“@unit-address”。

Path Names

表示一個節點的完整路徑（full path）。型如：

    /node-name-1/node-name-2/node-name-N

Properties

每個節點包含的主要內容就是這個所描述的設備的屬性信息，由name和value組成：

Property Names

1-31個字元，可包含字母、數字、及‘,’，‘.’，‘_’，‘+’，‘?’，‘#’。

Property Values

Value	Description
empty	屬性值為空，用來表示true-false信息
u32/u64	32/64位大端位元組序的無符號整形，表示時需加`<>`
string,stringlist	null-terminated字元串或其組成的列表

Standard Properties

compatible

Value type: <stringlist>
Description:
    表示相容的設備類型，內核據此選擇合適的驅動程式。由多個字元串組成，從左到由列出這個設備相容的驅動（from most specific to most general）。
    推薦的格式為：“製造商名,具體型號”。
Example:
    compatible = "fsl,mpc8641-uart", "ns16550";
    內核先搜索支持“fsl,mpc8641-uart”的驅動，如未找到，則搜索支持更通用的“ns16550”設備類型的驅動。

model

Value type: <stringlist>
Description:
    表明設備型號。
    推薦的格式為：“製造商名,具體型號”。
Example:
    model = "fsl,MPC8349EMITX";

phandle

Value type: <u32>
Description:
    用一個樹內唯一的數字標識所在的這個節點，其他節點可以直接通過這個數字標識來引用這個節點。
Example:
    pic@10000000 {
        phandle = <1>;
        interrupt-controller;
    };
    interrupt-parent = <1>;

status

Value type: <string>
Description:
    表示設備的可用狀態：
    "okay" -> 設備可用
    "disabled" -> 目前不可用，但以後可能會可用
    "fail" -> 不可用。出現嚴重問題，得修一下
    "fail-sss" -> 不可用。出現嚴重問題，得修一下。sss指明錯誤類型。

#address-cells and #size-cells

Value type: <u32>
Description:
    在擁有子節點的節點中使用，來描述它的位元組點的地址分配問題。即分別表示子節點中使用多少個u32大小的cell來編碼reg屬性中的address域和size域。
    這兩個屬性不會繼承，必須明確指出。如未指出，預設#address-cells=2，#size-cells=1。
Example:
    soc {
        #address-cells = <1>;
        #size-cells = <1>;
        serial {
            reg = <0x4600 0x100>;
        };
    };

reg

Value type: <prop-encoded-array> encoded as an arbitraty number of (address, length) pairs.
Description:
    描述該設備在parent bus定義的地址空間中的地址資源分配。
Example:
    reg = <0x3000 0x20 0xFE00 0x100>;
    a 32-byte block at offset 0x3000 and a 256-byte block at offset 0xFE00。

virtual-reg

Value type: <stringlist>
Description:
    表示映射到reg第一個物理地址對應的effective address。使bootloader能夠提供給內核它所建立的virtual-to-physical mappings。

ranges

Value type: <empty> or <prop-encoded-array> encoded as an arbitrary number of (child-bus-address,parent-bus-address, length) triplets.
Description:
    提供了子地址空間與父地址空間的映射關係，如果值為空則父子地址相等，無需轉換。
Example:
    soc {
        compatible = "simple-bus";
        #address-cells = <1>;
        #size-cells = <1>;
        ranges = <0x0 0xe0000000 0x00100000>;

        serial {
            compatible = "ns16550";
            reg = <0x4600 0x100>;
        };
    };
    將子節點serial的0x0地址映射到父節點soc的0xe0000000，映射長度為0x100000。此時reg的實際物理地址就為0xe0004600。

dma-ranges

Value type: <empty> or <prop-encoded-array> encoded as an arbitrary number of (child-bus-address,parent-bus-address, length) triplets.
Description:
    提供了dma地址的映射方法。

Interrupts

描述中斷的屬性有4個：

interrupt-controller

一個空的屬性用來指示這個節點設備是接收中斷信號的控制器。

#interrupt-cells

這是上面所說中斷控制器中的一個屬性，用來描述需要用多少個cell來描述這個中斷控制器的interrupt specifier(類似#address-cells和#size-cells)。

interrupt-parent

常出現在根節點的一個屬性，它的屬性值是指向interrupt-controller的一個phandle。可從parent繼承。

interrupts

包含interrupt specifiers列表，每一個specifier表示一個中斷輸出信號。

Example

/ {
    interrupt-parent = <&intc>;

    intc: interrupt-controller@10140000 {        
              compatible = "arm,pl190";        
              reg = <0x10140000 0x1000 >;        
              interrupt-controller;        
                #interrupt-cells = <2>;    
    };
    serial@101f0000 {        
        interrupts = < 1 0 >;    
    };
};

Base Device Node Types

所有的設備樹都必須有一個root節點，且root節點下必須包含一個cpus節點和至少一個memory節點。

root node

root節點須包含 #address-cells、#size-cells、model、compatible等屬性。

/cpus node

是cpu子節點的父節點容器。須包含 #address-cells、#size-cells屬性。

/cpus/cpu* node
```
是描述系統cpu的節點。
```

/memory node

描述系統物理記憶體的layout。須包含reg節點。
Example:
假如一個64位系統有如下兩塊物理記憶體：
- RAM: starting address 0x0, length 0x80000000 (2GB)
- RAM: starting address 0x100000000, length 0x100000000 (4GB)
則我們可以有下麵兩種描述方法(#address-cells = <2> and #size-cells =<2>)：
Example #1
    memory@0 {
        reg = <0x000000000 0x00000000 0x00000000 0x80000000
               0x000000001 0x00000000 0x00000001 0x00000000>;
    };
Example #2
    memory@0 {
        reg = <0x000000000 0x00000000 0x00000000 0x80000000>;
    };
    memory@100000000 {
        reg = <0x000000001 0x00000000 0x00000001 0x00000000>;
    };

/chosen node

根節點下的一個子節點，不是描述設備而是描述運行時參數。常用來給內核傳遞bootargs:
chosen {
    bootargs = "root=/dev/nfs rw nfsroot=192.168.1.1 console=ttyS0,115200";
};

/aliases node

由1-31個字母、數字或下劃線組成的設備節點full path的別名。它的值是節點的全路徑，因此最終會被編碼成字元串。
aliases {
    serial0 = "/simple-bus@fe000000/serial@llc500";
}

Device Bindings

更多具體設備具體類別的描述信息：內核源代碼/Documentation/devicetree/bindings。

DTS是描述devicetree的源文本文件，它通過內核中的DTC（Devicetree Compiler）編譯後生成相應平臺可燒寫的二進位DTB。

Devicetree Blob (DTB) Structure

DTB又稱Flattened Devicetree（FDT），在記憶體中的結構如下圖所示：
dtb overview

大端位元組序結構體：

struct fdt_header {
    uint32_t magic; /* contain the value 0xd00dfeed (big-endian) */
    uint32_t totalsize; /* the total size of the devicetree data structure */
    uint32_t off_dt_struct; /* offset in bytes of the structure block */
    uint32_t off_dt_strings; /* offset in bytes of the strings block */
    uint32_t off_mem_rsvmap; /* offset in bytes of the memory reservation block */
    uint32_t version; /* the version of the devicetree data structure */
    uint32_t last_comp_version; /* the lowest version used is backwards compatible */
    uint32_t boot_cpuid_phys; /* the physical ID of the system’s boot CPU */
    uint32_t size_dt_strings; /* the length in bytes of the strings block */
    uint32_t size_dt_struct; /* the length in bytes of the structure block */
};

Memory Reservation Block

Purpose

為系統保留一些特殊用途的memory。這些保留記憶體不會進入記憶體管理系統。

Format

struct fdt_reserve_entry {
    uint64_t address;
    uint64_t size;
};

Structure Block

Devicetree結構體存放的位置。由一行行“token+內容”片段線性組成。

token
每一行內容都由一個32位的整形token起始。token指明瞭其後內容的屬性及格式。共有以下5種token：

token	Description
FDT_BEGIN_NODE (0x00000001)	節點起始，其後內容為節點名
FDT_END_NODE (0x00000002)	節點結束
FDT_PROP (0x00000003)	描述屬性
FDT_NOP (0x00000004)	nothing，devicetree解析器忽略它
FDT_END (0x00000009)	block結束

tree structure
- (optionally) any number of FDT_NOP tokens
- FDT_BEGIN_NODE
  - The node’s name as a null-terminated string
  - [zeroed padding bytes to align to a 4-byte boundary]
- For each property of the node:
  - (optionally) any number of FDT_NOP tokens
  - FDT_PROP token
    - property information
    - [zeroed padding bytes to align to a 4-byte boundary]
- Representations of all child nodes in this format
- (optionally) any number of FDT_NOP tokens
- FDT_END_NODE token

Devicetree Source (DTS) Format

Node and property definitions

    [label:] node-name[@unit-address] {
        [properties definitions]
            [child nodes]
    };

File layout

Version 1 DTS files have the overall layout:

/dts-v1/; /* dts 版本1 */
[memory reservations] /* DTB中記憶體保留表的入口 */
    / {
        [property definitions]
        [child nodes]
    };

References

1. The Devicetree Specification
2. elinux

Linux設備驅動之devicetree