• 设备树手册

# 1. 目的和范围

To initialize and boot a computer system, various software components interact. Firmware might perform low-level initialization of the system hardware before passing control to software such as an operating system, bootloader, or hypervisor. Bootloaders and hypervisors can, in turn, load and transfer control to operating systems. Standard, consistent interfaces and conventions facilitate the interactions between these software components. In this document the term boot program is used to generically refer to a software component that initializes the system state and executes another software component referred to as a client program. Examples of a boot program include: firmware, bootloaders, and hypervisors. Examples of a client program include: bootloaders, hypervisors, operating systems, and special purpose programs. A piece of software may be both a client program and a boot program (e.g. a hypervisor).

This specification, the Devicetree Specification (DTSpec), provides a complete boot program to client program interface definition, combined with minimum system requirements that facilitate the development of a wide variety of systems. This specification is targeted towards the requirements of embedded systems. An embedded system typically consists of system hardware, an operating system, and application software that are custom designed to perform a fixed, specific set of tasks. This is unlike general purpose computers, which are designed to be customized by a user with a variety of software and I/O devices. Other characteristics of embedded systems may include:

• a fixed set of I/O devices, possibly highly customized for the application

一套固定的I/O设备，可能为应用高度定制

• a system board optimized for size and cost

针对尺寸和成本优化的系统板

• limited user interface

有限的用户接口

• resource constraints like limited memory and limited nonvolatile storage

资源限制，如有限的内存和有限的非易失性存储

• real-time constraints

实时限制

• use of a wide variety of operating systems, including Linux, real-time operating systems, and custom or proprietary operating systems

使用各种各样的操作系统，包括Linux、实时操作系统和自定义或专有操作系统

• 第1章介绍了DTSpec所指定的架构。
• 第2章介绍了设备树的概念，并描述了其逻辑结构和标准属性。
• 第3章规定了符合DTSpec的devicetrees所要求的设备节点的基本集合的定义。
• 第4章描述了某些类别的设备和特定设备类型的设备绑定。
• 第5章规定了devicetrees的DTB编码。
• 第6章规定了DTS源语言。

## 1.4 术语的定义

### AMP

Asymmetric Multiprocessing. Computer available CPUs are partitioned into groups, each running a distinct operating system image. The CPUs may or may not be identical.

### boot CPU

The first CPU which a boot program directs to a client program’s entry point.

boot程序进入到客户程序入口点的第一个CPU

### Book III-E

Embedded Environment. Section of the Power ISA defining supervisor instructions and related facilities used in embedded Power processor implementations.

### boot program

Used to generically refer to a software component that initializes the system state and executes another software component referred to as a client program. Examples of a boot program include: firmware, bootloaders, and hypervisors.

### client program

Program that typically contains application or operating system software. Examples of a client program include: bootloaders, hypervisors, operating systems, and special purpose programs.

### cell

A unit of information consisting of 32 bits.

### DTB

Devicetree blob. Compact binary representation of the devicetree

Devicetree blob。设备树的紧凑二进制表示

Memory address as computed by processor storage access or branch instruction.

Address used by the processor to access external device, typically a memory controller.

### Power ISA

Power Instruction Set Architecture.

Power 指令集体系结构

### interrupt specifier(说明符)

A property value that describes an interrupt. Typically information that specifies an interrupt number and sensitivity and triggering mechanism is included.

### secondary CPU

CPUs other than the boot CPU that belong to the client program are considered secondary CPUs.

### SMP

Symmetric multiprocessing. A computer architecture where two or more identical CPUs can share memory and IO and operate under a single operating system.

### SoC

System on a chip. A single computer chip integrating one or more CPU core as well as number of other peripherals

The part of a node name specifying the node’s address in the address space of the parent node.

### quiescent CPU

A quiescent CPU is in a state where it cannot interfere with the normal operation of other CPUs, nor can its state be affected by the normal operation of other running CPUs, except by an explicit method for enabling or re-enabling the quiescent CPU.

# 2. The Devicetree

## 2.1. Overview

DTSpec specifies a construct called a devicetree to describe system hardware. A boot program loads a devicetree into a client program’s memory and passes a pointer to the devicetree to the client.

DTSpec 指定了一个称为设备树的结构来描述系统硬件。引导程序将设备树加载到客户机程序的内存中，并将指向设备树的指针传递给客户机。

This chapter describes the logical structure of the devicetree and specifies a base set of properties for use in describing device nodes. Chapter 3 specifies certain device nodes required by a DTSpec-compliant devicetree. Chapter 4 describes the DTSpec-defined device bindings – the requirements for representing certain device types or classes of devices. Chapter 5 describes the in-memory encoding of the devicetree.

A devicetree is a tree data structure with nodes that describe the devices in a system. Each node has property/value pairs that describe the characteristics of the device being represented. Each node has exactly one parent except for the root node, which has no parent.

A DTSpec-compliant devicetree describes device information in a system that cannot necessarily be dynamically detected by a client program. For example, the architecture of PCI enables a client to probe and detect attached devices, and thus devicetree nodes describing PCI devices might not be required. However, a device node is required to describe a PCI host bridge device in the system if it cannot be detected by probing.

Example

Fig. 2.1 shows an example representation of a simple devicetree that is nearly complete enough to boot a simple operating system, with the platform type, CPU, memory and a single UART described. Device nodes are shown with properties and values inside each node.

## 2.2 Devicetree Structure and Conventions

### 2.2.1 Node Names

node-name@unit-address


The unit-address component of the name is specific to the bus type on which the node sits. It consists of one or more ASCII characters from the set of characters in Table 2.1. The unit-address must match the first address specified in the reg property of the node. If the node has no reg property, the @unit-address must be omitted and the node-name alone differentiates the node from other nodes at the same level in the tree. The binding for a particular bus may specify additional, more specific requirements for the format of reg and the unit-address.

The root node does not have a node-name or unit-address. It is identified by a forward slash (/).

• The nodes with the name cpu are distinguished by their unit-address values of 0 and 1

名称为cpu的节点通过它们的单位地址值0和1来区分

• The nodes with the name ethernet are distinguished by their unit-address values of fe002000 and fe003000.

名称为ethernet的节点通过其单位地址值fe002000和fe003000来区分。

### 2.2.2 通用名称的建议

The name of a node should be somewhat generic, reflecting the function of the device and not its precise programming model. If appropriate, the name should be one of the following choices:

### 2.2.3 路径名称

• 设备树中的一个节点可以通过指定从根节点到所有子节点再到所需节点的完整路径来唯一地识别，指定设备路径的惯例是
/node-name-1/node-name-2/node-name-N


CPU #1的设备路径是

/cpus/cpu@1


### 2.2.4 属性

fsl,channel-fifo-len
ibm,ppc-interrupt-server#s
linux,network-index


#### 属性值

• 一个属性值是一个由零个或多个字节组成的数组，包含与属性相关的信息
• 如果传达的是真-假信息，属性可能会有一个空值

<empty> 值为空。当存在或不存在时，用于传达真-假信息
<u32> 一个32位的整数，以big-endian格式。例如:32位的值0x11223344在内存中表示为：
<u64> 代表一个64位的big-endian格式的整数。由两个值组成，其中第一个值包含整数的最高有效位，第2个值为最低有效位
<string> 字符串是可打印的，并且是空尾的。例如:字符串 “hello “将被代表为：
<prop-encoded-array> 格式是特定于该属性的。请参阅属性定义
<phandle> 一个值。phandle值是一种引用devicetree中另一个节点的方式。任何可以被引 用的节点都定义了一个具有唯一值的phandle属性。这个数字被用于具有 phandle值类型的属性的值
<stringlist> 一个串联起来的值的列表，字符串列表："hello", "wolrd" 在内存中表示为：
... ...
... ...

## 2.3 标准属性

DTSpec为设备节点指定了一组标准属性，由DTSpec定义的设备节点(见第3章)可以指定有关使用标准属性的额外要求或约束。第4章描述了特定设备的表示方法

### 2.3.1 compatible

• 属性名：兼容(可共用)
• 值类型：<stringlist>
• 说明
• The compatible property value consists of one or more strings that define the specific programming model for the device. This list of strings should be used by a client program for device driver selection. The property value consists of a concatenated list of null terminated strings, from most specific to most general. They allow a device to express its compatibility with a family of similar devices, potentially allowing a single device driver to match against several devices

compatible属性值由一个或多个字符串组成，定义设备的特定编程模型。客户端程序应该使用这个字符串列表来选择设备驱动程序。属性值由一个以空结尾的字符串串接列表组成，从最特定的字符串到最通用的字符串。它们允许一个设备表达其与一系列类似设备的兼容性，潜在地允许一个设备驱动程序匹配多个设备

• 推荐的格式是 “制造商，产品型号”，其中制造商是一个描述制造商名称的字符串(如股票代码)，而model则指定产品型号。
• 兼容的字符串应仅由小写字母、数字和破折号组成，并应以字母开头。通常只在供应商前缀之后使用单个逗号。不应使用下划线。
• 举例：

compatible = "fsl,mpc8641", "ns16550";


在这个例子中，操作系统首先会尝试找到一个支持fsl,mpc8641的设备驱动程序。如果没有找到驱动程序 ，它就会试图找到一个支持更普遍的ns16550设备类型的驱动程序。

### 2.3.2 model

• 属性：model
• 类型：<string>
• 说明
• The model property value is a <string> that specifies the manufacturer’s model number of the device.

model属性值是一个<字符串>，它指定设备的产品型号。

• The recommended format is: “manufacturer,model”, where manufacturer is a string describing the name of the manufacturer (such as a stock ticker symbol), and model specifies the model number.

推荐的格式是:”制造商，产品型号”，其中制造商是一个描述制造商名称的字符串(如股票代码)， 而model则指定产品型号。

• 举例
• model = “fsl,MPC8349EMITX”;

### 2.3.3 phandle

• 值类型: <u32>
• 说明
• phandle属性为一个节点指定了一个数字标识符，该标识符在devicetree内是唯一的
• phandle属性值由需要引用与该属性关联的节点的其他节点使用
• 例子

pic@10000000 {
phandle = <1>;
interrupt-contorller;
reg = <0x10000000 0x100>;
};


phandle值被定义为1。另一个设备节点可以通过pandle引用pic节点:

another-device-node {
interrupt-parent = <1>;
};


注意：旧版本的设备树可能会包含这个属性的废弃形式，称为linux,phandle。为了兼容，如果没有phandle属性，客户程序可能希望支持linux,phandle。这两个属性的含义和用法是相同的 DTS中的大多数设备树(见附录A)将不包含明确的phandle属性。当DTS被编译成二进制DTB格式时，DTC 工具会自动插入phandle属性

### 2.3.4 状态

