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 32-bit integer cells, as

    33 NUL-terminated strings, as bytestrings or a combination of these.

    34 

    35 * Arrays of cells are represented by angle brackets surrounding a

    36   space separated list of C-style integers

    37 

    38 	e.g. interrupts = <17 0xc>;

    39 

    40 * A 64-bit value is represented with two 32-bit cells.

    41 

    42 	e.g. clock-frequency = <0x00000001 0x00000000>;

    43 

    44 * A NUL-terminated string value is represented using double quotes

    45   (the property value is considered to include the terminating NUL

    46   character).

    47 

    48 	e.g. compatible = "simple-bus";

    49 

    50 * A bytestring is enclosed in square brackets [] with each byte

    51   represented by two hexadecimal digits.  Spaces between each byte are

    52   optional.

    53 

    54 	e.g. local-mac-address = [00 00 12 34 56 78]; or equivalently

    55 	     local-mac-address = [000012345678];

    56 

    57 * Values may have several comma-separated components, which are

    58   concatenated together.

    59 	e.g. compatible = "ns16550", "ns8250";

    60 	     example = <0xf00f0000 19>, "a strange property format";

    61 

    62 * In a cell array a reference to another node will be expanded to that

    63   node's phandle.  References may by '&' followed by a node's label:

    64 	e.g. interrupt-parent = < &mpic >;

    65   or they may be '&' followed by a node's full path in braces:

    66 	e.g. interrupt-parent = < &{/soc/interrupt-controller@40000} >;

    67 

    68 * Outside a cell array, a reference to another node will be expanded

    69   to that node's full path.

    70 	e.g. ethernet0 = &EMAC0;

    71 

    72 * Labels may also appear before or after any component of a property

    73   value, or between cells of a cell array, or between bytes of a

    74   bytestring.

    75 	e.g. reg = reglabel: <0 sizelabel: 0x1000000>;

    76 	e.g. prop = [ab cd ef byte4: 00 ff fe];

    77 	e.g. str = start: "string value" end: ;

    78 

    79 

    80 File layout

    81 -----------

    82 

    83 Version 1 DTS files have the overall layout:

    84 	/dts-v1/;

    85 

    86 	[memory reservations]

    87 

    88 	/ {

    89 		[property definitions]

    90 		[child nodes]

    91 	};

    92 

    93 * The "/dts-v1/;" must be present to identify the file as a version 1

    94   DTS (dts files without this tag will be treated by dtc as being in

    95   the obsolete "version 0", which uses a different format for integers

    96   amongst other small but incompatible changes).

    97 

    98 * Memory reservations define an entry for the device tree blob's

    99   memory reservation table.  They have the form:

   100 	e.g. /memreserve/ <address> <length>;

   101   Where <address> and <length> are 64-bit C-style integers.

   102 

   103 * The / { ... }; section defines the root node of the device tree.

   104 

   105 * C style (/* ... */) and C++ style (// ...) comments are supported.

   106 

   107 

   108 

   109 	-- David Gibson <david@gibson.dropbear.id.au>

   110 	-- Yoder Stuart <stuart.yoder@freescale.com>