设备树

 

设备树手册

  • 设备树手册

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:

这个规范,即Devicetree规范(DTSpec),提供了一个完整的引导程序到客户程序接口的定义,结合最低的系统要求,促进了各种系统的开发。 这个规范是针对嵌入式系统的要求的。一个嵌入式系统通常由系统硬件、操作系统和应用软件组成,这些都是为执行固定的、特定的任务集而定制的。这与通用计算机不同,通用计算机的设计是由用户通过各种软件和I/O设备来定制。嵌入式系统的其他特点可能包括:

  • 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.

非对称多处理。计算机可用的CPU被分成若干组,每组运行一个不同的操作系统镜像。这些CPU可能是也可能不是相同的。

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.

嵌入式环境。Power ISA的一部分,定义了嵌入式Power处理器实现中使用的监督器指令和相关设施

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.

通常包含应用程序或操作系统软件的程序。客户机程序的例子包括:引导加载程序、虚拟机监控程序、操作系统和特殊用途的程序。

一个hypervisor(又被称为virtual machine monitor,VMM,或virtualizer)是一种模拟器;它是创建或者运行虚拟机的软件、固件、或者硬件。一个计算机,上面运行着一个hypervisor,hypervisor上面又运行着一个或多个虚拟机,该计算机被称为host machine,每一个虚拟机被叫做guest machine。hypervisor为guest operating system营造了一个虚拟的操作系统,并且对guest operating system的运行进行管理。多个不同的操作系统能够共享虚拟化的硬件资源:例如,Linux,Windows,macOS实例能够在一个单独的物理x86机器上运行。这与操作系统级虚拟化技术不同,该技术让所有的实例共享一个内核(所谓操作系统级虚拟化技术就是指容器),即使guest operating system能够在user space不同,例如有同样的内核的Linux distribution。 Type-1,native or bare-metal hypervisors

这些hypervisors直接运行在host的hardware上来控制硬件资源与管理guest operating system。正式这个原因,有时也被称为是bare metal hypervisors。第一种这种类型的hypervisor是IBM在1960年代开发的,包括软件SIMMON和CP/CMS操作系统。现代的类似hypervisor包括 AntsleOS,Microsoft Hyper-V和Xbox One system software,Nutanix AHV,XCP-ng,Oracle VM Server for SPARC,Oracle VM Server for x86,POWER Hypervisor,QNX Hypervisor,VMware ESXi(formerly ESX),Proxmox Virtual Environment, Xen Typer-2 or hosted hypervisors

这些hypervisor直接作为一种计算机程序运行在传统的操作系统上。一个gust operating system直接作为host上的一个进程运行。Typer-2 hypervisor从host operating system中抽象了guest operating system。type-2 hypervisor包括Parallels Desktop for Mac,QEMU,VirtualBox,VMware Player、VMware Workstation。

cell

A unit of information consisting of 32 bits.

由32位组成的信息单位

DTB

Devicetree blob. Compact binary representation of the devicetree

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

effective address

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

由处理器存储访问或分支指令计算的内存地址

physical address

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.

属于客户端程序的引导CPU以外的CPU被认为是次要CPU。

SMP

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

对称多处理。一种计算机结构,其中两个或多个相同的cpu可以共享内存和IO,并在一个操作系统下运行

SoC

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

芯片上的系统。集成一个或多个CPU核心以及许多其他外设的单个计算机芯片

unit address

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.

一个静态CPU处于这样一种状态:它不能干扰其他CPU的正常运行,它的状态也不能被其他运行中的CPU的正常运行所影响,除非通过显式的方法启用或重新启用该静态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.

本章描述了设备节点的逻辑结构,并指定了用于描述设备节点的基本属性集。第3章指定符合 dtspec 的设备所需的某些设备节点。第4章描述了 dtspec 定义的设备绑定——表示特定设备类型或设备类别的要求。第五章描述了设备的内存内编码。

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.

符合 dtspec 的设备树描述了系统中的设备信息,客户机程序不一定能够动态检测到这些信息。例如,PCI 的体系结构允许客户机探测和检测连接的设备,因此可能不需要描述 PCI 设备的设备树节点。但是,如果无法通过探测检测到系统中的 PCI 主机桥接设备,则需要设备节点来描述该设备。

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.1示出了一个简单设备的示例表示,该设备几乎完成到足以引导一个简单操作系统,其中描述了平台类型、 CPU、内存和单个 UART。设备节点在每个节点中显示属性和值。

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.

