1Device Tree Source Format (version 1)
2=====================================
3
4The Device Tree Source (DTS) format is a textual representation of a
5device tree in a form that can be processed by dtc into a binary
6device tree in the form expected by the kernel.  The description below
7is not a formal syntax definition of DTS, but describes the basic
8constructs used to represent device trees.
9
10Node and property definitions
11-----------------------------
12
13Device tree nodes are defined with a node name and unit address with
14braces marking the start and end of the node definition.  They may be
15preceded by a label.
16
17	[label:] node-name[@unit-address] {
18		[properties definitions]
19		[child nodes]
20	}
21
22Nodes may contain property definitions and/or child node
23definitions. If both are present, properties must come before child
24nodes.
25
26Property definitions are name value pairs in the form:
27	[label:] property-name = value;
28except for properties with empty (zero length) value which have the
29form:
30	[label:] property-name;
31
32Property values may be defined as an array of 8, 16, 32, or 64-bit integer
33elements, 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
91File layout
92-----------
93
94Version 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>
122	-- Anton Staaf <robotboy@chromium.org>
123