← Back to branch summary

~pmdj/ubuntu/trusty/qemu/2.9+applesmc+fadtv3

« back to all changes in this revision

Viewing changes to dtc/Documentation/dts-format.txt

  • Committer: Phil Dennis-Jordan
  • Date: 2017-07-21 08:03:43 UTC
  • mfrom: (1.1.1)
  • Revision ID: phil@philjordan.eu-20170721080343-2yr2vdj7713czahv
New upstream release 2.9.0.

Show diffs side-by-side

added added

removed removed

Lines of Context:
dtc/Documentation/dts-format.txt
 
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@gibson.dropbear.id.au>
 
121
        -- Yoder Stuart <stuart.yoder@freescale.com>
 
122
        -- Anton Staaf <robotboy@chromium.org>