名称的单元地址组件特定于节点所在的总线类型。它由表2.1中字符集中的一个或多个ASCII字符组成。单元地址必须匹配节点的reg属性中指定的第一个地址。如果节点没有reg属性,则必须省略@unit-address,并且仅使用节点名将该节点与树中同一级别的其他节点区分开来。特定总线的绑定可以为reg格式和单元地址指定附加的、更具体的要求。

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

根节点没有节点名或单元地址。它由一个正斜杠(/)标识。

name

  • 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:

节点的名称应该通用,反映设备的功能,而不是其精确的编程模型,比如:

  • adc/accelerometer/bluetooth/bus/…

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在内存中表示为:
address: 11
address+1: 22
address+3:33
address+4:44
<u64> 代表一个64位的big-endian格式的整数。由两个值组成,其中第一个值包含整数的最高有效位,第2个值为最低有效位
<string> 字符串是可打印的,并且是空尾的。例如:字符串 “hello “将被代表为:
address: 68 ‘h’
address+1: 65 ‘e’
address+2: 6c ‘l’
address+3: 6c ‘l’
address+4: 6f ‘o’
address+5: 00 ‘\0’
<prop-encoded-array> 格式是特定于该属性的。请参阅属性定义
<phandle> 一个值。phandle值是一种引用devicetree中另一个节点的方式。任何可以被引 用的节点都定义了一个具有唯一值的phandle属性。这个数字被用于具有 phandle值类型的属性的值
<stringlist> 一个串联起来的值的列表,字符串列表:"hello", "wolrd" 在内存中表示为:
address: 68 'h'
address+1: 65 'e'
... ...
address+5: 00 '\0'
address+6: 77 'w'
... ...
address+10 64 'd'
address+11: 00 '\0'

大端:大地址在尾巴上 0x1234: [address+1] = 0x34 小端:小地址在尾巴上 0x1234: [address] = 0x34

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部分是针对设备的,表示检测到的错误情况。

2.3.5 #address-cells 和 #size-cells

  • 数值类型:<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 { 
      #address-cell = <1>; // 地址占1个u32
      #size-cells = <1>;   // 长度占1个u32
    
      serial@4600 {
        compatible = "ns16550";
        reg = <0x4600 0x100>;
        clock-frequency: <0>;
        interrupts = <0xA 0x8>;
        interrupt-parent = <&ipic>;
      };
    };
    
    • 在这个例子中,soc节点的#address-cells和#size-cells属性都被设置为1。这个设置指定了需要一个单元格u32来表示地址,需要一个单元格u32来表示作为这个节点的子节点的大小。
    • 串行设备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值中的长度字段应被省略。
  • 例子
    • 假设一个片上系统的设备有两个寄存器块,一个是位于SOC中偏移量0x3000的32字节块,一个是位于偏移量0xFE00的256字节块。寄存器属性将被编码如下(假设#address-cell和#size-cells值为1)

      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";
      #address-cells = <1>;
      #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属性的值的格式是一个任意数量的三联体(child-bus-address, parent-bus-address, length)。指定的每个三联体描述了一个连续的DMA地址范围。
      • 子总线地址是子总线地址空间内的一个物理地址。代表该地址的单元格数量取决于总线,可以从该节点(dma-ranges属性出现的节点)的#address-cell中确定
      • 父总线地址是父总线地址空间内的一个物理地址。表示父级地址的单元格数量与总线有关,可以从定 义父级地址空间的节点的#address-cell属性中确定。
      • 长度指定了子代地址空间中范围的大小。表示大小的单元格的数量可以从这个节点(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.

中断源到中断控制器的物理连接在设备树中用中断-父属性表示。表示中断生成设备的节点包含一个中断-父属性,该属性具有一个 phandle 值,该值指向设备的中断路由所指向的设备,通常是一个中断控制器。如果一个中断生成设备没有中断父属性,则假定它的中断-父属性是它的设备树父节点。

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.

每个中断生成设备包含一个 interrupts 中断属性,其值描述该设备的一个或多个中断源。每个源都用称为interrupt specifier中断指定符的信息表示。中断指定符的格式和意义是中断域特定的,也就是说,它依赖于中断域根节点上的属性。中断域的根使用 #interrupt-cells 属性来定义编码中断指定符所需的 <u32> 值的数量。例如,对于一个 Open PIC 中断控制器,一个中断指示器需要两个32位的值,并且由一个中断号和中断的级别/感知信息组成。

中断指定符表示的是中断生成设备中的中断源,中断指定符的长度由中断域的#interrupt-cells来指定

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)一个中断控制器或(2)一个中断连接。

  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.

当对中断树的遍历到达一个没有interrupts属性的中断控制器节点,从而没有明确的中断父节点时,中断树的根被确定。

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.

请看图2.3,这是一个以图形表示的设备树的例子,其中显示了中断父关系。它既显示了设备树的自然结构,也显示了每个节点在逻辑中断树中的位置。

devtree

  • 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.

中断枢纽节点应具有 #interrupt-cells 中断单元属性。

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.

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

    • child unit address 子单元地址

      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.

      被映射的子节点的单元地址。需要32位单元格的数量由子节点所在的总线节点的 #address-cells 属性描述。

    • 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> 值,指向子域映射到的中断父级。

    • parent unit address 父单元地址

      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.

      中断父级域中的单元地址。指定此地址所需的32位单元的数量由中断父字段指向的节点的 #address-cells 属性描述。

    • 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).