• 值类型：<string>
• 说明：
• 状态属性指示了设备的运行状态。缺少状态属性应被视为该属性存在，其值为 “okay”

“okay” 表明设备正在运行。
“disabled” 设备目前还没有运行，但将来可能会运行(例如，某些东西没有插上电源，或关闭了电源)。关于禁用对一个特定设备的含义，请参考设备绑定的细节
“reserved” 设备可以运行，但不应该被使用。一般来说，这用于设备是由另一个软件组件控制的，如平台固件
“fail” 表示设备无法运行。在设备中检测到一个严重的错误，并且不太可能 在没有修理的情况下成为可操作的。
“fail-sss” 表明设备无法运行。在设备中检测到一个严重的错误，不太可能 以使其无需修理即可运行。该值的sss部分是针对设备的，表示检测到的错误情况。

• 数值类型:<u32>
• 理解
• reg属性中的地址占u32数量
• reg属性中的长度占u32数量
• 说明
• #address-cells#size-cells属性可用于任何在devicetree层次结构中拥有子节点的设备节点，并描述应如何对子设备节点进行寻址
• #address-cells属性定义了用于编码子节点的reg属性中的地址字段的<u32>单元的数量
• #size-cells属性定义了用于编码子节点的reg属性中的大小字段的<u32>单元格的数量
• #address-cell#size-cells属性不从devicetree中的祖先那里继承。它们应被明确定义
• 一个符合DTSpec的boot引导程序应在所有有子节点上提供#address-cell#size-cells
• 如果缺失，客户程序应假定#address-cell的默认值为2，#size-cells的默认值为1
• 举例

soc {
#size-cells = <1>;   // 长度占1个u32

serial@4600 {
compatible = "ns16550";
reg = <0x4600 0x100>;
clock-frequency: <0>;
interrupts = <0xA 0x8>;
interrupt-parent = <&ipic>;
};
};

• 串行设备reg属性必须遵循父节点(soc)中设置的规范—地址由单个单元(0x4600)表示，大小由单个单元(0x100)表示

### 2.3.6 reg

• 属性类型：<prop-encoded-array>编码为任意数量的(地址，长度)对
• 说明：
• The reg property describes the address of the device’s resources within the address space defined by its parent bus. Most commonly this means the offsets and lengths of memory-mapped IO register blocks, but may have a different meaning on some bus types. Addresses in the address space defined by the root node are CPU real addresses

• reg 属性描述了设备的资源的地址，这个地址是在其父总线所定义的地址空间内的地址。
• 最常见的是这意味着内存映射的IO寄存器块的偏移量和长度，但在某些总线类型上可能有不同的含义。
• 根节点定义的地址空间中的地址是CPU的真实地址
• 该值是一个<prop-encoded-array>，由任意数量的地址和长度对组成，<address length>

• 指定地址和长度所需的<u32>单元的数量是特定于总线的，由设备节点的父节点中的#address-cells#size-cells属性指定。
• 如果父节点为#size-cells指定的值是0，那么reg值中的长度字段应被省略。
• 例子

reg = <0x3000 0x20 0xFE00 0x100>


### 2.3.7 virtual-reg

• 类型：<u32>
• 说明
• The virtual-reg property specifies an effective address that maps to the first physical address specified in the reg property of the device node. This property enables boot programs to provide client programs with virtual-to-physical mappings that have been set up.
• 指定了一个有效地址，该地址映射到设备节点的 reg 属性中指定的第一个物理地址。
• 这个属性使boot引导程序能够向客户程序提供已经设置好的虚拟到物理的映射关系

### 2.3.8 ranges

• 类型：<empty><prop-encoded-array>编码为任意数量的(子总线地址，父总线地址，长度)三要素
• 说明
• range 属性提供了一种方法来定义总线的地址空间(子地址空间)和总线节点的父地址空间(父地址空间)之间的映射或转换。
• 范围属性的值的格式是一个任意数量的(子总线地址，父总线地址，长度)的三联体。
• 子总线地址是子总线地址空间内的一个物理地址。表示该地址的单元格的数量与总线有关，可以从该节点(范围属性出现的节点)的#address-cell中确定
• 父总线地址是父总线地址空间内的一个物理地址。表示父级地址的单元格数量与总线有关，可以从定义父级地址空间的节点的#address-cell属性中确定
• 长度指定了子代地址空间中的范围的大小。表示大小的单元格的数量可以从这个节点(range属性出现的节点)的#size-cells中确定
• 如果该属性被定义为<empty>值，它指定了父代和子代地址空间是相同的，不需要进行地址转换。
• 如果该属性在总线节点中不存在，则假定该节点的子节点和父地址空间之间不存在映射。
• 例子

soc {
compatible = "simple-bus";
#size-cells = <1>;
// 所有子结点的基地址为0xe000_0000
ranges = <0x0 0xe0000000 0x00100000>;

seiral@4600 {
device-type = "serial";
compatible = "ns16550";
reg = <0x4600 0x100>;
clock-frequency = <0>;
interrupts = <0xA 0x8>;
interrupt-parent = <&ipic>;
};
};

• soc节点指定了一个范围属性为

<0x0 0xe0000000 0x00100000>

• 这个属性值规定，对于1024KB的地址空间范围，一个在物理0x0处寻址的子节点映射到物理0xe0000000的父地址。
• 有了这个映射，串行设备节点可以通过在地址0xe0004600、0x4600的偏移量(在resge中ri指al定@)4加60上0范围中指定的0xe0000000映射来进行加载或存储

### 2.3.9 dma-ranges

• 类型: <empty><prop-encoded-array>编码为任意数量的(子总线地址，父总线地址，长度)三要素：
• 说明
• dma-ranges属性用于描述内存映射总线的直接内存访问(DMA)结构，该总线的devicetree父节点可被源自该总线的DMA操作访问。
• 它提供了一种方法来定义总线的物理地址空间和总线的父代的物理地址空间之间的映射或转换。
• 长度指定了子代地址空间中范围的大小。表示大小的单元格的数量可以从这个节点(dma-ranges属性 出现的节点)的#size-cells中确定。

### dma-coherent

• 类型：<empty>
• 说明
• 对于I/O默认为非相干的架构，dma-coherent属性用于指示设备能够进行相干的DMA操作。有些架构默认有相干的 DMA，这个属性就不适用

### 2.3.10 name(弃用)

• 值类型: <string>
• 说明
• name属性是一个字符串，指定了节点的名称。这个属性已被废弃，不建议使用。
• 然而，它可能被用于旧的不符合DTSpec的设备树。操作系统应该根据节点名称的node-name组件来确定节点的名称

### 2.3.11 device_type(弃用)

• 值类型：<string>
• 说明
• 设备类型属性在IEEE 1275中被用来描述设备的FCode编程模型。
• 由于DTSpec没有FCode，该属性的新用途已被废弃，它应该只包含在cpu和内存节点上，以便与IEEE 1275衍生的devicetrees兼容

## 2.4 中断与中断映射

DTSpec adopts the interrupt tree model of representing interrupts specified in Open Firmware Recommended Practice: Interrupt Mapping, Version 0.9 b7. Within the devicetree a logical interrupt tree exists that represents the hierarchy and routing of interrupts in the platform hardware. While generically referred to as an interrupt tree it is more technically a directed acyclic graph.

DTSpec 采用中断树模型来表示 Open Firmware Recommended Practice: Interrupt Mapping，Version 0.9[b7] 中指定的中断。在设备树中存在一个逻辑中断树，它表示平台硬件中中断的层次结构和路由。虽然通常被称为中断树，但从技术上讲，它更像是一个有向无环图。

The physical wiring of an interrupt source to an interrupt controller is represented in the devicetree with the interrupt-parent property. Nodes that represent interrupt-generating devices contain an interrupt-parent property which has a phandle value that points to the device to which the device’s interrupts are routed, typically an interrupt controller. If an interrupt-generating device does not have an interrupt-parent property, its interrupt parent is assumed to be its devicetree parent.

Each interrupt generating device contains an interrupts property with a value describing one or more interrupt sources for that device. Each source is represented with information called an interrupt specifier. The format and meaning of an interrupt specifier is interrupt domain specific, i.e., it is dependent on properties on the node at the root of its interrupt domain. The #interrupt-cells property is used by the root of an interrupt domain to define the number of <u32> values needed to encode an interrupt specifier. For example, for an Open PIC interrupt controller, an interrupt-specifer takes two 32-bit values and consists of an interrupt number and level/sense information for the interrupt.

An interrupt domain is the context in which an interrupt specifier is interpreted. The root of the domain is either (1) an interrupt controller or (2) an interrupt nexus.

1. An interrupt controller is a physical device and will need a driver to handle interrupts routed through it. It may also cascade into another interrupt domain. An interrupt controller is specified by the presence of an interrupt-controller property on that node in the devicetree.

中断控制器是一个物理设备，需要一个驱动程序来处理通过它路由的中断。它也可能级联到另一个中断域。中断控制器由设备树中该节点上的 interrupt-controller 中断控制器属性指定。

2. An interrupt nexus defines a translation between one interrupt domain and another. The translation is based on both domain-specific and bus-specific information. This translation between domains is performed with the interrupt-map property. For example, a PCI controller device node could be an interrupt nexus that defines a translation from the PCI interrupt namespace (INTA, INTB, etc.) to an interrupt controller with Interrupt Request (IRQ) numbers.

interrupt nexus 中断枢纽定义了一个中断域和另一个中断域之间的转换。转换基于领域特定和总线特定的信息。域之间的转换是使用 interrupt-map 中断映射属性执行的。例如，PCI 控制器设备节点可以是一个中断枢纽，它定义了从 PCI 中断命名空间(INTA、 INTB 等)到带有中断请求(IRQ)号码的中断控制器的转换。

The root of the interrupt tree is determined when traversal of the interrupt tree reaches an interrupt controller node without an interrupts property and thus no explicit interrupt parent.

See Fig. 2.3 for an example of a graphical representation of a devicetree with interrupt parent relationships shown. It shows both the natural structure of the devicetree as well as where each node sits in the logical interrupt tree.

• The open-pic interrupt controller is the root of the interrupt tree.

Open-pic 中断控制器是中断树的根

• The interrupt tree root has three children—devices that route their interrupts directly to the

中断树根有三个子设备，它们将中断直接路由到open-pic

• device1 设备
• PCI host controller PCI 主机控制器
• GPIO Controller GPIO 控制器
• Three interrupt domains exist; one rooted at the open-pic node, one at the PCI host bridge node, and one at the GPIO Controller node.

有三个中断域; 一个位于 open-pic 节点，一个位于 PCI 主机桥节点，还有一个位于 GPIO Controller 节点。

• There are two nexus nodes; one at the PCI host bridge and one at the GPIO controller.

