Introduction to Device Trees

1 1 IntroductionA Device tree is a tree structure used to describe the physicalhardware in a system. Each node in the tree describes thecharacteristics of the Device being represented. The purpose ofthe Device tree is to describe Device information in a systemthat cannot necessarily be dynamically detected or discoveredby a client program. For example, a PCI host may be able toprobe and detect attached devices ; and so a Device tree nodedescribing PCI devices may not be required. However, adevice node is required to describe the PCI host bridge in thesystem, if that cannot be detected by the advent of the Device tree, the kernel containeddevice specific code.

2 A small change, such as the modificationof an I2C peripheral s address would force a recompilation ofthe kernel image to be boot loader (for example, U-Boot) would load a singlebinary, the kernel image, and execute to Device Trees , several attempts were made to reducecomplexity and pass small amounts of information to thekernel. The boot loader would typically prepare someadditional information and place it in system ram at a locationpointed to by a predefined register. This information wouldcontain some basic information, such as memory size andlocation, and kernel command line information, such as IPaddress.

3 The goal was to allow the kernel to configureFreescale SemiconductorDocument Number: AN5125 Application NoteRev. 0, 09/2015 Introduction to Device Trees 2015 Freescale Semiconductor, 12 Basic Device 34 Memory mapping and 76 Example: Device tree 87 Device tree 98 Device tree 1512 Revision 33hardware based on parsable information about the hardware rather than hard-coded initialization functions (for example,hard-coded IP addresses).With Device Trees , the kernel itself no longer needs specific code for each version of hardware. Instead, the code is located ina separate binary: the Device tree blob.

4 This enables us to target different hardware with the same kernel image by simplychanging the much simpler, and much smaller, Device tree Device tree can be passed to the kernel either through appending it to the kernel image or through the bootloader. Themachine type is now defined in the Device tree itself. The bootloader can dynamically add some information (for example,clock frequencies) to the Device tree and then passes a pointer to the tree, located in system memory, through r2 (for ARM architecture) or r3 (for Power Architecture ). The kernel then unflattens and parses the Device Device treeDevice Trees are well described in the Standard for Embedded Power Architecture Platform Requirements(ePAPR): The ePAPR defines a concept, a Device tree, to describesystem hardware and separate that description from the kernel Device tree is a tree structure with nodes that describe the physical devices in the system that cannot be dynamicallydetected by software.

5 The nodes are organized in a hierarchical parent/child figure is a representation of a simple Device tree, describing the platform type, CPU and memory. Nodes are organizedin a hierarchy as a collection of property and value tokens. Sub-nodes define the relationship of devices within the hierarchy.( I2C devices are children of an I2C controller node.)/model = "fsl, P1010";compatible = "fsl, P1010 RDB";#address-cells = <2>;#size-cells - <2>;CPUsmemoryethernet @ 0xfe001000#address-cells = <1>;#size-cells = <0>;CPU @ 0 Node NameUnit Addressdevice_type = "cpu";reg = <0x0>;next-level-cache = < Property ValueProperty Namephandledevice_type = "memory";Figure 1.

6 High-level Device treeIn Figure 1, we see the definition of a P1010 based system. The compatible keyword specifies the name of the system in theform <manufacturer>, <model>. This may be used by the operating system to make decisions on how to run on Device treeIntroduction to Device Trees , Rev. 0, 09/20152 Freescale Semiconductor, in the tree, we see a node named cpus define one CPU with a unit address of 0. This corresponds to the node s regproperty and indicates that a single CPU is in the tree, the node named Ethernet has a unit-address value of example is intended as a simple example of portions of a Device tree.

7 The following sections delve into more advancedexamples, as well as specifics of the syntax used to define nodes in the Device tree is simply a tree structure of nodes and properties. Properties are key-value pairs and may contain bothproperties and child nodes. The following sections review the basic syntax of the Device tree nodes, as well as parent/childnode namesThe node name is a label used to identify the node. The unit-address component of the node identifies the base address of thebus on which the node sits. This is the primary address used to access the nodes must be uniquely named, but can alternatively be addressed by a unit name, which is used to differentiatenodes with the same name (for example, multiple I2C devices in the same SoC) at the same level.

8 Unit names are made of thenode names, the @ symbol, and a unit address (for example, i2c@3000, i2c@4000, and so on).Multiple definitions of the same node are merged into one by the Device Tree node may contain multiple properties arranged in name = value format. The name consists of a string, while value can bean array of strings, bytes, numbers, or phandles, or a mixture of types. For example, value can be: compatible = "fsl,mpc8610-msi", "fsl,mpic-msi"; reg = <0 0 0x8000000>; interrupt-parent = < NOTEN umbers are always 32-bit big-endian in Device Trees .

9 At times, multiple 32-bit big-endian numbers are used to represent a larger value (for example, 64-bit). phandle (pointer handle) is a 32-bit value associated with a node that is used to uniquely identify that node so that the nodecan be reference from a property in another node. More simply put, it is a property in one node that contains a pointer toanother node. A phandle is created either by the Device tree compiler or U-Boot for each the following example, <&label> is converted to the phandle for the labeled node by the @address { <key> = < };SyntaxIntroduction to Device Trees , Rev.

10 0, 09/2015 Freescale Semiconductor, : name@adresss {} It is most commonly used for interrupts. In Listing 1 on page 7, interrupt-parent is assigned a phandle to the node withthe label aliases node is an index of other nodes. The properties of the node are paths within the Device tree, not { ethernet0 = ethernet1 = ethernet2 = serial0 = serial1 = pci0 = }; 4 Memory mapping and addressingAddresses are encoded using the following three properties: reg #address-cells #size-cellsEach addressable Device has a reg property, which lists the address ranges used by the Device through one or more 32-bitintegers, called cells.