通过将单元地址/中断指定符对与中断映射中的子组件相匹配,在中断映射表上进行查找。因为单元中断指定符中的一些字段可能不相关,所以在进行查找之前会应用一个屏蔽。这个掩码是在中断映射掩码属性中定义的(参见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.

子节点和中断父节点都需要定义 #address-cell#interrupt-cell 属性。如果不需要单位地址组件,#address-cells应明确定义为零。

2.4.3.2. interrupt-map-mask 中断-映射-掩码

  • 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.

下面显示了一个带有PCI总线控制器的devicetree和中断映射的片段,它描述两个PCI插槽(IDSEL 0x11,0x12)的中断路由。 插槽1和2的INTA、INTB、INTC和INTD引脚被连接到开放式PIC中断控制器。

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

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

   pci {
      #interrupt-cells = <1>; // 子中断指定符长度
      #size-cells = <2>;
      #address-cells = <3>;
      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.

一个开放 PIC 中断控制器被表示为具有interrupt-controller属性的中断控制器。

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.

在本例中,interrupt-map-mask 属性的值为 <0xf800 0 0 7> 。在中断映射表中执行查找之前,这个掩码应用于子单元中断指定符

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:

为了查找 IDSEL 0x12(slot 2)的 INTB 的 open-pic 中断功能码0x3,将执行以下步骤:

  • 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.

一个枢纽节点应该有一个 *#-cells* 属性,其中 `` 是一些指定符空间,如‘ gpio’、‘ clock’、‘ reset’等。

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)).

    通过在映射表中对子说明符进行说明符匹配,可以在映射表上执行查找。由于说明符中的某些字段可能不相关或需要修改,因此在执行查找之前应用掩码。这个掩码在 *-map-mask* 属性中定义(请参阅第2.5.1.2节)。

    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.

下面显示了一个具有两个 GPIO 控制器和一个描述通过板上连接器到设备的两个控制器上的几个 GPIO 的 GPIO 路由的示例说明符映射的设备树片段的表示。扩展设备节点位于连接器节点的一侧,具有两个 GPIO 控制器的 SoC 位于连接器的另一侧。

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-mask = <0xf 0x0>;
        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.

在本例中,gpio-map-mask 属性的值为 < 0xf 0 > 。在 gpio-map 表中执行查找之前,将此掩码应用于子单元说明符。类似地,gpio-map-pass-thru 属性的值为 < 0x0 0x1 > 。当子单元说明符映射到父单元说明符时,将应用此掩码。此掩码中的任何位都会从父单元说明符中清除,并从子单元说明符复制到父单元说明符。

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:

要从扩展设备的 reset-gpios 属性中查找连接器的 GPIO 2指定源代码,将执行以下步骤:

  • 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.

下面的部分指定 dtspec 兼容设备中所需的基本设备节点集的要求

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.
指定用于表示根的子元素的 reg 属性中的地址的 < u32 > 单元格的数量。
#size-cells R <u32> Specifies the number of <u32> cells to represent the size in the reg property in children of root.
指定用于表示根的子元素的 reg 属性中的大小的 < u32 > 单元格的数量。
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"
指定此平台与之兼容的平台架构的列表。操作系统可以在选择平台特定的代码时使用此属性。属性值的建议形式如下:”制造商,型号”
例如:compatible = "fsl,mpc8572ds"
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:
指定一个字符串,用于标识系统的形状因子。属性值可以是:"desktop""laptop""convertible""server""tablet""handset""watch""embedded"

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.