有两个枢纽节点，一个在 PCI 主机桥接器上，一个在 GPIO 控制器上。

### 2.4.1. Properties for Interrupt Generating Devices 中断生成设备的属性

#### 2.4.1.1. interrupts 产生的中断

• Property: interrupts
• Value type: <prop-encoded-array> encoded as arbitrary number of interrupt specifiers

值类型: <prop-encoded-array> 编码为任意数目的中断指示符

• 描述:

• The interrupts property of a device node defines the interrupt or interrupts that are generated by the device. The value of the interrupts property consists of an arbitrary number of interrupt specifiers. The format of an interrupt specifier is defined by the binding of the interrupt domain root.

设备节点的interrupts属性定义了由设备产生的一个或多个中断。interrupts属性的值由任意数量的中断指定符组成。中断指定符的格式由中断域根的绑定来定义。

• interrupts is overridden by the interrupts-extended property and normally only one or the other should be used.

中断被 interrupts-extended 属性重写，通常只能使用其中一个

• 例子:

• A common definition of an interrupt specifier in an open PIC–compatible interrupt domain consists of two cells; an interrupt number and level/sense information. See the following example, which defines a single interrupt specifier, with an interrupt number of 0xA and level/sense encoding of 8.

在一个开放的PIC兼容的中断域中，一个常见的中断指定符的定义包括两个单元；一个中断号和电平/感应信息。请看下面的例子，它定义了一个单一的中断指定符，中断号为0xA，级别/感应编码为8。

  interrupts = <0xA 8>;


#### 2.4.1.2. interrupt-parent 中断-父

• Property: interrupt-parent

属性: interrupt-parent

• 值类型: <phandle>
• 描述:

• Because the hierarchy of the nodes in the interrupt tree might not match the devicetree, the interrupt-parent property is available to make the definition of an interrupt parent explicit. The value is the phandle to the interrupt parent. If this property is missing from a device, its interrupt parent is assumed to be its devicetree parent.

因为中断树中节点的层次结构可能与设备树不一致，所以interrupt-parent属性可用来明确定义中断父节点。其值是指向中断父节点的句柄。如果一个设备缺少这个属性，它的中断父节点就被认为是它的设备树父节点。

#### 2.4.1.3. interrupts-extended

• Property: interrupts-extended
• 值类型: <phandle> <prop-encoded-array>
• 描述:

• The interrupts-extended property lists the interrupt(s) generated by a device. interrupts-extended should be used instead of interrupts when a device is connected to multiple interrupt controllers as it encodes a parent phandle with each interrupt specifier.

interrupts-extended属性列出了一个设备产生的中断（s）。当一个设备连接到多个中断控制器时，应使用interrupts-extended而不是interrupts，因为它为每个中断指定符编码了一个父句柄。

• 例子:

• This example shows how a device with two interrupt outputs connected to two separate interrupt controllers would describe the connection using an interrupts-extended property. pic is an interrupt controller with an #interrupt-cells specifier of 2, while gic is an interrupt controller with an #interrupts-cells specifier of 1.

这个例子显示了一个有两个中断输出的设备，连接到两个独立的中断控制器，如何使用interrupts-extended属性描述连接。pic是一个中断控制器，#interrupt-cells 规格为2，而gic’是一个中断控制器，#interrupts-cell规格为1。

  interrupts-extended = <&pic 0xA 8>, <&gic 0xda>;


The interrupts and interrupts-extended properties are mutually exclusive. A device node should use one or the other, but not both. Using both is only permissible when required for compatibility with software that does not understand interrupts-extended. If both interrupts-extended and interrupts are present then interrupts-extended takes precedence.

interruptsinterrupts-extended属性是相互排斥的。一个设备节点应该使用其中之一，但不能同时使用。只有在需要与“不能解析 interrupts-extended 的软件”相兼容时，才允许同时使用。如果interrupts-extendedinterrupts都存在，那么interrupts-extended优先使用。

### 2.4.2. Properties for Interrupt Controllers 中断控制器属性

#### 2.4.2.1. #interrupt-cells

• Property: #interrupt-cells
• Value type: <u32>
• Description:

• The #interrupt-cells property defines the number of cells required to encode an interrupt specifier for an interrupt domain.

#interrupt-cells属性定义了为一个中断域编码一个中断指定符所需的单元数。

#### 2.4.2.2. interrupt-controller 中断控制器

• Property: interrupt-controller
• Value type: <empty>
• Description:

• The presence of an interrupt-controller property defines a node as an interrupt controller node.

中断控制器属性的存在将节点定义为中断控制器节点

### 2.4.3. Interrupt Nexus Properties 中断枢纽属性

An interrupt nexus node shall have an #interrupt-cells property.

#### 2.4.3.1. interrupt-map 中断映射

• Property: interrupt-map

属性: 中断映射

• Value type: <prop-encoded-array> encoded as an arbitrary number of interrupt mapping entries.

值类型: <prop-encoded-array> 编码为任意数量的中断映射条目

• Description: 描述:

• An interrupt-map is a property on a nexus node that bridges one interrupt domain with a set of parent interrupt domains and specifies how interrupt specifiers in the child domain are mapped to their respective parent domains.

interrupt-map 中断映射是 nexus 节点上的一个属性，它将一个中断域与一组父中断域连接起来，并指定子域中的中断指定符如何映射到它们各自的父域。

• The interrupt map is a table where each row is a mapping entry consisting of five components: child unit address, child interrupt specifier, interrupt-parent, parent unit address, parent interrupt specifier.

中断映射是一个表，其中每一行是一个映射条目，由五个组成部分组成: 子单元地址、子中断指定符、父中断、父中断单元地址、父中断指定符。

The unit address of the child node being mapped. The number of 32-bit cells required to specify this is described by the #address-cells property of the bus node on which the child is located.

• child interrupt specifier 子中断指定符

The interrupt specifier of the child node being mapped. The number of 32-bit cells required to specify this component is described by the #interrupt-cells property of this node—the nexus node containing the interrupt-map property.

被映射的子节点的中断指定符。指定此组件所需的32位单元的数量由此节点的 #interrupt-cells 属性描述，该节点是包含中断映射属性的 nexus 节点。

• interrupt-parent 父中断

A single <phandle> value that points to the interrupt parent to which the child domain is being mapped.

一个单独的 <phandle> 值，指向子域映射到的中断父级。

The unit address in the domain of the interrupt parent. The number of 32-bit cells required to specify this address is described by the #address-cells property of the node pointed to by the interrupt-parent field.

• parent interrupt specifier 父中断指定符

The interrupt specifier in the parent domain. The number of 32-bit cells required to specify this component is described by the #interrupt-cells property of the node pointed to by the interrupt-parent field.

父域中的中断指定符。指定此组件所需的32位单元格数由中断父字段指向的节点的 #interrupt-cells 属性描述。

Lookups are performed on the interrupt mapping table by matching a unit-address/interrupt specifier pair against the child components in the interrupt-map. Because some fields in the unit interrupt specifier may not be relevant, a mask is applied before the lookup is done. This mask is defined in the interrupt-map-mask property (see Section 2.4.3.2).

Both the child node and the interrupt parent node are required to have #address-cells and #interrupt-cells properties defined. If a unit address component is not required, #address-cells shall be explicitly defined to be zero.

• Property: interrupt-map-mask

属性: 中断-映射-掩码

• Value type: <prop-encoded-array> encoded as a bit mask

值类型: <prop-encoded-array> 编码为位掩码

• 描述:

An interrupt-map-mask property is specified for a nexus node in the interrupt tree. This property specifies a mask that is ANDed with the incoming unit interrupt specifier being looked up in the table specified in the interrupt-map property.

为中断树中的节点指定一个中断-映射-掩码属性。该属性指定了一个掩码，该掩码与正在 interrupt-map 属性中指定的表中查找的传入单元中断指定符相加。

#### 2.4.3.3. #interrupt-cells

• Property: #interrupt-cells

属性: #interrupt-cells

• Value type: <u32>

值类型: < u32 >

• 描述:

The #interrupt-cells property defines the number of cells required to encode an interrupt specifier for an interrupt domain.

#interrupt-cells 属性定义为中断域编码中断指定符所需的单元数

### 2.4.4. Interrupt Mapping Example 中断映射示例

The following shows the representation of a fragment of a devicetree with a PCI bus controller and a sample interrupt map for describing the interrupt routing for two PCI slots (IDSEL 0x11,0x12). The INTA, INTB, INTC, and INTD pins for slots 1 and 2 are wired to the Open PIC interrupt controller.

soc {
compatible = "simple-bus";
#size-cells = <1>;

open-pic {
clock-frequency = <0>;
interrupt-controller;
#interrupt-cells = <2>;   // 中断指定符的长度
};

pci {
#interrupt-cells = <1>; // 子中断指定符长度
#size-cells = <2>;
interrupt-map-mask = <0xf800 0 0 7>;
//  子单元地址、子中断指定符、父中断、父中断单元地址、父中断指定符
interrupt-map = <
/* IDSEL 0x11 - PCI slot 1 */
0x8800 0 0 1 &open-pic 2 1 /* INTA */
0x8800 0 0 2 &open-pic 3 1 /* INTB */
0x8800 0 0 3 &open-pic 4 1 /* INTC */
0x8800 0 0 4 &open-pic 1 1 /* INTD */
/* IDSEL 0x12 - PCI slot 2 */
0x9000 0 0 1 &open-pic 3 1 /* INTA */
0x9000 0 0 2 &open-pic 4 1 /* INTB */
0x9000 0 0 3 &open-pic 1 1 /* INTC */
0x9000 0 0 4 &open-pic 2 1 /* INTD */
>;
};
};


One Open PIC interrupt controller is represented and is identified as an interrupt controller with an interrupt-controller property.

Each row in the interrupt-map table consists of five parts: a child unit address and interrupt specifier, which is mapped to an interrupt-parent node with a specified parent unit address and interrupt specifier.

• For example, the first row of the interrupt-map table specifies the mapping for INTA of slot 1. The components of that row are shown here

例如，中断映射表的第一行指定了槽1的 INTA 映射。这里显示了该行的组件

child unit address: 0x8800 0 0: 子单元地址: 0x8800 0 0

child interrupt specifier:1: 子中断指定符: 1

interrupt parent: &open-pic: 父中断: &open-pic

