|
1 Device Tree Compiler Manual |
|
2 =========================== |
|
3 |
|
4 I - "dtc", the device tree compiler |
|
5 1) Obtaining Sources |
|
6 2) Description |
|
7 3) Command Line |
|
8 4) Source File |
|
9 4.1) Overview |
|
10 4.2) Properties |
|
11 4.3) Labels and References |
|
12 |
|
13 II - The DT block format |
|
14 1) Header |
|
15 2) Device tree generalities |
|
16 3) Device tree "structure" block |
|
17 4) Device tree "strings" block |
|
18 |
|
19 |
|
20 III - libfdt |
|
21 |
|
22 |
|
23 I - "dtc", the device tree compiler |
|
24 =================================== |
|
25 |
|
26 1) Sources |
|
27 |
|
28 Source code for the Device Tree Compiler can be found at jdl.com. |
|
29 The gitweb interface is: |
|
30 |
|
31 http://www.jdl.com/git_repos/ |
|
32 |
|
33 The repository is here: |
|
34 |
|
35 git://www.jdl.com/software/dtc.git |
|
36 http://www.jdl.com/software/dtc.git |
|
37 |
|
38 Tarballs of the 1.0.0 and latest releases are here: |
|
39 |
|
40 http://www.jdl.com/software/dtc-1.0.0.tgz |
|
41 http://www.jdl.com/software/dtc-latest.tgz |
|
42 |
|
43 |
|
44 2) Description |
|
45 |
|
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. |
|
50 |
|
51 The currently supported Input Formats are: |
|
52 |
|
53 - "dtb": "blob" format. A flattened device-tree block with |
|
54 header in one binary blob. |
|
55 |
|
56 - "dts": "source" format. A text file containing a "source" |
|
57 for a device-tree. |
|
58 |
|
59 - "fs" format. A representation equivalent to the output of |
|
60 /proc/device-tree where nodes are directories and |
|
61 properties are files. |
|
62 |
|
63 The currently supported Output Formats are: |
|
64 |
|
65 - "dtb": "blob" format |
|
66 |
|
67 - "dts": "source" format |
|
68 |
|
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. |
|
73 |
|
74 |
|
75 3) Command Line |
|
76 |
|
77 The syntax of the dtc command line is: |
|
78 |
|
79 dtc [options] [<input_filename>] |
|
80 |
|
81 Options: |
|
82 |
|
83 <input_filename> |
|
84 The name of the input source file. If no <input_filename> |
|
85 or "-" is given, stdin is used. |
|
86 |
|
87 -b <number> |
|
88 Set the physical boot cpu. |
|
89 |
|
90 -f |
|
91 Force. Try to produce output even if the input tree has errors. |
|
92 |
|
93 -h |
|
94 Emit a brief usage and help message. |
|
95 |
|
96 -I <input_format> |
|
97 The source input format, as listed above. |
|
98 |
|
99 -o <output_filename> |
|
100 The name of the generated output file. Use "-" for stdout. |
|
101 |
|
102 -O <output_format> |
|
103 The generated output format, as listed above. |
|
104 |
|
105 -q |
|
106 Quiet: -q suppress warnings, -qq errors, -qqq all |
|
107 |
|
108 -R <number> |
|
109 Make space for <number> reserve map entries |
|
110 Relevant for dtb and asm output only. |
|
111 |
|
112 -S <bytes> |
|
113 Ensure the blob at least <bytes> long, adding additional |
|
114 space if needed. |
|
115 |
|
116 -v |
|
117 Print DTC version and exit. |
|
118 |
|
119 -V <output_version> |
|
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. |
|
123 |
|
124 |
|
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. |
|
128 |
|
129 Additionally, dtc performs various sanity checks on the tree. |
|
130 |
|
131 |
|
132 4) Device Tree Source file |
|
133 |
|
134 4.1) Overview |
|
135 |
|
136 Here is a very rough overview of the layout of a DTS source file: |
|
137 |
|
138 |
|
139 sourcefile: list_of_memreserve devicetree |
|
140 |
|
141 memreserve: label 'memreserve' ADDR ADDR ';' |
|
142 | label 'memreserve' ADDR '-' ADDR ';' |
|
143 |
|
144 devicetree: '/' nodedef |
|
145 |
|
146 nodedef: '{' list_of_property list_of_subnode '}' ';' |
|
147 |
|
148 property: label PROPNAME '=' propdata ';' |
|
149 |
|
150 propdata: STRING |
|
151 | '<' list_of_cells '>' |
|
152 | '[' list_of_bytes ']' |
|
153 |
|
154 subnode: label nodename nodedef |
|
155 |
|
156 That structure forms a hierarchical layout of nodes and properties |
|
157 rooted at an initial node as: |
|
158 |
|
159 / { |
|
160 } |
|
161 |
|
162 Both classic C style and C++ style comments are supported. |
|
163 |
|
164 Source files may be directly included using the syntax: |
|
165 |
|
166 /include/ "filename" |
|
167 |
|
168 |
|
169 4.2) Properties |
|
170 |
|
171 Properties are named, possibly labeled, values. Each value |
|
172 is one of: |
|
173 |
|
174 - A null-teminated C-like string, |
|
175 - A numeric value fitting in 32 bits, |
|
176 - A list of 32-bit values |
|
177 - A byte sequence |
|
178 |
|
179 Here are some example property definitions: |
|
180 |
|
181 - A property containing a 0 terminated string |
|
182 |
|
183 property1 = "string_value"; |
|
184 |
|
185 - A property containing a numerical 32-bit hexadecimal value |
|
186 |
|
187 property2 = <1234abcd>; |
|
188 |
|
189 - A property containing 3 numerical 32-bit hexadecimal values |
|
190 |
|
191 property3 = <12345678 12345678 deadbeef>; |
|
192 |
|
193 - A property whose content is an arbitrary array of bytes |
|
194 |
|
195 property4 = [0a 0b 0c 0d de ea ad be ef]; |
|
196 |
|
197 |
|
198 Node may contain sub-nodes to obtain a hierarchical structure. |
|
199 For example: |
|
200 |
|
201 - A child node named "childnode" whose unit name is |
|
202 "childnode at address". It it turn has a string property |
|
203 called "childprop". |
|
204 |
|
205 childnode@addresss { |
|
206 childprop = "hello\n"; |
|
207 }; |
|
208 |
|
209 |
|
210 By default, all numeric values are hexadecimal. Alternate bases |
|
211 may be specified using a prefix "d#" for decimal, "b#" for binary, |
|
212 and "o#" for octal. |
|
213 |
|
214 Strings support common escape sequences from C: "\n", "\t", "\r", |
|
215 "\(octal value)", "\x(hex value)". |
|
216 |
|
217 |
|
218 4.3) Labels and References |
|
219 |
|
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. |
|
223 |
|
224 In this exmaple, a node is labled "mpic" and then referenced: |
|
225 |
|
226 mpic: interrupt-controller@40000 { |
|
227 ... |
|
228 }; |
|
229 |
|
230 ethernet-phy@3 { |
|
231 interrupt-parent = <&mpic>; |
|
232 ... |
|
233 }; |
|
234 |
|
235 And used in properties, lables may appear before or after any value: |
|
236 |
|
237 randomnode { |
|
238 prop: string = data: "mystring\n" data_end: ; |
|
239 ... |
|
240 }; |
|
241 |
|
242 |
|
243 |
|
244 II - The DT block format |
|
245 ======================== |
|
246 |
|
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 |
|
250 |
|
251 linux-2.6/Documentation/powerpc/booting-without-of.txt |
|
252 |
|
253 You can find example of code manipulating that format within |
|
254 the kernel. For example, the file: |
|
255 |
|
256 including arch/powerpc/kernel/prom_init.c |
|
257 |
|
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. |
|
263 |
|
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 |
|
268 the kernel. |
|
269 |
|
270 |
|
271 1) Header |
|
272 --------- |
|
273 |
|
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 |
|
276 boot_param_header: |
|
277 |
|
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 */ |
|
286 |
|
287 /* version 2 fields below */ |
|
288 u32 boot_cpuid_phys; /* Which physical CPU id we're |
|
289 booting on */ |
|
290 /* version 3 fields below */ |
|
291 u32 size_dt_strings; /* size of the strings block */ |
|
292 |
|
293 /* version 17 fields below */ |
|
294 u32 size_dt_struct; /* size of the DT structure block */ |
|
295 }; |
|
296 |
|
297 Along with the constants: |
|
298 |
|
299 /* Definitions used by the flattened device tree */ |
|
300 #define OF_DT_HEADER 0xd00dfeed /* 4: version, |
|
301 4: total size */ |
|
302 #define OF_DT_BEGIN_NODE 0x1 /* Start node: full name |
|
303 */ |
|
304 #define OF_DT_END_NODE 0x2 /* End node */ |
|
305 #define OF_DT_PROP 0x3 /* Property: name off, |
|
306 size, content */ |
|
307 #define OF_DT_END 0x9 |
|
308 |
|
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 |
|
312 value of r3. |
|
313 |
|
314 - magic |
|
315 |
|
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 |
|
319 |
|
320 - totalsize |
|
321 |
|
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. |
|
326 |
|
327 - off_dt_struct |
|
328 |
|
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) |
|
331 |
|
332 - off_dt_strings |
|
333 |
|
334 This is an offset from the beginning of the header to the start |
|
335 of the "strings" part of the device-tree |
|
336 |
|
337 - off_mem_rsvmap |
|
338 |
|
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. |
|
355 |
|
356 - version |
|
357 |
|
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. |
|
371 |
|
372 - last_comp_version |
|
373 |
|
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. |
|
381 |
|
382 - boot_cpuid_phys |
|
383 |
|
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) |
|
391 |
|
392 - size_dt_strings |
|
393 |
|
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). |
|
397 |
|
398 - size_dt_struct |
|
399 |
|
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). |
|
403 |
|
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 |
|
406 bottom): |
|
407 |
|
408 ------------------------------ |
|
409 r3 -> | struct boot_param_header | |
|
410 ------------------------------ |
|
411 | (alignment gap) (*) | |
|
412 ------------------------------ |
|
413 | memory reserve map | |
|
414 ------------------------------ |
|
415 | (alignment gap) | |
|
416 ------------------------------ |
|
417 | | |
|
418 | device-tree structure | |
|
419 | | |
|
420 ------------------------------ |
|
421 | (alignment gap) | |
|
422 ------------------------------ |
|
423 | | |
|
424 | device-tree strings | |
|
425 | | |
|
426 -----> ------------------------------ |
|
427 | |
|
428 | |
|
429 --- (r3 + totalsize) |
|
430 |
|
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. |
|
434 |
|
435 |
|
436 2) Device tree generalities |
|
437 --------------------------- |
|
438 |
|
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 |
|
441 byte boundary. |
|
442 |
|
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. |
|
447 |
|
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 |
|
451 have a value or not. |
|
452 |
|
453 It is a tree, so each node has one and only one parent except for the |
|
454 root node who has no parent. |
|
455 |
|
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. |
|
461 |
|
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. |
|
466 |
|
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 |
|
470 below. |
|
471 |
|
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 "/". |
|
481 |
|
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 "/". |
|
487 |
|
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 |
|
491 type of node . |
|
492 |
|
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 |
|
501 document. |
|
502 |
|
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. |
|
508 |
|
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. |
|
519 |
|
520 / o device-tree |
|
521 |- name = "device-tree" |
|
522 |- model = "MyBoardName" |
|
523 |- compatible = "MyBoardFamilyName" |
|
524 |- #address-cells = <2> |
|
525 |- #size-cells = <2> |
|
526 |- linux,phandle = <0> |
|
527 | |
|
528 o cpus |
|
529 | | - name = "cpus" |
|
530 | | - linux,phandle = <1> |
|
531 | | - #address-cells = <1> |
|
532 | | - #size-cells = <0> |
|
533 | | |
|
534 | o PowerPC,970@0 |
|
535 | |- name = "PowerPC,970" |
|
536 | |- device_type = "cpu" |
|
537 | |- reg = <0> |
|
538 | |- clock-frequency = <5f5e1000> |
|
539 | |- 64-bit |
|
540 | |- linux,phandle = <2> |
|
541 | |
|
542 o memory@0 |
|
543 | |- name = "memory" |
|
544 | |- device_type = "memory" |
|
545 | |- reg = <00000000 00000000 00000000 20000000> |
|
546 | |- linux,phandle = <3> |
|
547 | |
|
548 o chosen |
|
549 |- name = "chosen" |
|
550 |- bootargs = "root=/dev/sda2" |
|
551 |- linux,phandle = <4> |
|
552 |
|
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). |
|
559 |
|
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. |
|
565 |
|
566 |
|
567 3) Device tree "structure" block |
|
568 |
|
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 |
|
574 |
|
575 Here's the basic structure of a single node: |
|
576 |
|
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 |
|
581 root node) |
|
582 * [align gap to next 4 bytes boundary] |
|
583 * for each property: |
|
584 * token OF_DT_PROP (that is 0x00000003) |
|
585 * 32-bit value of property value size in bytes (or 0 if no |
|
586 value) |
|
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) |
|
592 |
|
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. |
|
596 |
|
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 |
|
603 constraint. |
|
604 |
|
605 4) Device tree "strings" block |
|
606 |
|
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 |
|
612 strings block. |
|
613 |
|
614 |
|
615 III - libfdt |
|
616 |
|
617 This library should be merged into dtc proper. |
|
618 This library should likely be worked into U-Boot and the kernel. |