所有其他的标准属性(第2.3节)是允许的,但是是可选的

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.

一个设备树可以有一个别名节点(/aliases)来定义一个或多个别名属性。别名节点应位于设备树的根,并具有节点名称/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.

别名应该是来自以下字符集的1到31个字符的小写文本字符串。

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.

给定别名 serial0,客户机程序可以查看/aliases节点并确定别名指向设备路径/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.

所有设备树都要求一个内存设备节点,并描述系统的物理内存布局。如果系统具有多个内存范围,则可以创建多个内存节点,或者可以在单个内存节点的 reg 属性中指定这些范围。

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

节点名称的单元名称组件(见第2.2.1节)应该是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:

客户端程序可以使用它选择的任何存储属性来访问没有被任何内存预留所覆盖的内存(见第5.3节)。然而,在改变用于访问真实页面的存储属性之前,客户程序要负责执行架构和实现所要求的操作,可能包括从缓存中刷新真实页面。引导程序负责确保在不采取任何与改变存储属性相关的行动的情况下,客户程序可以安全地访问所有的内存(包括被内存保留覆盖的内存),如 WIMG = 0b001x。这就是:

  • 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.

如果支持 VLE 存储属性,则使用 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).
是一个由(有效地址、物理地址、大小)三要素组成的道具编码数组。有效地址和物理地址应分别为64位(<u64>值),大小为32位(<u32>值)。
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.

当通过[ UEFI ]引导时,系统内存映射通过[ UEFI ]7.2中定义的 GetMemoryMap() UEFI 引导时间服务获得,如果存在,OS 必须忽略任何/内存节点。

3.4.2 /memory Examples 例子

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

给定一个具有以下物理内存布局的64位 Power 系统:

  • 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>.

假设 # address-cells = < 2 > 和 # size-cells = < 2 > ,内存节点可以定义如下。

Example #1

例子 # 1

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

Example #2

例子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.

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

注意:所有其他标准属性(第2.3节)都是允许的,但也是可选择的

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.

可能会遇到旧版本的devicetrees,其中包含一个被废弃的stdout-path属性形式,称为linux,stdout-path。为了兼容,如果不存在stdout-path属性,客户程序可能希望支持linux,stdout-path。这两个属性的含义和用途是相同的。

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.

所有设备树都需要一个/cpus节点。它并不代表系统中的真实设备,而是作为子cpu节点的容器,代表系统的CPU。

  • 属性名
    • #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.

一个cpu节点代表一个硬件执行块,它具有足够的独立性,能够运行一个操作系统而不干扰其他可能运行其他操作系统的CPU。

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).

共享一个MMU的硬件线程一般会在一个cpu节点下表示。如果设计了其他更复杂的CPU拓扑结构,那么CPU的绑定必须描述该拓扑结构(例如,不共享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.

在不同cpu节点中具有相同值的属性可以放在/cpus节点中。客户端程序必须首先检查一个特定的cpu节点,但如果没有找到预期的属性,那么它应该查看父/cpus节点。这样做的结果是,在所有的CPU上都是相同的属性的表述不那么冗长。

The node name for every CPU node should be cpu.

每个CPU节点的节点名称应该是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.

下表描述了cpu节点的一般属性。表3.6中描述的一些属性是选择的标准属性,有具体的适用细节。

  • 属性名
    • 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.

        如果一个CPU支持一个以上的线程(即多个执行流),reg属性是一个数组,每个线程有一个元素。/cpus节点上的#address-cells指定了数组的每个元素需要多少个单元。软件可以通过用reg的大小除以父节点的#address-cell来确定线程的数量。

      • 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.

        cpu-release-addr属性对于enable-method道具值为 “spin-table “的cpu节点是必需的。该值指定了将二级CPU从其自旋循环中释放出来的自旋表项的物理地址。

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.

保留内存被指定为/reserved-memory节点下的节点。操作系统应该排除正常使用的保留内存。可以创建描述特定保留内存区域的子节点(从正常使用中排除)。这样的存储区域通常是为各种设备驱动程序的特殊用途而设计的。

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.
指定用于表示根的子元素的 reg 属性中的地址的 < u32 > 单元格的数量。
#size-cells R <u32> Specifies the number of <u32> cells to represent the size in the reg property in children of root.
指定用于表示根的子元素的 reg 属性中的大小的 < u32 > 单元格的数量。
ranges R <prop encoded array> This property represents the mapping between parent address to child address spaces (see Section 2.3.8, ranges).
此属性表示父地址到子地址空间之间的映射(请参阅第2.3.8节,范围)。

#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.

保留内存节点的每个子节点指定一个或多个保留内存区域。每个子节点可以使用 reg 属性来指定特定的保留内存范围,或者使用带有可选约束的 size 属性来请求动态分配的内存块。

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.

按照推荐的通用名称实践,节点名称应该反映节点的用途(即。“framebuffer”或“dma-pool”)。如果节点是一个静态分配,那么单元地址(@<address>)应该附加到名称中。

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.

保留内存节点需要用于静态分配的 reg 属性,或用于动态分配的 size 属性。动态分配可以使用对齐和分配范围属性来约束从哪里分配内存。如果同时存在 reg 和 size,那么该区域将被视为一个静态分配,其中 reg 属性优先,而 size 被忽略。

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.
要为动态分配的区域保留的内存字节大小。此属性的大小基于父节点的 # Size-cells 属性。
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.

所有其他的标准属性(第2.3节)是允许的,但是是可选的。

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.

当通过 UEFI 引导时,静态/保留内存区域还必须列在通过[ UEFI ]7.2中定义的 GetMemoryMap() UEFI 引导时间服务获得的系统内存映射中。保留的内存区域需要包含在 UEFI 内存映射中,以防止 UEFI 应用程序分配内存。

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.

具有无映射属性的保留区域必须列在类型为 ereservedmemorytype 的内存映射中。所有其他保留区域必须以 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.

动态保留内存区域不能列在[ UEFI ]内存映射中,因为它们是在退出固件引导服务之后由操作系统分配的。

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).

