freebsd-nq/contrib/dtc/Documentation/dts-format.txt
Rafal Jaworowski 21fdc27a05 Merge DTC-d75b33af.
This is a split merge because of non-uniform licensing of the DTC package
contents and the way these components will be used in the FreeBSD environment.

The original DTC package is composed of the following two major pieces:

1. sys/contrib/libfdt (BSD [dual] license)
2. contrib/dtc (GPLv2)

The libfdt component is going to be shared in all aspects of the environment:
- /boot/loader
- kernel
- dtc (the device tree compiler proper, userspace tool)
2010-02-28 21:57:35 +00:00

111 lines
3.5 KiB
Plaintext

Device Tree Source Format (version 1)
=====================================
The Device Tree Source (DTS) format is a textual representation of a
device tree in a form that can be processed by dtc into a binary
device tree in the form expected by the kernel. The description below
is not a formal syntax definition of DTS, but describes the basic
constructs used to represent device trees.
Node and property definitions
-----------------------------
Device tree nodes are defined with a node name and unit address with
braces marking the start and end of the node definition. They may be
preceded by a label.
[label:] node-name[@unit-address] {
[properties definitions]
[child nodes]
}
Nodes may contain property definitions and/or child node
definitions. If both are present, properties must come before child
nodes.
Property definitions are name value pairs in the form:
[label:] property-name = value;
except for properties with empty (zero length) value which have the
form:
[label:] property-name;
Property values may be defined as an array of 32-bit integer cells, as
NUL-terminated strings, as bytestrings or a combination of these.
* Arrays of cells are represented by angle brackets surrounding a
space separated list of C-style integers
e.g. interrupts = <17 0xc>;
* A 64-bit value is represented with two 32-bit cells.
e.g. clock-frequency = <0x00000001 0x00000000>;
* A NUL-terminated string value is represented using double quotes
(the property value is considered to include the terminating NUL
character).
e.g. compatible = "simple-bus";
* A bytestring is enclosed in square brackets [] with each byte
represented by two hexadecimal digits. Spaces between each byte are
optional.
e.g. local-mac-address = [00 00 12 34 56 78]; or equivalently
local-mac-address = [000012345678];
* Values may have several comma-separated components, which are
concatenated together.
e.g. compatible = "ns16550", "ns8250";
example = <0xf00f0000 19>, "a strange property format";
* In a cell array a reference to another node will be expanded to that
node's phandle. References may by '&' followed by a node's label:
e.g. interrupt-parent = < &mpic >;
or they may be '&' followed by a node's full path in braces:
e.g. interrupt-parent = < &{/soc/interrupt-controller@40000} >;
* Outside a cell array, a reference to another node will be expanded
to that node's full path.
e.g. ethernet0 = &EMAC0;
* Labels may also appear before or after any component of a property
value, or between cells of a cell array, or between bytes of a
bytestring.
e.g. reg = reglabel: <0 sizelabel: 0x1000000>;
e.g. prop = [ab cd ef byte4: 00 ff fe];
e.g. str = start: "string value" end: ;
File layout
-----------
Version 1 DTS files have the overall layout:
/dts-v1/;
[memory reservations]
/ {
[property definitions]
[child nodes]
};
* The "/dts-v1/;" must be present to identify the file as a version 1
DTS (dts files without this tag will be treated by dtc as being in
the obsolete "version 0", which uses a different format for integers
amongst other small but incompatible changes).
* Memory reservations define an entry for the device tree blob's
memory reservation table. They have the form:
e.g. /memreserve/ <address> <length>;
Where <address> and <length> are 64-bit C-style integers.
* The / { ... }; section defines the root node of the device tree.
* C style (/* ... */) and C++ style (// ...) comments are supported.
-- David Gibson <david@gibson.dropbear.id.au>
-- Yoder Stuart <stuart.yoder@freescale.com>