Devicetree（设备树）是用来描述系统硬件信息的树模型，其旨在unify内核。通过bootloader将devicetree的信息传给kernel，然后kernel根据这些设备描述初始化相应的板级驱动，达到一个内核多个平台共享的目的。

---

Overview

Devicetree主要为描述不可插拔（非动态）设备的板级硬件信息而设计的。它由分层的描述设备信息的节点（node）组成树结构。每个node包含的内容通过property/value对来表示。除root节点外，每个节点都有parent。如图所示：

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:  Description: 表示兼容的设备类型，内核据此选择合适的驱动程序。由多个字符串组成，从左到由列出这个设备兼容的驱动（from most specific to most general）。 推荐的格式为：“制造商名,具体型号”。 Example: compatible = "fsl,mpc8641-uart", "ns16550"; 内核先搜索支持“fsl,mpc8641-uart”的驱动，如未找到，则搜索支持更通用的“ns16550”设备类型的驱动。

• model

  Value type:  Description: 表明设备型号。 推荐的格式为：“制造商名,具体型号”。 Example: model = "fsl,MPC8349EMITX";

• phandle

  Value type:  Description: 用一个树内唯一的数字标识所在的这个节点，其他节点可以直接通过这个数字标识来引用这个节点。 Example: pic@10000000 { phandle = <1>; interrupt-controller; }; interrupt-parent = <1>;

• status

  Value type:  Description: 表示设备的可用状态： "okay" -> 设备可用 "disabled" -> 目前不可用，但以后可能会可用 "fail" -> 不可用。出现严重问题，得修一下 "fail-sss" -> 不可用。出现严重问题，得修一下。sss指明错误类型。

• #address-cells and #size-cells

  Value type:  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:  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:  Description: 表示映射到reg第一个物理地址对应的effective address。使bootloader能够提供给内核它所建立的virtual-to-physical mappings。

• ranges

  Value type:  or  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:  or  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），在内存中的结构如下图所示：

Header

大端字节序结构体：

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] };