这个示例为 Linux 内核定义了3个连续区域: 所有设备驱动程序的一个缺省值(命名为 Linux、 cma 和64mib 大小) ,一个专用于 framebuffer 设备(命名为 framebuffer@78000000,8MiB) ,一个用于多媒体处理(命名为 multimedia@77000000,64MiB)。

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

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

   reserved-memory {
      #address-cells = <1>;
      #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).

绑定可以被定义为其他绑定的扩展。例如,一个新的总线类型可以被定义为简单总线绑定的扩展。在这种情况下,兼容的属性将包含几个字符串来识别每个绑定–从最具体的到最一般的(见2.3.1节,兼容)。

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.

当为设备创建一个新的devicetree表示时,应该创建一个完全描述设备所需属性和值的绑定。这组属性应具有足够的描述性,以便为设备驱动程序提供设备的必要属性。

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.

串行设备类包括各种类型的点对点串行线路设备。串行线设备的例子包括8250 UART、16550 UART、HDLC设备和BISYNC设备。在大多数情况下,与RS-232标准兼容的硬件适合于串行设备类

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.

与美国国家半导体16450/16550 UART(通用异步接收转换器)兼容的串行设备应使用以下属性在devicetree中表示。

属性 用法 值类型 说明
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
指定波特率发生器的输入时钟的频率(Hz)
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.
以字节为单位指定离散的副寄存器之间的距离。各个寄存器的位置是通过以下公式计算的。”寄存器地址”«寄存器移位。如果没有指定,默认值为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
见第2.3.7节。指定一个有效地址,映射到reg属性中指定的第一个物理地址。如果这个设备结点是系统的,则需要这个属性。

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.

网络设备是面向数据包的通信设备。这类设备被认为实现了七层OSI模型的数据链路层(第2层),并使用媒体访问控制(MAC)地址。网络设备的例子包括以太网、FDDI、802.11和令牌环。

4.3.1 Network Class Binding

参见设备树规格文档

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.

基于IEEE 802.3系列LAN标准(统称为以太网)的网络设备可以在devicetree中使用以下属性来表示,除了网络设备类指定的属性外。 本节中列出的属性是对网络设备类中列出的属性的扩充。

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].

本节规定了代表开放PIC兼容中断控制器的要求。开放式PIC中断控制器实现了开放式PIC架构(由AMD和Cyrix联合开发),并在《开放式可编程中断控制器(PIC)寄存器接口规范》第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”.

片上系统处理器可能有一个内部I/O总线,无法探测到设备。总线上的设备可以直接被访问,而不需要额外的配置。这种类型的总线被表示为一个节点,其兼容值为 “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)
此属性表示父级地址到子级地址空间之间的映射(见2.3.8节,范围)。

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中的图(低地址在图的顶部)。

