1
Device Tree Compiler Manual
2
===========================
4
I - "dtc", the device tree compiler
11
4.3) Labels and References
13
II - The DT block format
15
2) Device tree generalities
16
3) Device tree "structure" block
17
4) Device tree "strings" block
23
I - "dtc", the device tree compiler
24
===================================
28
Source code for the Device Tree Compiler can be found at jdl.com.
29
The gitweb interface is:
31
http://www.jdl.com/git_repos/
33
The repository is here:
35
git://www.jdl.com/software/dtc.git
36
http://www.jdl.com/software/dtc.git
38
Tarballs of the 1.0.0 and latest releases are here:
40
http://www.jdl.com/software/dtc-1.0.0.tgz
41
http://www.jdl.com/software/dtc-latest.tgz
46
The Device Tree Compiler, dtc, takes as input a device-tree in
47
a given format and outputs a device-tree in another format.
48
Typically, the input format is "dts", a human readable source
49
format, and creates a "dtb", or binary format as output.
51
The currently supported Input Formats are:
53
- "dtb": "blob" format. A flattened device-tree block with
54
header in one binary blob.
56
- "dts": "source" format. A text file containing a "source"
59
- "fs" format. A representation equivalent to the output of
60
/proc/device-tree where nodes are directories and
63
The currently supported Output Formats are:
65
- "dtb": "blob" format
67
- "dts": "source" format
69
- "asm": assembly language file. A file that can be sourced
70
by gas to generate a device-tree "blob". That file can
71
then simply be added to your Makefile. Additionally, the
72
assembly file exports some symbols that can be used.
77
The syntax of the dtc command line is:
79
dtc [options] [<input_filename>]
84
The name of the input source file. If no <input_filename>
85
or "-" is given, stdin is used.
88
Set the physical boot cpu.
91
Force. Try to produce output even if the input tree has errors.
94
Emit a brief usage and help message.
97
The source input format, as listed above.
100
The name of the generated output file. Use "-" for stdout.
103
The generated output format, as listed above.
106
Quiet: -q suppress warnings, -qq errors, -qqq all
109
Make space for <number> reserve map entries
110
Relevant for dtb and asm output only.
113
Ensure the blob at least <bytes> long, adding additional
117
Print DTC version and exit.
120
Generate output conforming to the given <output_version>.
121
By default the most recent version is generated.
122
Relevant for dtb and asm output only.
125
The <output_version> defines what version of the "blob" format will be
126
generated. Supported versions are 1, 2, 3, 16 and 17. The default is
127
always the most recent version and is likely the highest number.
129
Additionally, dtc performs various sanity checks on the tree.
132
4) Device Tree Source file
136
Here is a very rough overview of the layout of a DTS source file:
139
sourcefile: list_of_memreserve devicetree
141
memreserve: label 'memreserve' ADDR ADDR ';'
142
| label 'memreserve' ADDR '-' ADDR ';'
144
devicetree: '/' nodedef
146
nodedef: '{' list_of_property list_of_subnode '}' ';'
148
property: label PROPNAME '=' propdata ';'
151
| '<' list_of_cells '>'
152
| '[' list_of_bytes ']'
154
subnode: label nodename nodedef
156
That structure forms a hierarchical layout of nodes and properties
157
rooted at an initial node as:
162
Both classic C style and C++ style comments are supported.
164
Source files may be directly included using the syntax:
171
Properties are named, possibly labeled, values. Each value
174
- A null-teminated C-like string,
175
- A numeric value fitting in 32 bits,
176
- A list of 32-bit values
179
Here are some example property definitions:
181
- A property containing a 0 terminated string
183
property1 = "string_value";
185
- A property containing a numerical 32-bit hexadecimal value
187
property2 = <1234abcd>;
189
- A property containing 3 numerical 32-bit hexadecimal values
191
property3 = <12345678 12345678 deadbeef>;
193
- A property whose content is an arbitrary array of bytes
195
property4 = [0a 0b 0c 0d de ea ad be ef];
198
Node may contain sub-nodes to obtain a hierarchical structure.
201
- A child node named "childnode" whose unit name is
202
"childnode at address". It it turn has a string property
206
childprop = "hello\n";
210
By default, all numeric values are hexadecimal. Alternate bases
211
may be specified using a prefix "d#" for decimal, "b#" for binary,
214
Strings support common escape sequences from C: "\n", "\t", "\r",
215
"\(octal value)", "\x(hex value)".
218
4.3) Labels and References
220
Labels may be applied to nodes or properties. Labels appear
221
before a node name, and are referenced using an ampersand: &label.
222
Absolute node path names are also allowed in node references.
224
In this exmaple, a node is labled "mpic" and then referenced:
226
mpic: interrupt-controller@40000 {
231
interrupt-parent = <&mpic>;
235
And used in properties, lables may appear before or after any value:
238
prop: string = data: "mystring\n" data_end: ;
244
II - The DT block format
245
========================
247
This chapter defines the format of the flattened device-tree
248
passed to the kernel. The actual content of the device tree
249
are described in the kernel documentation in the file
251
linux-2.6/Documentation/powerpc/booting-without-of.txt
253
You can find example of code manipulating that format within
254
the kernel. For example, the file:
256
including arch/powerpc/kernel/prom_init.c
258
will generate a flattened device-tree from the Open Firmware
259
representation. Other utilities such as fs2dt, which is part of
260
the kexec tools, will generate one from a filesystem representation.
261
Some bootloaders such as U-Boot provide a bit more support by
262
using the libfdt code.
264
For booting the kernel, the device tree block has to be in main memory.
265
It has to be accessible in both real mode and virtual mode with no
266
mapping other than main memory. If you are writing a simple flash
267
bootloader, it should copy the block to RAM before passing it to
274
The kernel is entered with r3 pointing to an area of memory that is
275
roughly described in include/asm-powerpc/prom.h by the structure
278
struct boot_param_header {
279
u32 magic; /* magic word OF_DT_HEADER */
280
u32 totalsize; /* total size of DT block */
281
u32 off_dt_struct; /* offset to structure */
282
u32 off_dt_strings; /* offset to strings */
283
u32 off_mem_rsvmap; /* offset to memory reserve map */
284
u32 version; /* format version */
285
u32 last_comp_version; /* last compatible version */
287
/* version 2 fields below */
288
u32 boot_cpuid_phys; /* Which physical CPU id we're
290
/* version 3 fields below */
291
u32 size_dt_strings; /* size of the strings block */
293
/* version 17 fields below */
294
u32 size_dt_struct; /* size of the DT structure block */
297
Along with the constants:
299
/* Definitions used by the flattened device tree */
300
#define OF_DT_HEADER 0xd00dfeed /* 4: version,
302
#define OF_DT_BEGIN_NODE 0x1 /* Start node: full name
304
#define OF_DT_END_NODE 0x2 /* End node */
305
#define OF_DT_PROP 0x3 /* Property: name off,
307
#define OF_DT_END 0x9
309
All values in this header are in big endian format, the various
310
fields in this header are defined more precisely below. All "offset"
311
values are in bytes from the start of the header; that is from the
316
This is a magic value that "marks" the beginning of the
317
device-tree block header. It contains the value 0xd00dfeed and is
318
defined by the constant OF_DT_HEADER
322
This is the total size of the DT block including the header. The
323
"DT" block should enclose all data structures defined in this
324
chapter (who are pointed to by offsets in this header). That is,
325
the device-tree structure, strings, and the memory reserve map.
329
This is an offset from the beginning of the header to the start
330
of the "structure" part the device tree. (see 2) device tree)
334
This is an offset from the beginning of the header to the start
335
of the "strings" part of the device-tree
339
This is an offset from the beginning of the header to the start
340
of the reserved memory map. This map is a list of pairs of 64-
341
bit integers. Each pair is a physical address and a size. The
342
list is terminated by an entry of size 0. This map provides the
343
kernel with a list of physical memory areas that are "reserved"
344
and thus not to be used for memory allocations, especially during
345
early initialization. The kernel needs to allocate memory during
346
boot for things like un-flattening the device-tree, allocating an
347
MMU hash table, etc... Those allocations must be done in such a
348
way to avoid overriding critical things like, on Open Firmware
349
capable machines, the RTAS instance, or on some pSeries, the TCE
350
tables used for the iommu. Typically, the reserve map should
351
contain _at least_ this DT block itself (header,total_size). If
352
you are passing an initrd to the kernel, you should reserve it as
353
well. You do not need to reserve the kernel image itself. The map
354
should be 64-bit aligned.
358
This is the version of this structure. Version 1 stops
359
here. Version 2 adds an additional field boot_cpuid_phys.
360
Version 3 adds the size of the strings block, allowing the kernel
361
to reallocate it easily at boot and free up the unused flattened
362
structure after expansion. Version 16 introduces a new more
363
"compact" format for the tree itself that is however not backward
364
compatible. Version 17 adds an additional field, size_dt_struct,
365
allowing it to be reallocated or moved more easily (this is
366
particularly useful for bootloaders which need to make
367
adjustments to a device tree based on probed information). You
368
should always generate a structure of the highest version defined
369
at the time of your implementation. Currently that is version 17,
370
unless you explicitly aim at being backward compatible.
374
Last compatible version. This indicates down to what version of
375
the DT block you are backward compatible. For example, version 2
376
is backward compatible with version 1 (that is, a kernel build
377
for version 1 will be able to boot with a version 2 format). You
378
should put a 1 in this field if you generate a device tree of
379
version 1 to 3, or 16 if you generate a tree of version 16 or 17
380
using the new unit name format.
384
This field only exist on version 2 headers. It indicate which
385
physical CPU ID is calling the kernel entry point. This is used,
386
among others, by kexec. If you are on an SMP system, this value
387
should match the content of the "reg" property of the CPU node in
388
the device-tree corresponding to the CPU calling the kernel entry
389
point (see further chapters for more informations on the required
390
device-tree contents)
394
This field only exists on version 3 and later headers. It
395
gives the size of the "strings" section of the device tree (which
396
starts at the offset given by off_dt_strings).
400
This field only exists on version 17 and later headers. It gives
401
the size of the "structure" section of the device tree (which
402
starts at the offset given by off_dt_struct).
404
So the typical layout of a DT block (though the various parts don't
405
need to be in that order) looks like this (addresses go from top to
408
------------------------------
409
r3 -> | struct boot_param_header |
410
------------------------------
411
| (alignment gap) (*) |
412
------------------------------
413
| memory reserve map |
414
------------------------------
416
------------------------------
418
| device-tree structure |
420
------------------------------
422
------------------------------
424
| device-tree strings |
426
-----> ------------------------------
431
(*) The alignment gaps are not necessarily present; their presence
432
and size are dependent on the various alignment requirements of
433
the individual data blocks.
436
2) Device tree generalities
437
---------------------------
439
This device-tree itself is separated in two different blocks, a
440
structure block and a strings block. Both need to be aligned to a 4
443
First, let's quickly describe the device-tree concept before detailing
444
the storage format. This chapter does _not_ describe the detail of the
445
required types of nodes & properties for the kernel, this is done
446
later in chapter III.
448
The device-tree layout is strongly inherited from the definition of
449
the Open Firmware IEEE 1275 device-tree. It's basically a tree of
450
nodes, each node having two or more named properties. A property can
453
It is a tree, so each node has one and only one parent except for the
454
root node who has no parent.
456
A node has 2 names. The actual node name is generally contained in a
457
property of type "name" in the node property list whose value is a
458
zero terminated string and is mandatory for version 1 to 3 of the
459
format definition (as it is in Open Firmware). Version 16 makes it
460
optional as it can generate it from the unit name defined below.
462
There is also a "unit name" that is used to differentiate nodes with
463
the same name at the same level, it is usually made of the node
464
names, the "@" sign, and a "unit address", which definition is
465
specific to the bus type the node sits on.
467
The unit name doesn't exist as a property per-se but is included in
468
the device-tree structure. It is typically used to represent "path" in
469
the device-tree. More details about the actual format of these will be
472
The kernel powerpc generic code does not make any formal use of the
473
unit address (though some board support code may do) so the only real
474
requirement here for the unit address is to ensure uniqueness of
475
the node unit name at a given level of the tree. Nodes with no notion
476
of address and no possible sibling of the same name (like /memory or
477
/cpus) may omit the unit address in the context of this specification,
478
or use the "@0" default unit address. The unit name is used to define
479
a node "full path", which is the concatenation of all parent node
480
unit names separated with "/".
482
The root node doesn't have a defined name, and isn't required to have
483
a name property either if you are using version 3 or earlier of the
484
format. It also has no unit address (no @ symbol followed by a unit
485
address). The root node unit name is thus an empty string. The full
486
path to the root node is "/".
488
Every node which actually represents an actual device (that is, a node
489
which isn't only a virtual "container" for more nodes, like "/cpus"
490
is) is also required to have a "device_type" property indicating the
493
Finally, every node that can be referenced from a property in another
494
node is required to have a "linux,phandle" property. Real open
495
firmware implementations provide a unique "phandle" value for every
496
node that the "prom_init()" trampoline code turns into
497
"linux,phandle" properties. However, this is made optional if the
498
flattened device tree is used directly. An example of a node
499
referencing another node via "phandle" is when laying out the
500
interrupt tree which will be described in a further version of this
503
This "linux, phandle" property is a 32-bit value that uniquely
504
identifies a node. You are free to use whatever values or system of
505
values, internal pointers, or whatever to generate these, the only
506
requirement is that every node for which you provide that property has
507
a unique value for it.
509
Here is an example of a simple device-tree. In this example, an "o"
510
designates a node followed by the node unit name. Properties are
511
presented with their name followed by their content. "content"
512
represents an ASCII string (zero terminated) value, while <content>
513
represents a 32-bit hexadecimal value. The various nodes in this
514
example will be discussed in a later chapter. At this point, it is
515
only meant to give you a idea of what a device-tree looks like. I have
516
purposefully kept the "name" and "linux,phandle" properties which
517
aren't necessary in order to give you a better idea of what the tree
518
looks like in practice.
521
|- name = "device-tree"
522
|- model = "MyBoardName"
523
|- compatible = "MyBoardFamilyName"
524
|- #address-cells = <2>
526
|- linux,phandle = <0>
530
| | - linux,phandle = <1>
531
| | - #address-cells = <1>
532
| | - #size-cells = <0>
535
| |- name = "PowerPC,970"
536
| |- device_type = "cpu"
538
| |- clock-frequency = <5f5e1000>
540
| |- linux,phandle = <2>
544
| |- device_type = "memory"
545
| |- reg = <00000000 00000000 00000000 20000000>
546
| |- linux,phandle = <3>
550
|- bootargs = "root=/dev/sda2"
551
|- linux,phandle = <4>
553
This tree is almost a minimal tree. It pretty much contains the
554
minimal set of required nodes and properties to boot a linux kernel;
555
that is, some basic model informations at the root, the CPUs, and the
556
physical memory layout. It also includes misc information passed
557
through /chosen, like in this example, the platform type (mandatory)
558
and the kernel command line arguments (optional).
560
The /cpus/PowerPC,970@0/64-bit property is an example of a
561
property without a value. All other properties have a value. The
562
significance of the #address-cells and #size-cells properties will be
563
explained in chapter IV which defines precisely the required nodes and
564
properties and their content.
567
3) Device tree "structure" block
569
The structure of the device tree is a linearized tree structure. The
570
"OF_DT_BEGIN_NODE" token starts a new node, and the "OF_DT_END_NODE"
571
ends that node definition. Child nodes are simply defined before
572
"OF_DT_END_NODE" (that is nodes within the node). A 'token' is a 32
573
bit value. The tree has to be "finished" with a OF_DT_END token
575
Here's the basic structure of a single node:
577
* token OF_DT_BEGIN_NODE (that is 0x00000001)
578
* for version 1 to 3, this is the node full path as a zero
579
terminated string, starting with "/". For version 16 and later,
580
this is the node unit name only (or an empty string for the
582
* [align gap to next 4 bytes boundary]
584
* token OF_DT_PROP (that is 0x00000003)
585
* 32-bit value of property value size in bytes (or 0 if no
587
* 32-bit value of offset in string block of property name
588
* property value data if any
589
* [align gap to next 4 bytes boundary]
590
* [child nodes if any]
591
* token OF_DT_END_NODE (that is 0x00000002)
593
So the node content can be summarized as a start token, a full path,
594
a list of properties, a list of child nodes, and an end token. Every
595
child node is a full node structure itself as defined above.
597
NOTE: The above definition requires that all property definitions for
598
a particular node MUST precede any subnode definitions for that node.
599
Although the structure would not be ambiguous if properties and
600
subnodes were intermingled, the kernel parser requires that the
601
properties come first (up until at least 2.6.22). Any tools
602
manipulating a flattened tree must take care to preserve this
605
4) Device tree "strings" block
607
In order to save space, property names, which are generally redundant,
608
are stored separately in the "strings" block. This block is simply the
609
whole bunch of zero terminated strings for all property names
610
concatenated together. The device-tree property definitions in the
611
structure block will contain offset values from the beginning of the
617
This library should be merged into dtc proper.
618
This library should likely be worked into U-Boot and the kernel.
added
removed
Documentation/manual.txt
