1 Device Tree Source Format (version 1) 2 ===================================== 3 4 The Device Tree Source (DTS) format is a textual representation of a 5 device tree in a form that can be processed by dtc into a binary 6 device tree in the form expected by the kernel. The description below 7 is not a formal syntax definition of DTS, but describes the basic 8 constructs used to represent device trees. 9 10 Node and property definitions 11 ----------------------------- 12 13 Device tree nodes are defined with a node name and unit address with 14 braces marking the start and end of the node definition. They may be 15 preceded by a label. 16 17 [label:] node-name[@unit-address] { 18 [properties definitions] 19 [child nodes] 20 } 21 22 Nodes may contain property definitions and/or child node 23 definitions. If both are present, properties must come before child 24 nodes. 25 26 Property definitions are name value pairs in the form: 27 [label:] property-name = value; 28 except for properties with empty (zero length) value which have the 29 form: 30 [label:] property-name; 31 32 Property values may be defined as an array of 8, 16, 32, or 64-bit integer 33 elements, as NUL-terminated strings, as bytestrings or a combination of these. 34 35 * Arrays are represented by angle brackets surrounding a space separated list 36 of C-style integers or character literals. Array elements default to 32-bits 37 in size. An array of 32-bit elements is also known as a cell list or a list 38 of cells. A cell being an unsigned 32-bit integer. 39 40 e.g. interrupts = <17 0xc>; 41 42 * A 64-bit value can be represented with two 32-bit elements. 43 44 e.g. clock-frequency = <0x00000001 0x00000000>; 45 46 * The storage size of an element can be changed using the /bits/ prefix. The 47 /bits/ prefix allows for the creation of 8, 16, 32, and 64-bit elements. 48 The resulting array will not be padded to a multiple of the default 32-bit 49 element size. 50 51 e.g. interrupts = /bits/ 8 <17 0xc>; 52 e.g. clock-frequency = /bits/ 64 <0x0000000100000000>; 53 54 * A NUL-terminated string value is represented using double quotes 55 (the property value is considered to include the terminating NUL 56 character). 57 58 e.g. compatible = "simple-bus"; 59 60 * A bytestring is enclosed in square brackets [] with each byte 61 represented by two hexadecimal digits. Spaces between each byte are 62 optional. 63 64 e.g. local-mac-address = [00 00 12 34 56 78]; or equivalently 65 local-mac-address = [000012345678]; 66 67 * Values may have several comma-separated components, which are 68 concatenated together. 69 e.g. compatible = "ns16550", "ns8250"; 70 example = <0xf00f0000 19>, "a strange property format"; 71 72 * In an array a reference to another node will be expanded to that node's 73 phandle. References may by '&' followed by a node's label: 74 e.g. interrupt-parent = < &mpic >; 75 or they may be '&' followed by a node's full path in braces: 76 e.g. interrupt-parent = < &{/soc/interrupt-controller@40000} >; 77 References are only permitted in arrays that have an element size of 78 32-bits. 79 80 * Outside an array, a reference to another node will be expanded to that 81 node's full path. 82 e.g. ethernet0 = &EMAC0; 83 84 * Labels may also appear before or after any component of a property 85 value, or between elements of an array, or between bytes of a bytestring. 86 e.g. reg = reglabel: <0 sizelabel: 0x1000000>; 87 e.g. prop = [ab cd ef byte4: 00 ff fe]; 88 e.g. str = start: "string value" end: ; 89 90 91 File layout 92 ----------- 93 94 Version 1 DTS files have the overall layout: 95 /dts-v1/; 96 97 [memory reservations] 98 99 / { 100 [property definitions] 101 [child nodes] 102 }; 103 104 * The "/dts-v1/;" must be present to identify the file as a version 1 105 DTS (dts files without this tag will be treated by dtc as being in 106 the obsolete "version 0", which uses a different format for integers 107 amongst other small but incompatible changes). 108 109 * Memory reservations define an entry for the device tree blob's 110 memory reservation table. They have the form: 111 e.g. /memreserve/ <address> <length>; 112 Where <address> and <length> are 64-bit C-style integers. 113 114 * The / { ... }; section defines the root node of the device tree. 115 116 * C style (/* ... */) and C++ style (// ...) comments are supported. 117 118 119 120 -- David Gibson <david (a] gibson.dropbear.id.au> 121 -- Yoder Stuart <stuart.yoder (a] freescale.com> 122 -- Anton Staaf <robotboy (a] chromium.org> 123
