David Gibson | 3bdd393 | 2008-03-11 10:47:14 +1100 | [diff] [blame] | 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 | |
Anton Staaf | 033089f | 2011-10-11 10:22:29 -0700 | [diff] [blame] | 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. |
David Gibson | 3bdd393 | 2008-03-11 10:47:14 +1100 | [diff] [blame] | 34 | |
Anton Staaf | 033089f | 2011-10-11 10:22:29 -0700 | [diff] [blame] | 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. |
David Gibson | 3bdd393 | 2008-03-11 10:47:14 +1100 | [diff] [blame] | 39 | |
| 40 | e.g. interrupts = <17 0xc>; |
| 41 | |
Anton Staaf | 033089f | 2011-10-11 10:22:29 -0700 | [diff] [blame] | 42 | * A 64-bit value can be represented with two 32-bit elements. |
David Gibson | 3bdd393 | 2008-03-11 10:47:14 +1100 | [diff] [blame] | 43 | |
| 44 | e.g. clock-frequency = <0x00000001 0x00000000>; |
| 45 | |
Anton Staaf | 033089f | 2011-10-11 10:22:29 -0700 | [diff] [blame] | 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 | |
David Gibson | 3bdd393 | 2008-03-11 10:47:14 +1100 | [diff] [blame] | 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 | |
Anton Staaf | 033089f | 2011-10-11 10:22:29 -0700 | [diff] [blame] | 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: |
David Gibson | 3bdd393 | 2008-03-11 10:47:14 +1100 | [diff] [blame] | 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} >; |
Anton Staaf | 033089f | 2011-10-11 10:22:29 -0700 | [diff] [blame] | 77 | References are only permitted in arrays that have an element size of |
| 78 | 32-bits. |
David Gibson | 3bdd393 | 2008-03-11 10:47:14 +1100 | [diff] [blame] | 79 | |
Anton Staaf | 033089f | 2011-10-11 10:22:29 -0700 | [diff] [blame] | 80 | * Outside an array, a reference to another node will be expanded to that |
| 81 | node's full path. |
David Gibson | 3bdd393 | 2008-03-11 10:47:14 +1100 | [diff] [blame] | 82 | e.g. ethernet0 = &EMAC0; |
| 83 | |
| 84 | * Labels may also appear before or after any component of a property |
Anton Staaf | 033089f | 2011-10-11 10:22:29 -0700 | [diff] [blame] | 85 | value, or between elements of an array, or between bytes of a bytestring. |
David Gibson | 3bdd393 | 2008-03-11 10:47:14 +1100 | [diff] [blame] | 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@gibson.dropbear.id.au> |
| 121 | -- Yoder Stuart <stuart.yoder@freescale.com> |
Anton Staaf | 033089f | 2011-10-11 10:22:29 -0700 | [diff] [blame] | 122 | -- Anton Staaf <robotboy@chromium.org> |