dtb

图5.1: Devicetree .dtb结构

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.

自从该格式的最初定义以来,扁平化的devicetree结构的几个版本已经被定义。头部的字段给出了版本,这样客户程序就可以确定devicetree是否以兼容的格式进行编码。

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.

本文档只描述了格式的第17个版本。兼容DTSpec的启动程序应提供17版或更高版本的devicetree,并应提供向后兼容16版的devicetree。兼容DTSpec的客户程序应接受向后兼容17版的任何版本的devicetree,也可以接受其他版本。

注意:版本是关于devicetree的二进制结构,而不是它的内容

5.2 Header

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格式存储。

Flattened Devicetree Header Fields

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.

为了使内存预留块和结构块中的数据在使用时没有不对齐的内存访问,它们应位于适当对齐的内存地址上。具体来说,内存预留块应与8字节边界对齐,结构块应与4字节边界对齐。

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

此外,devicetree blob作为一个整体可以被重新定位而不破坏子块的对齐。

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.

正如前几节所述,结构块和字符串块应从devicetree blob的开始处有对齐的偏移量。为了保证块的内存对齐,只需要保证devicetree作为一个整体被加载在一个与任何子块的最大对齐的地址上,也就是8字节的边界上。一个符合DTSpec的引导程序在把devicetree blob传递给客户程序之前,应该在这样一个对齐的地址上加载devicetree blob。如果一个DTSpec客户程序在内存中重新定位devicetree blob,它应该只在另一个8字节对齐的地址上这样做。

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.

其他源文件可以从一个DTS文件中包含。包含文件的名称应该以”.dtsi “结尾。包含的文件可以反过来包含其他文件。

/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.

源格式允许将标签附加到设备树中的任何节点或属性值。通过引用一个标签,而不是明确指定一个phandle值或节点的完整路径,可以自动生成phandle和路径引用。标签只在设备树源格式中使用,不被编码到DTB二进制中。

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.

标签的长度应在1到31个字符之间,仅由表6.1中的字符集组成,且不得以数字开头。

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.

属性值可以被定义为32位整数单元的数组、空尾字符串、字节串或这些的组合

  • 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];
      local-mac-address = [000012345678];
      
    • 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

第1版的DTS文件具有整体布局:

/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.

内存保留定义了devicetree blob的内存保留表的条目。它们的形式是:例如,/memreserve/ <address> <length>; 其中<address><length>是64位C风格的整数。

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

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

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

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

zephyr 设备树相关

这是一个设备树的概念性概述以及 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.

有两种类型的设备树输入文件: 设备树源码和设备树绑定。信息来源包含了这个装置本身。绑定描述其内容,包括数据类型。构建系统使用 devicetree 源和绑定来生成一个生成的 c 头文件。生成的头文件的内容是由 devicetree.h API 提取的,您可以使用该 API 从设备树获取信息。

Here is a simplified view of the process:

这里有一个过程的简化视图:

zephyr_dt_build_flow.png

Fig. 20 Devicetree build flow

图20设备树构建流程

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

所有 Zephyr 和应用程序源代码文件都可以包含并使用 devicetree.h。这包括设备驱动程序、应用程序、测试、内核等。

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.

在 devicetree 中定义的一些信息可以通过从 Kconfig 生成的 CONFIG_ 宏获得。这通常是为了向后兼容,因为 Zephyr 使用 Kconfig 的时间比设备树更长,并且仍然在将一些信息从 Kconfig 转换到设备树的过程中。它还允许 Kconfig 覆盖取自设备树的默认值。设备信息是从 Kconfig 通过 Kconfig 函数引用的。请参阅 Devicetree 和 Kconfig 以获得与 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.

顾名思义,设备就是一棵树。这个树的人类可读的文本格式称为 DTS (用于设备树源) ,并在设备树规范中定义。

Here is an example DTS file:

下面是一个 DTS 文件示例:

/dts-v1/;

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

名称中的 单元地址 部分是针对节点所处的总线类型的,单元地址必须与节点的reg属性中指定的第一个地址相匹配。如果节点没有reg属性,则必须省略@unit-address,仅用节点名称来区分

在树中的同一级别的其他节点中的节点。特定总线的绑定可能会对reg的格式和单元地址规定更多、更具体的要求。 在节点名称没有@unit-address的情况下,节点名应该与树中同一级别的任何属性名不同。 根节点没有节点名称或单元地址。它由一个正斜杠(/)来识别

root

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