qemu/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>