parent unit address: (empty because #address-cells = <0> in the open-pic node): 父单元地址: (空，因为在 open-pic 节点中 #address-cells = <0>)

parent interrupt specifier: 2 1: 父中断指定符: 2 1

• The child unit address is <0x8800 0 0>. This value is encoded with three 32-bit cells, which is determined by the value of the #address-cells property (value of 3) of the PCI controller. The three cells represent the PCI address as described by the binding for the PCI bus.

子单元地址是<0x8800 0 0>。这个值用三个32位的单元进行编码，这是由PCI控制器的#address-cells属性的值（值为3）决定的。这三个单元代表PCI总线的绑定所描述的PCI地址。

• The value <2 1> is a value specified by the device binding for the Open PIC interrupt controller (see section 4.5). The value <2> specifies the physical interrupt source number on the interrupt controller to which INTA is wired. The value <1> specifies the level/sense encoding.

<2 1>是Open PIC中断控制器的设备绑定指定的值(参见4.5节)。<2>表示INTA连线到的中断控制器上的物理中断源号。<1>表示level/sense编码

The encoding includes the bus number (0x0 « 16), device number (0x11 « 11), and function number (0x0 « 8). 编码包括总线号（0x0 « 16），设备号（0x11 « 11），和功能号（0x0 « 8）。

• The child interrupt specifier is <1>, which specifies INTA as described by the PCI binding. This takes one 32-bit cell as specified by the #interrupt-cells property (value of 1) of the PCI controller, which is the child interrupt domain.

子中断指定器是<1>，它指定了PCI绑定所描述的INTA。这需要一个32位的单元，由PCI控制器的 #interrupt-cells 属性（值为1）指定，这是子中断域

• The interrupt parent is specified by a phandle which points to the interrupt parent of the slot, the Open PIC interrupt controller.

中断父 由一个指向插槽的中断父级的 phandle 指定(&open-pic)，即 Open PIC 中断控制器。

• The parent has no unit address because the parent interrupt domain (the open-pic node) has an #address-cells value of <0>.

父节点没有单元地址，因为父中断域(open-pic 节点)的 #address-cells 值为 <0>

• The parent interrupt specifier is <2 1>. The number of cells to represent the interrupt specifier (two cells) is determined by the #interrupt-cells property on the interrupt parent, the open-pic node.

父中断指定符是<2 1>。表示中断指定符的单元格数量（两个单元格）由中断父节点即open-pic节点上的 #interrupt-cell 属性决定

The value <2 1> is a value specified by the device binding for the Open PIC interrupt controller (see Section 4.5). The value <2> specifies the physical interrupt source number on the interrupt controller to which INTA is wired. The value <1> specifies the level/sense encoding.
<2 1> 是由设备绑定为 Open PIC 中断控制器指定的值(参见第4.5节)。值 <2> 指定 INTA 连接到的中断控制器上的物理中断源号。值 <1> 指定级别/感觉编码。

In this example, the interrupt-map-mask property has a value of <0xf800 0 0 7>. This mask is applied to a child unit interrupt specifier before performing a lookup in the interrupt-map table.

To perform a lookup of the open-pic interrupt source number for INTB for IDSEL 0x12 (slot 2), function 0x3, the following steps would be performed:

• The child unit address and interrupt specifier form the value <0x9300 0 0 2>.

子单元地址和中断指定符形成值 <0x9300 0 0 2>

• The encoding of the address includes the bus number (0x0 « 16), device number (0x12 « 11), and function number (0x3 « 8).

地址的编码包括总线号(0x0 « 16)、设备号(0x12 « 11)和功能号(0x3 « 8)。

• The interrupt specifier is 2, which is the encoding for INTB as per the PCI binding.

中断指定符是2，这是根据 PCI 绑定对 INTB 进行的编码

• The interrupt-map-mask value <0xf800 0 0 7> is applied, giving a result of <0x9000 0 0 2>.

应用中断-映射-掩码值 <0xf800 0 0 7> ，得到 <0x9000 0 0 2> 的结果。

• That result is looked up in the interrupt-map table, which maps to the parent interrupt specifier <4 1>.

该结果在中断映射表中查找，该表映射到父中断指定符 <4 1>.

## 2.5. Nexus Nodes and Specifier Mapping

### 2.5.1. Nexus Node Properties

A nexus node shall have a *#-cells* property, where  is some specifier space such as ‘gpio’, ‘clock’, ‘reset’, etc.

#### 2.5.1.1. <specifier>-map

• Property: <specifier>-map

• Value type: <prop-encoded-array> encoded as an arbitrary number of specifier mapping entries.

值类型: · 编码为任意数目的指定符映射条目

• 描述:

• A *-map* is a property in a nexus node that bridges one specifier domain with a set of parent specifier domains and describes how specifiers in the child domain are mapped to their respective parent domains.

一个 *-map* 是一个 nexus 节点中的属性，它将一个说明符域与一组父说明符域连接起来，并描述子域中的说明符如何映射到它们各自的父域。

• The map is a table where each row is a mapping entry consisting of three components: child specifier, specifier parent, and parent specifier.

映射是一个表，其中每一行是一个映射条目，由三个组件组成: 子说明符、说明符父说明符和父说明符。

• child specifier 子说明符

The specifier of the child node being mapped. The number of 32-bit cells required to specify this component is described by the *#-cells* property of this node—the nexus node containing the *-map* property.

被映射的子节点的说明符。指定此组件所需的32位单元的数量由此节点的 *#-cells* 属性描述，该节点是包含 *-map* 属性的 nexus 节点。

• specifier parent 指定符-父

A single ** value that points to the specifier parent to which the child domain is being mapped.

一个单独的 < phandle > 值，指向子域映射到的父指定符。

• parent specifier 父指定符

The specifier in the parent domain. The number of 32-bit cells required to specify this component is described by the *#-cells* property of the specifier parent node.

父域中的说明符。指定此组件所需的32位单元格数由指定父节点的 *#-cells* 属性描述。

Lookups are performed on the mapping table by matching a specifier against the child specifier in the map. Because some fields in the specifier may not be relevant or need to be modified, a mask is applied before the lookup is done. This mask is defined in the *-map-mask* property (see [Section 2.5.1.2](https://devicetree-specification.readthedocs.io/en/latest/chapter2-devicetree-basics.html#sect-specifier-map-mask)).

Similarly, when the specifier is mapped, some fields in the unit specifier may need to be kept unmodified and passed through from the child node to the parent node. In this case, a *-map-pass-thru* property (see [Section 2.5.1.3](https://devicetree-specification.readthedocs.io/en/latest/chapter2-devicetree-basics.html#sect-specifier-map-pass-thru)) may be specified to apply a mask to the child specifier and copy any bits that match to the parent unit specifier.

类似地，当指定符被映射时，单元指定符中的某些字段可能需要保持不变，并从子节点传递到父节点。在这种情况下，可以指定一个 *-map-pass-thru* 属性(参见第2.5.1.3节)为子说明符应用掩码，并复制与父单元说明符匹配的任何位。

#### 2.5.1.2. <specifier>-map-mask

• Property: <specifier>-map-mask

• Value type: <prop-encoded-array> encoded as a bit mask

值类型: < prop-encoded-array > 编码为位掩码

• 描述:

A *-map-mask* property may be specified for a nexus node. This property specifies a mask that is ANDed with the child unit specifier being looked up in the table specified in the *-map* property. If this property is not specified, the mask is assumed to be a mask with all bits set.

可以为枢纽节点指定一个 *-map-mask* 属性。此属性指定一个掩码，该掩码与在 *-map* 属性中指定的表中查找的子单元说明符一起进行 ANDed。如果未指定此属性，则假定掩码是设置了所有位的掩码。

#### 2.5.1.3. <specifier>-map-pass-thru

• Property: <specifier>-map-pass-thru

• Value type: <prop-encoded-array> encoded as a bit mask

值类型: < prop-encoded-array > 编码为位掩码

• Description: 描述:

A *-map-pass-thru* property may be specified for a nexus node. This property specifies a mask that is applied to the child unit specifier being looked up in the table specified in the *-map* property. Any matching bits in the child unit specifier are copied over to the parent specifier. If this property is not specified, the mask is assumed to be a mask with no bits set.

可以为连结节点指定一个 *-map-pass-thru* 属性。此属性指定一个掩码，该掩码应用于在 *-map* 属性中指定的表中查找的子单元说明符。子单元说明符中的任何匹配位都被复制到父说明符中。如果未指定此属性，则假定掩码是未设置位的掩码。

#### 2.5.1.4. #-cells

• Property: #<specifier>-cells
• Value type: <u32>
• Description: 描述:

The *#-cells* property defines the number of cells required to encode a specifier for a domain.

单元格属性定义为域编码说明符所需的单元格数量。

### 2.5.2. Specifier Mapping Example 说明符映射示例

The following shows the representation of a fragment of a devicetree with two GPIO controllers and a sample specifier map for describing the GPIO routing of a few gpios on both of the controllers through a connector on a board to a device. The expansion device node is on one side of the connector node and the SoC with the two GPIO controllers is on the other side of the connector.

soc {
soc_gpio1: gpio-controller1 {
#gpio-cells = <2>;
};

soc_gpio2: gpio-controller2 {
#gpio-cells = <2>;
};
};

connector: connector {
#gpio-cells = <2>;
gpio-map = <0 0 &soc_gpio1 1 0>,
<1 0 &soc_gpio2 4 0>,
<2 0 &soc_gpio1 3 0>,
<3 0 &soc_gpio2 2 0>;
gpio-map-pass-thru = <0x0 0x1>;
};

expansion_device {
reset-gpios = <&connector 2 GPIO_ACTIVE_LOW>;
};


Each row in the gpio-map table consists of three parts: a child unit specifier, which is mapped to a gpio-controller node with a parent specifier.

Gpio-map 表中的每一行由三部分组成: 一个子单元说明符，它通过一个父说明符映射到一个 gpio-controller 节点。

• For example, the first row of the specifier-map table specifies the mapping for GPIO 0 of the connector. The components of that row are shown here

例如，specifier-map 表的第一行指定连接器的 gpio0映射。这里显示了该行的组件

child specifier: 0 0

specifier parent: &soc_gpio1

parent specifier: 1 0

• The child specifier is <0 0>, which specifies GPIO 0 in the connector with a flags field of 0. This takes two 32-bit cells as specified by the #gpio-cells property of the connector node, which is the child specifier domain.

• 子说明符是 <0 0> ，它指定连接器中的 GPIO 0，其标志字段为0。这需要两个32位单元格，由连接器节点(即子说明符域)的 #gpio-cells 属性指定。

• The specifier parent is specified by a phandle which points to the specifier parent of the connector, the first GPIO controller in the SoC.

• 父指定符由 phandle 指定，phandle 指向连接器的父指定符，即 SoC 中的第一个 GPIO 控制器。

• The parent specifier is <1 0>. The number of cells to represent the gpio specifier (two cells) is determined by the #gpio-cells property on the specifier parent, the soc_gpio1 node.

父指定符是<1 0>。表示gpio指示符的单元格数量(两个单元格)由指示符父节点soc gpio1节点上的#gpio-cells属性决定。

• The value <1 0> is a value specified by the device binding for the GPIO controller. The value <1> specifies the GPIO pin number on the GPIO controller to which GPIO 0 on the connector is wired. The value <0> specifies the flags (active low, active high, etc.).

值 < 1 0 > 是由 GPIO 控制器的设备绑定指定的值。值 < 1 > 指定连接器上的 GPIO 0连接到的 GPIO 控制器上的 GPIO 引脚号。值 < 0 > 指定标志(active low、 active high 等)。

In this example, the gpio-map-mask property has a value of <0xf 0>. This mask is applied to a child unit specifier before performing a lookup in the gpio-map table. Similarly, the gpio-map-pass-thru property has a value of <0x0 0x1>. This mask is applied to a child unit specifier when mapping it to the parent unit specifier. Any bits set in this mask are cleared out of the parent unit specifier and copied over from the child unit specifier to the parent unit specifier.

To perform a lookup of the connector’s specifier source number for GPIO 2 from the expansion device’s reset-gpios property, the following steps would be performed:

• The child specifier forms the value <2 GPIO_ACTIVE_LOW>

子指示符形成了值<2 GPIO_ACTIVE_LOW>

• The specifier is encoding GPIO 2 with active low flags per the GPIO binding.

说明符对 GPIO 2进行编码，每个 GPIO 绑定使用活动的低标志。

• The gpio-map-mask value <0xf 0x0> is ANDed with the child specifier, giving a result of <0x2 0>.

Gpio-map-mask 值 < 0xf 0x0 > 与子说明符一起进行分析，得到的结果是 < 0x2 0 > 。

• The result is looked up in the gpio-map table, which maps to the parent specifier <3 0> and &soc_gpio1 phandle.

• 结果在 gpio-map 表中查找，该表映射到父指定符 < 3 0 > 和 & soc_gpio1 phandle。

• The gpio-map-pass-thru value <0x0 0x1> is inverted and ANDed with the parent specifier found in the gpio-map table, resulting in <3 0>. The child specifier is ANDed with the gpio-map-pass-thru mask, forming <0 GPIO_ACTIVE_LOW> which is then ORed with the cleared parent specifier <3 0> resulting in <3 GPIO_ACTIVE_LOW>.

Gpio-map-pass-thru 值 < 0x0 0x1 > 被反转并与 gpio-map 表中的父指定符分开，从而得到 < 3 0 > 。子指定符用 GPIO-map-pass-thru 掩码进行分析，形成 < 0 GPIO_active_low > ，然后与清除的父指定符 < 3 0 > 连接，形成 < 3 GPIO_active_low > 。

• The specifier <3 GPIO_ACTIVE_LOW> is appended to the mapped phandle &soc_gpio1 resulting in <&soc_gpio1 3 GPIO_ACTIVE_LOW>.

• 说明符 < 3 gpio_active_low > 附加在映射的 phandle &soc_gpio1 后，生成 < &soc_gpio1 3 gpio_active_low > 。

# 3. Device Node Requirements 设备节点需求

## 3.1. Base Device Node Types 基本设备节点类型

The sections that follow specify the requirements for the base set of device nodes required in a DTSpec-compliant devicetree.

All devicetrees shall have a root node and the following nodes shall be present at the root of all devicetrees:

• One /cpus node 一个 /cpu 节点
• At least one /memory node 至少有一个/memory节点

## 3.2. Root node 根节点

The devicetree has a single root node of which all other device nodes are descendants. The full path to the root node is /.

Property Name Usage Value Type Definition
#address-cells R <u32> Specifies the number of <u32> cells to represent the address in the reg property in children of root.

#size-cells R <u32> Specifies the number of <u32> cells to represent the size in the reg property in children of root.

model R <string> Specifies a string that uniquely identifies the model of the system board. The recommended format is “manufacturer,model-number”.

compatible R <stringlist> Specifies a list of platform architectures with which this platform is compatible. This property can be used by operating systems in selecting platform specific code. The recommended form of the property value is:"manufacturer,model"

serial-number O <string> Specifies a string representing the device’s serial number.

chassis-type OR <string> Specifies a string that identifies the form-factor of the system. The property value can be one of:

Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition

Note 注意

All other standard properties (Section 2.3) are allowed but are optional.

## 3.3 /aliases node 节点

A devicetree may have an aliases node (/aliases) that defines one or more alias properties. The alias node shall be at the root of the devicetree and have the node name /aliases.

Each property of the /aliases node defines an alias. The property name specifies the alias name. The property value specifies the full path to a node in the devicetree. For example, the property serial0 = "/simple-bus@fe000000/serial@llc500" defines the alias serial0.

/aliases节点的每个属性都定义一个别名。属性名指定别名。属性值指定到设备树中某个节点的完整路径。例如，属性 serial0 ="/simple-bus@fe000000/serial@llc500"定义了别名 serial0

Alias names shall be a lowercase text strings of 1 to 31 characters from the following set of characters.

Character 性格 Description 描述
0-9 digit 数字
a-z lowercase letter 小写字母
- dash 破折号

An alias value is a device path and is encoded as a string. The value represents the full path to a node, but the path does not need to refer to a leaf node.

A client program may use an alias property name to refer to a full device path as all or part of its string value. A client program, when considering a string as a device path, shall detect and use the alias.

Example

aliases {
serial0 = "/simple-bus@fe000000/serial@llc500";
ethernet0 = "/simple-bus@fe000000/ethernet@31c000";
};


Given the alias serial0, a client program can look at the /aliases node and determine the alias refers to the device path /simple-bus@fe000000/serial@llc500.

## 3.4 /memory node 节点

A memory device node is required for all devicetrees and describes the physical memory layout for the system. If a system has multiple ranges of memory, multiple memory nodes can be created, or the ranges can be specified in the reg property of a single memory node.

The unit-name component of the node name (see Section 2.2.1) shall be memory.

The client program may access memory not covered by any memory reservations (see Section 5.3) using any storage attributes it chooses. However, before changing the storage attributes used to access a real page, the client program is responsible for performing actions required by the architecture and implementation, possibly including flushing the real page from the caches. The boot program is responsible for ensuring that, without taking any action associated with a change in storage attributes, the client program can safely access all memory (including memory covered by memory reservations) as WIMG = 0b001x. That is:

• not Write Through Required 不需要写透
• not Caching Inhibited 不禁止缓存
• Memory Coherence 记忆体一致性
• Required either not Guarded or Guarded
• 要求不受保护或受保护

If the VLE storage attribute is supported, with VLE=0.

Property Name Usage Value Type Definition
device_type R <string> Value shall be “memory”
reg R <prop-encoded-array> Consists of an arbitrary number of address and size pairs that specify the physical address and size of the memory ranges.

initial-mapped-area O <prop-encoded-array> Specifies the address and size of the Initial Mapped Area

Is a prop-encoded-array consisting of a triplet of (effective address, physical address, size). The effective and physical address shall each be 64-bit (<u64> value), and the size shall be 32-bits (<u32> value).

hotpluggable O <empty> Specifies an explicit hint to the operating system that this memory may potentially be removed later.

### 3.4.1 /memory node and UEFI 节点和 UEFI

When booting via [UEFI], the system memory map is obtained via the GetMemoryMap() UEFI boot time service as defined in [UEFI] § 7.2, and if present, the OS must ignore any /memory nodes.

### 3.4.2 /memory Examples 例子

Given a 64-bit Power system with the following physical memory layout:

• RAM: starting address 0x0, length 0x80000000 (2 GB) RAM: 起始地址0x0，长度0x80000000(2GB)
• RAM: starting address 0x100000000, length 0x100000000 (4 GB) RAM: 起始地址0x100000000，长度0x10000000(4 GB)

Memory nodes could be defined as follows, assuming #address-cells = <2> and #size-cells = <2>.

Example #1

memory@0 {
device_type = "memory";
reg = <0x000000000 0x00000000 0x00000000 0x80000000
0x000000001 0x00000000 0x00000001 0x00000000>;
};


Example #2

memory@0 {
device_type = "memory";
reg = <0x000000000 0x00000000 0x00000000 0x80000000>;
};
memory@100000000 {
device_type = "memory";
reg = <0x000000001 0x00000000 0x00000001 0x00000000>;
};


The reg property is used to define the address and size of the two memory ranges. The 2 GB I/O region is skipped. Note that the #address-cells and #size-cells properties of the root node specify a value of 2, which means that two 32-bit cells are required to define the address and length for the reg property of the memory node.

Reg 属性用于定义两个内存范围的地址和大小。跳过2GB的 I/O 区域。注意，根节点的 # address-cells 和 # size-cells 属性指定的值为2，这意味着需要两个32位单元来定义内存节点的 reg 属性的地址和长度。

## 3.5 /chosen Node

The /chosen node does not represent a real device in the system but describes parameters chosen or specified by the system firmware at run time. It shall be a child of the root node.

/chosen节点并不代表系统中的一个真实设备，而是描述运行时由系统固件选择或指定的参数。 系统固件在运行时选择或指定的参数。它应是根节点的一个子节点。

• bootargs,可选，<string>类型 A string that specifies the boot arguments for the client program. The value could poten- tially be a null string if no boot arguments are required.

一个字符串，用于指定客户程序的启动参数。如果不需要启动参数，该值有可能是一个空字符串。

• stdout-path, 可选，<string>类型

A string that specifies the full path to the node representing the device to be used for boot console output. If the character “:” is present in the value it terminates the path. The value may be an alias. If the stdin-path property is not specified, stdout-path should be assumed to define the input device.

一个字符串，指定了代表设备的节点的完整路径，用于启动控制台输出。如果值中有字符”:”，它将终止路径。该值可以是一个别名。如果没有指定stdin-path属性，应假定stdout-path定义输入设备

• stdin-path, 可选，<string>类型

A string that specifies the full path to the node representing the device to be used for boot console input. If the character “:” is present in the value it terminates the path. The value may be an alias.

一个字符串，指定代表设备的节点的完整路径，用于启动控制台输入。如果值中有字符”:”，它将终止路径。该值可以是一个别名。

chosen {
bootargs = "root=/dev/nfs rw nfsroot=192.168.1.1 console=ttyS0,115200";
};


Older versions of devicetrees may be encountered that contain a deprecated form of the stdout-path property called linux,stdout-path. For compatibility, a client program might want to support linux,stdout-path if a stdout-path property is not present. The meaning and use of the two properties is identical.

## 3.6 /cpus Node Properties

A /cpus node is required for all devicetrees. It does not represent a real device in the system, but acts as a container for child cpu nodes which represent the systems CPUs.

• 属性名
• #address-cells, R, <u32>

The value specifies how many cells each element of the reg property array takes in children of this node.

该值指定reg属性数组的每个元素在该节点的子节点中占多少个单元

• #size-cells, R,<u32>

Value shall be 0. Specifies that no size is required in the reg property in children of this node.

指定此节点的子节点的reg属性中不需要尺寸

/cpus节点可能包含跨cpu节点的共同属性。详见3.7节。

## 3.7 /cpus/cpu* Node Properties

A cpu node represents a hardware execution block that is sufficiently independent that it is capable of running an operating system without interfering with other CPUs possibly running other operating systems.

Hardware threads that share an MMU would generally be represented under one cpu node. If other more complex CPU topographies are designed, the binding for the CPU must describe the topography (e.g. threads that don’t share an MMU).

CPUs and threads are numbered through a unified number-space that should match as closely as possible the interrupt controller’s numbering of CPUs/threads.

CPU和线程通过一个统一的数字空间进行编号，该数字空间应尽可能地与中断控制器对CPU/线程的编号相匹配。

Properties that have identical values across cpu nodes may be placed in the /cpus node instead. A client program must first examine a specific cpu node, but if an expected property is not found then it should look at the parent /cpus node. This results in a less verbose representation of properties which are identical across all CPUs.

The node name for every CPU node should be cpu.

### 3.7.1 General Properties of /cpus/cpu* nodes

The following table describes the general properties of cpu nodes. Some of the properties described in Table 3.6 are select standard properties with specific applicable detail.

• 属性名
• device_type, R, <string>

Value shall be “cpu”

• reg, R, array

• The value of reg is a <prop-encoded-array> that defines a unique CPU/thread id for the CPU/threads represented by the CPU node.

reg的值是一个<prop-encoded-array>，它为CPU节点所代表的CPU/线程定义了一个唯一的CPU/线程ID。

• If a CPU supports more than one thread (i.e. multiple streams of execution) the reg property is an array with 1 element per thread. The #address-cells on the /cpus node specifies how many cells each element of the array takes. Software can determine the number of threads by dividing the size of reg by the parent node’s #address-cells.

• If a CPU/thread can be the target of an external interrupt the reg property value must be a unique CPU/thread id that is addressable by the interrupt controller.

如果一个CPU/线程可以成为外部中断的目标，那么reg属性值必须是一个唯一的CPU/线程ID，可以被中断控制器寻址。

• If a CPU/thread cannot be the target of an external interrupt, then reg must be unique and out of bounds of the range addressed by the interrupt controller

如果一个CPU/线程不能成为外部中断的目标，那么reg必须是唯一的，并且超出了中断控制器寻址的范围。

• If a CPU/thread’s PIR (pending interrupt reg- ister) is modifiable, a client program should modify PIR to match the reg property value. If PIR cannot be modified and the PIR value is distinct from the interrupt controller number space, the CPUs binding may define a binding-specific representation of PIR values if desired.

如果CPU/线程的PIR（挂起的中断调节器）是可以修改的，客户程序应该修改PIR以匹配reg属性值。如果PIR不能被修改，而且PIR值与中断控制器的数字空间不同，如果需要的话，CPU的绑定可以定义PIR值的绑定特定表示。

• clock-frequency, R, array

• Specifies the current clock speed of the CPU in Hertz. The value is a <prop-encoded-array> in one of two forms:

指定CPU的当前时钟速度，单位是赫兹。该值是一个<prop-encoded-array>，有两种形式之一。

• A 32-bit integer consisting of one <u32> specifying the frequency.

一个32位的整数，由一个<u32>组成，指定频率。

• A64-bitintegerrepresentedasa<u64> specifying the frequency.

一个64位的整数，表示为<u64>，指定频率。

• timebase-frequency, R, array

• Specifies the current frequency at which the timebase and decrementer registers are up- dated (in Hertz). The value is a <prop-encoded-array> in one of two forms:

指定当前更新时间基准和递减器寄存器的频率（单位：赫兹）。该值是一个<prop-encoded-array>，有两种形式之一。

• A 32-bit integer consisting of one <u32> specifying the frequency.

一个32位的整数，由一个<u32>组成，指定频率。

• A 64-bit integer represented as a <u64>.

一个64位的整数，表示为<u64>

• status, SR, <string>

• A standard property describing the state of a CPU. This property shall be present for nodes representing CPUs in a symmetric mul- tiprocessing (SMP) configuration. For a CPU node the meaning of the “okay” and “disabled” values are as follows: “okay” : The CPU is running. “disabled” : The CPU is in a quiescent state.

一个描述CPU状态的标准属性。对于代表对称多处理（SMP）配置中的CPU的节点，该属性应存在。对于一个CPU节点，”好 “和 “禁用 “值的含义如下。”okay” : CPU正在运行。”disabled”：CPU处于静止状态。

• A quiescent CPU is in a state where it cannot interfere with the normal operation of other CPUs, nor can its state be affected by the normal operation of other running CPUs, except by an explicit method for enabling or re- enabling the quiescent CPU (see the enable method property).

静止的CPU处于一种状态，它不能干扰其他CPU的正常运行，其状态也不能被其他运行中的CPU的正常运行所影响，除非通过明确的方法来启用或重新启用静止的CPU（见启用方法属性）。

• In particular, a running CPU shall be able to issue broadcast TLB invalidates without affecting a quiescent CPU.

特别是，运行中的CPU应能发出广播TLB无效，而不影响静止的CPU。

• Examples: A quiescent CPU could be in a spin loop, held in reset, and electrically isolated from the system bus or in another implementation dependent state.

例子。静止的CPU可以在自旋循环中，保持在复位状态，并与系统总线电隔离，或处于另一个与实施有关的状态。

• enable-method, SD, <stringlist>

• Describes the method by which a CPU in a disabled state is enabled. This property is re- quired for CPUs with a status property with a value of “disabled”. The value consists of one or more strings that define the method to release this CPU. If a client program recog- nizes any of the methods, it may use it. The value shall be one of the following: “spin-table” : The CPU is enabled with

描述了处于禁用状态的CPU被启用的方法。对于状态属性值为 “disabled “的CPU来说，这个属性是重新要求的。该值由一个或多个字符串组成，定义释放该CPU的方法。如果客户程序识别了其中任何一种方法，它就可以使用它。该值应是以下之一。“spin-table “ 。该CPU被启用时有

• the spin table method defined in the DT-Spec.

在DT-Spec中定义的自旋表方法。

• “[vendor],[method]” : Implementation dependent string that describes the method by which a CPU is released from a “disabled” state. The required format is: “[vendor], [method]”, where vendor is a string describing the name of the manufacturer and method is a string describing the vendor specific mechanism.

“[vendor],[method]”：描述CPU从 “禁用 “状态释放的方法的与实施相关的字符串。要求的格式是。”[vendor], [method]”，其中vendor是一个描述制造商名称的字符串，method是一个描述供应商特定机制的字符串。

• Example: “fsl,MPC8572DS”

• Note: Other methods may be added to later revisions of the DTSpec specification.

注：其他方法可能会被添加到DTSpec规范的后期修订中。

• cpu-release-addr, SD, <u64>

• The cpu-release-addr property is required for cpu nodes that have an enable-method prop- erty value of “spin-table”. The value specifies the physical address of a spin table entry that releases a secondary CPU from its spin loop.

### 3.7.2 TLB Properties

The following properties of a cpu node describe the translate look-aside buffer in the processor’s MMU.

cpu节点的以下属性描述了处理器MMU中的翻译查找缓冲区。

## 3.5. /reserved-memory Node 节点

Reserved memory is specified as a node under the /reserved-memory node. The operating system shall exclude reserved memory from normal usage. One can create child nodes describing particular reserved (excluded from normal use) memory regions. Such memory regions are usually designed for the special usage by various device drivers.

Parameters for each memory region can be encoded into the device tree with the following nodes:

### 3.5.1. /reserved-memory parent node

Property Name Usage Value Type Definition
#address-cells R <u32> Specifies the number of <u32> cells to represent the address in the reg property in children of root.

#size-cells R <u32> Specifies the number of <u32> cells to represent the size in the reg property in children of root.

ranges R <prop encoded array> This property represents the mapping between parent address to child address spaces (see Section 2.3.8, ranges).

#address-cells and #size-cells should use the same values as for the root node, and ranges should be empty so that address translation logic works correctly.

# address-cells 和 # size-cells 应该使用与根节点相同的值，并且范围应该为空，这样地址转换逻辑才能正常工作。

### 3.5.2. /reserved-memory/ child nodes

Each child of the reserved-memory node specifies one or more regions of reserved memory. Each child node may either use a reg property to specify a specific range of reserved memory, or a size property with optional constraints to request a dynamically allocated block of memory.

Following the generic-names recommended practice, node names should reflect the purpose of the node (ie. “framebuffer” or “dma-pool”). Unit address (@<address>) should be appended to the name if the node is a static allocation.

A reserved memory node requires either a reg property for static allocations, or a size property for dynamics allocations. Dynamic allocations may use alignment and alloc-ranges properties to constrain where the memory is allocated from. If both reg and size are present, then the region is treated as a static allocation with the reg property taking precedence and size is ignored.

Property Name Usage Value Type Definition
reg O <prop-encoded-array> Consists of an arbitrary number of address and size pairs that specify the physical address and size of the memory ranges.

size O <prop-encoded-array> Size in bytes of memory to reserve for dynamically allocated regions. Size of this property is based on parent node’s #size-cells property.

alignment O <prop-encoded-array> Address boundary for alignment of allocation. Size of this property is based on parent node’s #size-cells property.分配对齐的地址边界。此属性的大小基于父节点的 # Size-cells 属性。
alloc-ranges O <prop-encoded-array> Specifies regions of memory that are acceptable to allocate from. Format is (address, length pairs) tuples in same format as for reg properties.

compatible O <stringlist> May contain the following strings:可能包含以下字符串:shared-dma-pool: This indicates a region of memory meant to be used as a shared pool of DMA buffers for a set of devices. It can be used by an operating system to instantiate the necessary pool management subsystem if necessary.Shared-DMA-pool: 这表示内存的一个区域，用作一组设备的 DMA 缓冲区的共享池。如果需要，操作系统可以使用它来实例化必要的池管理子系统。vendor specific string in the form <vendor>,[<device>-]<usage>供应商特定的字符串形式 < 供应商 > ，[ < 设备 >-] < 使用 >
no-map O <empty> If present, indicates the operating system must not create a virtual mapping of the region as part of its standard mapping of system memory, nor permit speculative access to it under any circumstances other than under the control of the device driver using the region.

reusable O <empty> The operating system can use the memory in this region with the limitation that the device driver(s) owning the region need to be able to reclaim it back. Typically that means that the operating system can use that region to store volatile or cached data that can be otherwise regenerated or migrated elsewhere.

Note

All other standard properties (Section 2.3) are allowed but are optional.

The no-map and reusable properties are mutually exclusive and both must not be used together in the same node.

Linux implementation notes:

• If a linux,cma-default property is present, then Linux will use the region for the default pool of the contiguous memory allocator.
• 如果存在 Linux，cma-default 属性，那么 Linux 将使用该区域作为连续内存分配器的默认池。
• If a linux,dma-default property is present, then Linux will use the region for the default pool of the consistent DMA allocator.
• 如果存在 Linux，DMA-default 属性，那么 Linux 将使用该区域作为一致的 DMA 分配器的默认池。

### 3.5.3. Device node references to reserved memory 设备节点引用保留内存

Regions in the /reserved-memory node may be referenced by other device nodes by adding a memory-region property to the device node.

Property Name Usage 用法 Value Type 值类型 Definition 定义
memory-region O <prop-encoded-array> phandle, specifier pairs to children of /reserved-memory
/reserved-memory子(phandle，specifier)对
memory-region-names O <stringlist> A list of names, one for each corresponding entry in the memory-region
property名称列表，对应于内存区域属性中的每个相应条目

### 3.5.4. /reserved-memory and UEFI 及 UEFI

When booting via UEFI, static /reserved-memory regions must also be listed in the system memory map obtained via the GetMemoryMap() UEFI boot time service as defined in UEFI § 7.2. The reserved memory regions need to be included in the UEFI memory map to protect against allocations by UEFI applications.

Reserved regions with the no-map property must be listed in the memory map with type EfiReservedMemoryType. All other reserved regions must be listed with type EfiBootServicesData.

Dynamic reserved memory regions must not be listed in the [UEFI] memory map because they are allocated by the OS after exiting firmware boot services.

### 3.5.5. /reserved-memory Example 例子

This example defines 3 contiguous regions are defined for Linux kernel: one default of all device drivers (named linux,cma and 64MiB in size), one dedicated to the framebuffer device (named framebuffer@78000000, 8MiB), and one for multimedia processing (named multimedia@77000000, 64MiB).

/ {
#size-cells = <1>;

memory {
reg = <0x40000000 0x40000000>;
};

reserved-memory {
#size-cells = <1>;
ranges;

/* global autoconfigured region for contiguous allocations */
linux,cma {
compatible = "shared-dma-pool";
reusable;
size = <0x4000000>;
alignment = <0x2000>;
linux,cma-default;
};

display_reserved: framebuffer@78000000 {
reg = <0x78000000 0x800000>;
};

multimedia_reserved: multimedia@77000000 {
compatible = "acme,multimedia-memory";
reg = <0x77000000 0x4000000>;
};
};

/* ... */

fb0: video@12300000 {
memory-region = <&display_reserved>;
/* ... */
};

scaler: scaler@12500000 {
memory-region = <&multimedia_reserved>;
/* ... */
};

codec: codec@12600000 {
memory-region = <&multimedia_reserved>;
/* ... */
};
};


# 4. DEVICE BINDINGS

This chapter contains requirements, known as bindings, for how specific types and classes of devices are represented in the devicetree. The compatible property of a device node describes the specific binding (or bindings) to which the node complies.

Bindings may be defined as extensions of other each. For example a new bus type could be defined as an extension of the simple-bus binding. In this case, the compatible property would contain several strings identifying each binding—from the most specific to the most general (see section 2.3.1, compatible).

## 4.1 Binding Guidelines**

### 4.1.1 General Principles

When creating a new devicetree representation for a device, a binding should be created that fully describes the required properties and value of the device. This set of properties shall be sufficiently descriptive to provide device drivers with needed attributes of the device.

Some recommended practices include:

1. Define a compatible string using the conventions described in section 2.3.1.

2. Use the standard properties (defined in sections 2.3 and 2.4) as applicable for the new device. This usage typically includes the reg and interrupts properties at a minimum.

3. Use the conventions specified in section 4 (Device Bindings) if the new device fits into one the DTSpec defined device classes.

4. Use the miscellaneous property conventions specified in section 4.1.2, if applicable.

5. If new properties are needed by the binding, the recommended format for property names is: “, ", where is an OUI or short unique string like a stock ticker that identifies the creator of the binding.

Example: “ibm,ppc-interrupt-server#s”

1. 使用2.3.1节中描述的惯例，定义一个兼容的字符串。

2. 使用适用于新设备的标准属性（定义在2.32.4部分）。这种用法通常至少包括寄存器和中断属性。

3. 如果新设备符合DTSpec定义的设备类别之一，则使用4节（设备绑定）中规定的惯例。

4. 如果适用的话，使用4.1.2节中规定的杂项属性约定。

5. 如果绑定需要新的属性，推荐的属性名称格式是。”<公司>，<属性名称>"，其中<公司>是一个OUI或像股票代码一样的唯一短字符串，用于识别绑定的创建者。

例如。”ibm,ppc-interrupt-server#s”

### 4.1.2 Miscellaneous Properties 杂项属性

This section defines a list of helpful properties that might be applicable to many types of devices and device classes. They are defined here to facilitate standardization of names and usage.

#### clock-frequency Property

• Value type: <prop-encoded-array>
• Description
• Specifies the frequency of a clock in Hz. The value is a <prop-encoded-array> in one of two forms:

指定一个时钟的频率，单位为Hz。该值是一个<prop-encoded-array>，有两种形式之一。

• a 32-bit integer consisting of one <u32> specifying the frequency

一个32位的整数，由一个<u32>组成，指定频率

• a 64-bit integer represented as a <u64> specifying the frequency

一个64位的整数，以<u64>表示，指定频率。

#### reg-shift Property

• Value type: <u32>
• Description
• The reg-shift property provides a mechanism to represent devices that are identical in most re- spects except for the number of bytes between registers. The reg-shift property specifies in bytes how far the discrete device registers are separated from each other. The individual register location is calculated by using following formula: “registers address” « reg-shift. If unspecified, the default value is 0.

寄存器移位属性提供了一种机制，用于表示除了寄存器之间的字节数之外，在大多数重新方面都相同的设备。寄存器移位属性以字节为单位指定离散的设备寄存器之间的距离。各个寄存器的位置是通过以下公式计算的。”寄存器地址” « reg-shift。如果没有指定，默认值为0。

• For example, in a system where 16540 UART registers are located at addresses 0x0, 0x4, 0x8, 0xC, 0x10, 0x14, 0x18, and 0x1C, a reg-shift = <2> property would be used to specify register locations.

例如，在一个系统中，16540 UART寄存器位于地址0x0、0x4、0x8、0xC、0x10、0x14、0x18和0x1C，reg-shift = <2> 属性将被用来指定寄存器位置

#### label Property

• Value type: <string>
• Description:
• The label property defines a human readable string describing a device. The binding for a given device specifies the exact meaning of the property for that device.

标签属性定义了一个描述设备的人类可读字符串。对一个给定设备的绑定规定了该设备的属性的确切含义。

## 4.2 Serial devices

### 4.2.1 Serial Class Binding

The class of serial devices consists of various types of point to point serial line devices. Examples of serial line devices include the 8250 UART, 16550 UART, HDLC device, and BISYNC device. In most cases hardware compatible with the RS-232 standard fit into the serial device class.

I2C and SPI (Serial Peripheral Interface) devices shall not be represented as serial port devices because they have their own specific representation.

I2C和SPI（串行外设接口）设备不应表示为串行端口设备，因为它们有自己的具体表示方法

#### clock-frequency Property

• Value type: <u32>
• Description:
• Specifies the frequency in Hertz of the baud rate generator’s input clock.

指定波特率发生器的输入时钟的频率，单位为赫兹

• example:

clock-frequency = <100000000>;

#### current-speed Property

• Value type: <u32>
• Description
• Specifies the current speed of a serial device in bits per second. A boot program should set this property if it has initialized the serial device.

指定一个串行设备的当前速度，单位是比特/秒。如果一个启动程序已经初始化了串行设备，就应该设置这个属性。

### 4.2.2 National Semiconductor 16450/16550 Compatible UART Requirements 美国国家半导体16450/16550兼容UART要求

Serial devices compatible to the National Semiconductor 16450/16550 UART (Universal Asynchronous Receiver Trans- mitter) should be represented in the devicetree using following properties.

compatible R <string list> Value shall include “ns16550”
clock-frequency R <u32> Specifies the frequency (in Hz) of the baud rate generator’s input clock

current-speed OR <u32> Specifies current serial device speed in bits per second

reg R <prop-encoded-arry> Specifies the physical address of the registers device within the address space of the parent

interrupts OR <prop-encoded-arry> Specifies the interrupts generated by this de- vice. The value of the interrupts property con- sists of one or more interrupt specifiers. The format of an interrupt specifier is defined by the binding document describing the node’s in- terrupt parent.

reg-shift O <u32> Specifies in bytes how far the discrete de- vice registers are separated from each other. The individual register location is calculated by using following formula: “registers address” « reg-shift. If unspeci- fied, the default value is 0.

virtual-reg SD <u32> /<u64> See section 2.3.7. Specifies an effective address that maps to the first physical address specified in the reg property. This property is required if this device node is the system’s

Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition

## 4.3 Network devices

Network devices are packet oriented communication devices. Devices in this class are assumed to implement the data link layer (layer 2) of the seven-layer OSI model and use Media Access Control (MAC) addresses. Examples of network devices include Ethernet, FDDI, 802.11, and Token-Ring.

### 4.3.2 Ethernet specific considerations

Network devices based on the IEEE 802.3 collections of LAN standards (collectively referred to as Ethernet) may be represented in the devicetree using following properties, in addition to properties specified of the network device class. The properties listed in this section augment the properties listed in the network device class.

## 4.4 Power ISA Open PIC Interrupt Controllers

This section specifies the requirements for representing Open PIC compatible interrupt controllers. An Open PIC interrupt controller implements the Open PIC architecture (developed jointly by AMD and Cyrix) and specified in The Open Programmable Interrupt Controller (PIC) Register Interface Specification Revision 1.2 [b18].

## 4.5 simple-bus Compatible Value

System-on-a-chip processors may have an internal I/O bus that cannot be probed for devices. The devices on the bus can be accessed directly without additional configuration required. This type of bus is represented as a node with a compatible value of “simple-bus”.

### simple-bus兼容的节点属性

compatible R <string> Value shall include “simple-bus”.
ranges R   This property represents the mapping between parent address to child address spaces (see section 2.3.8, ranges)

Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition

# 5. 扁平化的设备树（DTB）格式

The Devicetree Blob (DTB) format is a flat binary encoding of devicetree data. It used to exchange devicetree data between software programs. For example, when booting an operating system, firmware will pass a DTB to the OS kernel.

Devicetree Blob（DTB）格式是一种扁平的二进制编码的devicetree数据。它用于在软件程序之间交换devicetree数据。例如，在启动操作系统时，固件将向操作系统内核传递一个DTB。

The DTB format encodes the devicetree data within a single, linear, pointerless data structure. It consists of a small header (see section 5.2), followed by three variable sized sections: the memory reservation block (see section 5.3), the structure block (see secton 5.4), and the strings block (see section 5.5). These should be present in the flattened devicetree in that order. Thus, the devicetree structure as a whole, when loaded into memory at address, will resemble the diagram in Fig. 5.1 (lower addresses are at the top of the diagram).

DTB格式在一个单一的、线性的、无指针的数据结构中对devicetree数据进行编码。它包括一个小头（见第5.2节），然后是三个大小不一的部分：内存保留块（见第5.3节）、结构块（见第5.4节）和字符串块（见第5.5节）。这些都应该按照这个顺序出现在扁平化的devicetree中。因此，devicetree结构作为一个整体，当按地址加载到内存中时，将类似于图5.1中的图（低地址在图的顶部）。

The (free space) sections may not be present, though in some cases they might be required to satisfy the alignment constraints of the individual blocks (see section 5.6).

(自由空间)部分可能不存在，尽管在某些情况下可能需要它们来满足单个块的对齐限制（见5.6节）。

## 5.1 Versioning

Several versions of the flattened devicetree structure have been defined since the original definition of the format. Fields in the header give the version, so that the client program can determine if the devicetree is encoded in a compatible format.

This document describes only version 17 of the format. DTSpec compliant boot programs shall provide a devicetree of version 17 or later, and should provide a devicetree of a version that is backwards compatible with version 16. DTSpec compliant client programs shall accept devicetrees of any version backwards compatible with version 17 and may accept other versions as well.

The layout of the header for the devicetree is defined by the following C structure. All the header fields are 32-bit integers, stored in big-endian format.

devicetree的头的布局由以下C结构定义。所有的头字段都是32位整数，以big-endian格式存储。

struct fdt_header {
uint32_t magic;
uint32_t totalsize;
uint32_t off_dt_struct;
uint32_t off_dt_strings;
uint32_t off_mem_rsvmap;
uint32_t version;
uint32_t last_comp_version;
uint32_t boot_cpuid_phys;
uint32_t size_dt_strings;
uint32_t size_dt_struct;
};


## 5.6 Alignment

For the data in the memory reservation and structure blocks to be used without unaligned memory accesses, they shall lie at suitably aligned memory addresses. Specifically, the memory reservation block shall be aligned to an 8-byte boundary and the structure block to a 4-byte boundary.

Furthermore, the devicetree blob as a whole can be relocated without destroying the alignment of the subblocks.

As described in the previous sections, the structure and strings blocks shall have aligned offsets from the beginning of the devicetree blob. To ensure the in-memory alignment of the blocks, it is sufficient to ensure that the devicetree as a whole is loaded at an address aligned to the largest alignment of any of the subblocks, that is, to an 8-byte boundary. A DTSpec compliant boot program shall load the devicetree blob at such an aligned address before passing it to the client program. If an DTSpec client program relocates the devicetree blob in memory, it should only do so to another 8-byte aligned address.

# 6. DEVICETREE SOURCE (DTS) FORMAT (VERSION 1) 设备树源(DTS)格式(版本1)

The Devicetree Source (DTS) format is a textual representation of a devicetree in a form that can be processed by dtc into a binary devicetree in the form expected by the kernel. The following description is not a formal syntax definition of DTS, but describes the basic constructs used to represent devicetrees.

Devicetree Source (DTS)格式是一种文本形式的devicetree表示，它可以被dtc处理成内核所期望的二进制devicetree形式。下面的描述并不是DTS的正式语法定义，而是描述用来表示devicetree的基本结构。

The name of DTS files should end with “.dts”.

DTS文件的名称应该以”.dts “结尾

## 6.1 Compiler directives

Other source files can be included from a DTS file. The name of include files should end with “.dtsi”. Included files can in turn include additional files.

/include/ "FILE"


## 6.2 Labels

The source format allows labels to be attached to any node or property value in the devicetree. Phandle and path references can be automatically generated by referencing a label instead of explicitly specifying a phandle value or the full path to a node. Labels are only used in the devicetree source format and are not encoded into the DTB binary.

A label shall be between 1 to 31 characters in length, be composed only of the characters in the set Table 6.1, and must not start with a number.

Labels are created by appending a colon (‘:’) to the label name. References are created by prefixing the label name with an ampersand (‘&’).

## 6.3 Node and property definitions

Devicetree nodes are defined with a node name and unit address with braces marking the start and end of the node definition. They may be preceded by a label.

Devicetree节点是用节点名称和单元地址来定义的，用大括号标记节点定义的开始和结束。它们前面可以有一个标签。

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


Nodes may contain property definitions and/or child node definitions. If both are present, properties shall come before child nodes.

Previously defined nodes may be deleted.

/delete-node/ node-name;
/delete-node/ &label;


Property definitions are name value pairs in the form:

[label:] property-name = value;


except for properties with empty (zero length) value which have the form:

[label:] property-name;


Previously defined properties may be deleted.

/delete-property/ property-name;


Property values may be defined as an array of 32-bit integer cells, as null-terminated strings, as bytestrings or a combination of these.

• Arrays of cells are represented by angle brackets surrounding a space separated list of C-style integers. Example:

单元数组用角括号表示，周围是以空格分隔的C语言整数列表。例如：

interrupts = <17 0xc>;

• values may be represented as arithmetic, bitwise, or logical expressions within parenthesis.

值可以用括号内的算术、比特或逻辑表达式表示

• A 64-bit value is represented with two 32-bit cells. Example:

一个64位的值用两个32位的单元表示。例子:

clock-frequency = <0x00000001 0x00000000>;

• A null-terminated string value is represented using double quotes (the property value is considered to include the terminating NULL character). Example:

一个以空为结尾的字符串值用双引号表示（属性值被认为包括结尾的NULL字符）。例子:

  compatible = "simple-bus";

• A bytestring is enclosed in square brackets [ ] with each byte represented by two hexadecimal digits. Spaces between each byte are optional. Example:

字节串用方括号[ ]括起来，每个字节用两个十六进制的数字表示。每个字节之间的空格是可选的。例子:

local-mac-address = [00 00 12 34 56 78];

• Values may have several comma-separated components, which are concatenated together. Example:

值可能有几个逗号分隔的部分，这些部分被串联在一起。例子:

compatible = "ns16550", "ns8250";
example = <0xf00f0000 19>, "a strange property format";

• In a cell array a reference to another node will be expanded to that node’s phandle. References may be & followed by a node’s label. Example:

在一个单元格阵列中，对另一个节点的引用将被扩展到该节点的范本。引用可以是&，后面是一个节点的标签。例子:

interrupt-parent = < &mpic >;
interrupt-parent = < &{/soc/interrupt-controller@40000} >;

• Outside a cell array, a reference to another node will be expanded to that node’s full path. Example:

在单元格阵列之外，对另一个节点的引用将被扩展为该节点的完整路径。例子:

ethernet0 = &EMAC0;

• Labels may also appear before or after any component of a property value, or between cells of a cell array, or between bytes of a bytestring. Examples:

标签也可以出现在属性值的任何组件之前或之后，或在单元格阵列的单元格之间，或在字节串的字节之间。例子

reg = reglabel: <0 sizelabel: 0x1000000>;
prop = [ab cd ef byte4: 00 ff fe];
str = start: "string value" end: ;


## 6.4 File layout

/dts-v1/;
[memory reservations]
/ {
[property definitions]
[child nodes]
};


The /dts-v1/; shall be present to identify the file as a version 1 DTS (dts files without this tag will be treated by dtc as being in the obsolete version 0, which uses a different format for integers in addition to other small but incompatible changes).

/dts-v1/;应该出现，以确定该文件是版本1的DTS（没有这个标签的dts文件将被dtc视为过时的版本0，除了其他小但不兼容的变化外，它还使用了不同的整数格式）。

Memory reservations define an entry for the devicetree blob’s memory reservation table. They have the form: e.g., /memreserve/ <address> <length>; Where <address> and <length> are 64-bit C-style integers.

• The / { }; section defines the root node of the devicetree.

/ { };部分定义了devicetree的根节点

• C style (/* . . . */) and C++ style (//) comments are supported.

支持C风格的(/* . . */)和C++风格的(//)注释

# zephyr 设备树相关

There are two types of devicetree input files: devicetree sources and devicetree bindings. The sources contain the devicetree itself. The bindings describe its contents, including data types. The build system uses devicetree sources and bindings to produce a generated C header. The generated header’s contents are abstracted by the devicetree.h API, which you can use to get information from your devicetree.

Here is a simplified view of the process:

Fig. 20 Devicetree build flow

All Zephyr and application source code files can include and use devicetree.h. This includes device drivers, applications, tests, the kernel, etc.

The API itself is based on C macros. The macro names all start with DT_. In general, if you see a macro that starts with DT_ in a Zephyr source file, it’s probably a devicetree.h macro. The generated C header contains macros that start with DT_ as well; you might see those in compiler error messages. You always can tell a generated- from a non-generated macro: generated macros have some lowercased letters, while the devicetree.h macro names have all capital letters.

API 本身是基于 c 宏的。宏名都以 DT_开头。通常，如果在 Zephyr 源文件中看到一个以 DT_开头的宏，那么它可能是一个 devicetree.h 宏。生成的 c 头包含以 DT_开头的宏; 您可能会在编译器错误消息中看到这些宏。您总是可以从未生成的宏中分辨出生成的宏: 生成的宏有一些小写字母，而 devicetree.h 宏名称都是大写字母。

Some information defined in devicetree is available via CONFIG_ macros generated from Kconfig. This is often done for backwards compatibility, since Zephyr has used Kconfig for longer than devicetree, and is still in the process of converting some information from Kconfig to devicetree. It is also done to allow Kconfig overrides of default values taken from devicetree. Devicetree information is referenced from Kconfig via Kconfig functions. See Devicetree versus Kconfig for some additional comparisons with Kconfig.

## Syntax and structure 语法和结构¶

As the name indicates, a devicetree is a tree. The human-readable text format for this tree is called DTS (for devicetree source), and is defined in the Devicetree specification.

Here is an example DTS file:

/dts-v1/;

/ {
a-node {
subnode_nodelabel: a-sub-node {
foo = <3>;
label = "SUBNODE";
};
};
};


• 名称为cpu的节点是通过其单元地址值0和1来区分的
• 名称为ethernet的节点通过其单元地址fe002000和fe003000的值来区分