manual.txt revision 266130
1Device Tree Compiler Manual 2=========================== 3 4I - "dtc", the device tree compiler 5 1) Obtaining Sources 6 1.1) Submitting Patches 7 2) Description 8 3) Command Line 9 4) Source File 10 4.1) Overview 11 4.2) Properties 12 4.3) Labels and References 13 14II - The DT block format 15 1) Header 16 2) Device tree generalities 17 3) Device tree "structure" block 18 4) Device tree "strings" block 19 20 21III - libfdt 22 23IV - Utility Tools 24 1) convert-dtsv0 -- Conversion to Version 1 25 1) fdtdump 26 27 28I - "dtc", the device tree compiler 29=================================== 30 311) Sources 32 33Source code for the Device Tree Compiler can be found at jdl.com. 34The gitweb interface is: 35 36 http://git.jdl.com/gitweb/ 37 38The repository is here: 39 40 git://www.jdl.com/software/dtc.git 41 http://www.jdl.com/software/dtc.git 42 43Tarballs of the 1.0.0 and latest releases are here: 44 45 http://www.jdl.com/software/dtc-v1.2.0.tgz 46 http://www.jdl.com/software/dtc-latest.tgz 47 481.1) Submitting Patches 49 50Patches should be sent to jdl@jdl.com, and CC'ed to 51devicetree-discuss@lists.ozlabs.org. 52 532) Description 54 55The Device Tree Compiler, dtc, takes as input a device-tree in 56a given format and outputs a device-tree in another format. 57Typically, the input format is "dts", a human readable source 58format, and creates a "dtb", or binary format as output. 59 60The currently supported Input Formats are: 61 62 - "dtb": "blob" format. A flattened device-tree block with 63 header in one binary blob. 64 65 - "dts": "source" format. A text file containing a "source" 66 for a device-tree. 67 68 - "fs" format. A representation equivalent to the output of 69 /proc/device-tree where nodes are directories and 70 properties are files. 71 72The currently supported Output Formats are: 73 74 - "dtb": "blob" format 75 76 - "dts": "source" format 77 78 - "asm": assembly language file. A file that can be sourced 79 by gas to generate a device-tree "blob". That file can 80 then simply be added to your Makefile. Additionally, the 81 assembly file exports some symbols that can be used. 82 83 843) Command Line 85 86The syntax of the dtc command line is: 87 88 dtc [options] [<input_filename>] 89 90Options: 91 92 <input_filename> 93 The name of the input source file. If no <input_filename> 94 or "-" is given, stdin is used. 95 96 -b <number> 97 Set the physical boot cpu. 98 99 -f 100 Force. Try to produce output even if the input tree has errors. 101 102 -h 103 Emit a brief usage and help message. 104 105 -I <input_format> 106 The source input format, as listed above. 107 108 -o <output_filename> 109 The name of the generated output file. Use "-" for stdout. 110 111 -O <output_format> 112 The generated output format, as listed above. 113 114 -d <dependency_filename> 115 Generate a dependency file during compilation. 116 117 -q 118 Quiet: -q suppress warnings, -qq errors, -qqq all 119 120 -R <number> 121 Make space for <number> reserve map entries 122 Relevant for dtb and asm output only. 123 124 -S <bytes> 125 Ensure the blob at least <bytes> long, adding additional 126 space if needed. 127 128 -v 129 Print DTC version and exit. 130 131 -V <output_version> 132 Generate output conforming to the given <output_version>. 133 By default the most recent version is generated. 134 Relevant for dtb and asm output only. 135 136 137The <output_version> defines what version of the "blob" format will be 138generated. Supported versions are 1, 2, 3, 16 and 17. The default is 139always the most recent version and is likely the highest number. 140 141Additionally, dtc performs various sanity checks on the tree. 142 143 1444) Device Tree Source file 145 1464.1) Overview 147 148Here is a very rough overview of the layout of a DTS source file: 149 150 151 sourcefile: list_of_memreserve devicetree 152 153 memreserve: label 'memreserve' ADDR ADDR ';' 154 | label 'memreserve' ADDR '-' ADDR ';' 155 156 devicetree: '/' nodedef 157 158 nodedef: '{' list_of_property list_of_subnode '}' ';' 159 160 property: label PROPNAME '=' propdata ';' 161 162 propdata: STRING 163 | '<' list_of_cells '>' 164 | '[' list_of_bytes ']' 165 166 subnode: label nodename nodedef 167 168That structure forms a hierarchical layout of nodes and properties 169rooted at an initial node as: 170 171 / { 172 } 173 174Both classic C style and C++ style comments are supported. 175 176Source files may be directly included using the syntax: 177 178 /include/ "filename" 179 180 1814.2) Properties 182 183Properties are named, possibly labeled, values. Each value 184is one of: 185 186 - A null-teminated C-like string, 187 - A numeric value fitting in 32 bits, 188 - A list of 32-bit values 189 - A byte sequence 190 191Here are some example property definitions: 192 193 - A property containing a 0 terminated string 194 195 property1 = "string_value"; 196 197 - A property containing a numerical 32-bit hexadecimal value 198 199 property2 = <1234abcd>; 200 201 - A property containing 3 numerical 32-bit hexadecimal values 202 203 property3 = <12345678 12345678 deadbeef>; 204 205 - A property whose content is an arbitrary array of bytes 206 207 property4 = [0a 0b 0c 0d de ea ad be ef]; 208 209 210Node may contain sub-nodes to obtain a hierarchical structure. 211For example: 212 213 - A child node named "childnode" whose unit name is 214 "childnode at address". It it turn has a string property 215 called "childprop". 216 217 childnode@addresss { 218 childprop = "hello\n"; 219 }; 220 221 222By default, all numeric values are hexadecimal. Alternate bases 223may be specified using a prefix "d#" for decimal, "b#" for binary, 224and "o#" for octal. 225 226Strings support common escape sequences from C: "\n", "\t", "\r", 227"\(octal value)", "\x(hex value)". 228 229 2304.3) Labels and References 231 232Labels may be applied to nodes or properties. Labels appear 233before a node name, and are referenced using an ampersand: &label. 234Absolute node path names are also allowed in node references. 235 236In this exmaple, a node is labled "mpic" and then referenced: 237 238 mpic: interrupt-controller@40000 { 239 ... 240 }; 241 242 ethernet-phy@3 { 243 interrupt-parent = <&mpic>; 244 ... 245 }; 246 247And used in properties, lables may appear before or after any value: 248 249 randomnode { 250 prop: string = data: "mystring\n" data_end: ; 251 ... 252 }; 253 254 255 256II - The DT block format 257======================== 258 259This chapter defines the format of the flattened device-tree 260passed to the kernel. The actual content of the device tree 261are described in the kernel documentation in the file 262 263 linux-2.6/Documentation/powerpc/booting-without-of.txt 264 265You can find example of code manipulating that format within 266the kernel. For example, the file: 267 268 including arch/powerpc/kernel/prom_init.c 269 270will generate a flattened device-tree from the Open Firmware 271representation. Other utilities such as fs2dt, which is part of 272the kexec tools, will generate one from a filesystem representation. 273Some bootloaders such as U-Boot provide a bit more support by 274using the libfdt code. 275 276For booting the kernel, the device tree block has to be in main memory. 277It has to be accessible in both real mode and virtual mode with no 278mapping other than main memory. If you are writing a simple flash 279bootloader, it should copy the block to RAM before passing it to 280the kernel. 281 282 2831) Header 284--------- 285 286The kernel is entered with r3 pointing to an area of memory that is 287roughly described in include/asm-powerpc/prom.h by the structure 288boot_param_header: 289 290 struct boot_param_header { 291 u32 magic; /* magic word OF_DT_HEADER */ 292 u32 totalsize; /* total size of DT block */ 293 u32 off_dt_struct; /* offset to structure */ 294 u32 off_dt_strings; /* offset to strings */ 295 u32 off_mem_rsvmap; /* offset to memory reserve map */ 296 u32 version; /* format version */ 297 u32 last_comp_version; /* last compatible version */ 298 299 /* version 2 fields below */ 300 u32 boot_cpuid_phys; /* Which physical CPU id we're 301 booting on */ 302 /* version 3 fields below */ 303 u32 size_dt_strings; /* size of the strings block */ 304 305 /* version 17 fields below */ 306 u32 size_dt_struct; /* size of the DT structure block */ 307 }; 308 309Along with the constants: 310 311 /* Definitions used by the flattened device tree */ 312 #define OF_DT_HEADER 0xd00dfeed /* 4: version, 313 4: total size */ 314 #define OF_DT_BEGIN_NODE 0x1 /* Start node: full name 315 */ 316 #define OF_DT_END_NODE 0x2 /* End node */ 317 #define OF_DT_PROP 0x3 /* Property: name off, 318 size, content */ 319 #define OF_DT_END 0x9 320 321All values in this header are in big endian format, the various 322fields in this header are defined more precisely below. All "offset" 323values are in bytes from the start of the header; that is from the 324value of r3. 325 326 - magic 327 328 This is a magic value that "marks" the beginning of the 329 device-tree block header. It contains the value 0xd00dfeed and is 330 defined by the constant OF_DT_HEADER 331 332 - totalsize 333 334 This is the total size of the DT block including the header. The 335 "DT" block should enclose all data structures defined in this 336 chapter (who are pointed to by offsets in this header). That is, 337 the device-tree structure, strings, and the memory reserve map. 338 339 - off_dt_struct 340 341 This is an offset from the beginning of the header to the start 342 of the "structure" part the device tree. (see 2) device tree) 343 344 - off_dt_strings 345 346 This is an offset from the beginning of the header to the start 347 of the "strings" part of the device-tree 348 349 - off_mem_rsvmap 350 351 This is an offset from the beginning of the header to the start 352 of the reserved memory map. This map is a list of pairs of 64- 353 bit integers. Each pair is a physical address and a size. The 354 list is terminated by an entry of size 0. This map provides the 355 kernel with a list of physical memory areas that are "reserved" 356 and thus not to be used for memory allocations, especially during 357 early initialization. The kernel needs to allocate memory during 358 boot for things like un-flattening the device-tree, allocating an 359 MMU hash table, etc... Those allocations must be done in such a 360 way to avoid overriding critical things like, on Open Firmware 361 capable machines, the RTAS instance, or on some pSeries, the TCE 362 tables used for the iommu. Typically, the reserve map should 363 contain _at least_ this DT block itself (header,total_size). If 364 you are passing an initrd to the kernel, you should reserve it as 365 well. You do not need to reserve the kernel image itself. The map 366 should be 64-bit aligned. 367 368 - version 369 370 This is the version of this structure. Version 1 stops 371 here. Version 2 adds an additional field boot_cpuid_phys. 372 Version 3 adds the size of the strings block, allowing the kernel 373 to reallocate it easily at boot and free up the unused flattened 374 structure after expansion. Version 16 introduces a new more 375 "compact" format for the tree itself that is however not backward 376 compatible. Version 17 adds an additional field, size_dt_struct, 377 allowing it to be reallocated or moved more easily (this is 378 particularly useful for bootloaders which need to make 379 adjustments to a device tree based on probed information). You 380 should always generate a structure of the highest version defined 381 at the time of your implementation. Currently that is version 17, 382 unless you explicitly aim at being backward compatible. 383 384 - last_comp_version 385 386 Last compatible version. This indicates down to what version of 387 the DT block you are backward compatible. For example, version 2 388 is backward compatible with version 1 (that is, a kernel build 389 for version 1 will be able to boot with a version 2 format). You 390 should put a 1 in this field if you generate a device tree of 391 version 1 to 3, or 16 if you generate a tree of version 16 or 17 392 using the new unit name format. 393 394 - boot_cpuid_phys 395 396 This field only exist on version 2 headers. It indicate which 397 physical CPU ID is calling the kernel entry point. This is used, 398 among others, by kexec. If you are on an SMP system, this value 399 should match the content of the "reg" property of the CPU node in 400 the device-tree corresponding to the CPU calling the kernel entry 401 point (see further chapters for more informations on the required 402 device-tree contents) 403 404 - size_dt_strings 405 406 This field only exists on version 3 and later headers. It 407 gives the size of the "strings" section of the device tree (which 408 starts at the offset given by off_dt_strings). 409 410 - size_dt_struct 411 412 This field only exists on version 17 and later headers. It gives 413 the size of the "structure" section of the device tree (which 414 starts at the offset given by off_dt_struct). 415 416So the typical layout of a DT block (though the various parts don't 417need to be in that order) looks like this (addresses go from top to 418bottom): 419 420 ------------------------------ 421 r3 -> | struct boot_param_header | 422 ------------------------------ 423 | (alignment gap) (*) | 424 ------------------------------ 425 | memory reserve map | 426 ------------------------------ 427 | (alignment gap) | 428 ------------------------------ 429 | | 430 | device-tree structure | 431 | | 432 ------------------------------ 433 | (alignment gap) | 434 ------------------------------ 435 | | 436 | device-tree strings | 437 | | 438 -----> ------------------------------ 439 | 440 | 441 --- (r3 + totalsize) 442 443 (*) The alignment gaps are not necessarily present; their presence 444 and size are dependent on the various alignment requirements of 445 the individual data blocks. 446 447 4482) Device tree generalities 449--------------------------- 450 451This device-tree itself is separated in two different blocks, a 452structure block and a strings block. Both need to be aligned to a 4 453byte boundary. 454 455First, let's quickly describe the device-tree concept before detailing 456the storage format. This chapter does _not_ describe the detail of the 457required types of nodes & properties for the kernel, this is done 458later in chapter III. 459 460The device-tree layout is strongly inherited from the definition of 461the Open Firmware IEEE 1275 device-tree. It's basically a tree of 462nodes, each node having two or more named properties. A property can 463have a value or not. 464 465It is a tree, so each node has one and only one parent except for the 466root node who has no parent. 467 468A node has 2 names. The actual node name is generally contained in a 469property of type "name" in the node property list whose value is a 470zero terminated string and is mandatory for version 1 to 3 of the 471format definition (as it is in Open Firmware). Version 16 makes it 472optional as it can generate it from the unit name defined below. 473 474There is also a "unit name" that is used to differentiate nodes with 475the same name at the same level, it is usually made of the node 476names, the "@" sign, and a "unit address", which definition is 477specific to the bus type the node sits on. 478 479The unit name doesn't exist as a property per-se but is included in 480the device-tree structure. It is typically used to represent "path" in 481the device-tree. More details about the actual format of these will be 482below. 483 484The kernel powerpc generic code does not make any formal use of the 485unit address (though some board support code may do) so the only real 486requirement here for the unit address is to ensure uniqueness of 487the node unit name at a given level of the tree. Nodes with no notion 488of address and no possible sibling of the same name (like /memory or 489/cpus) may omit the unit address in the context of this specification, 490or use the "@0" default unit address. The unit name is used to define 491a node "full path", which is the concatenation of all parent node 492unit names separated with "/". 493 494The root node doesn't have a defined name, and isn't required to have 495a name property either if you are using version 3 or earlier of the 496format. It also has no unit address (no @ symbol followed by a unit 497address). The root node unit name is thus an empty string. The full 498path to the root node is "/". 499 500Every node which actually represents an actual device (that is, a node 501which isn't only a virtual "container" for more nodes, like "/cpus" 502is) is also required to have a "device_type" property indicating the 503type of node . 504 505Finally, every node that can be referenced from a property in another 506node is required to have a "linux,phandle" property. Real open 507firmware implementations provide a unique "phandle" value for every 508node that the "prom_init()" trampoline code turns into 509"linux,phandle" properties. However, this is made optional if the 510flattened device tree is used directly. An example of a node 511referencing another node via "phandle" is when laying out the 512interrupt tree which will be described in a further version of this 513document. 514 515This "linux, phandle" property is a 32-bit value that uniquely 516identifies a node. You are free to use whatever values or system of 517values, internal pointers, or whatever to generate these, the only 518requirement is that every node for which you provide that property has 519a unique value for it. 520 521Here is an example of a simple device-tree. In this example, an "o" 522designates a node followed by the node unit name. Properties are 523presented with their name followed by their content. "content" 524represents an ASCII string (zero terminated) value, while <content> 525represents a 32-bit hexadecimal value. The various nodes in this 526example will be discussed in a later chapter. At this point, it is 527only meant to give you a idea of what a device-tree looks like. I have 528purposefully kept the "name" and "linux,phandle" properties which 529aren't necessary in order to give you a better idea of what the tree 530looks like in practice. 531 532 / o device-tree 533 |- name = "device-tree" 534 |- model = "MyBoardName" 535 |- compatible = "MyBoardFamilyName" 536 |- #address-cells = <2> 537 |- #size-cells = <2> 538 |- linux,phandle = <0> 539 | 540 o cpus 541 | | - name = "cpus" 542 | | - linux,phandle = <1> 543 | | - #address-cells = <1> 544 | | - #size-cells = <0> 545 | | 546 | o PowerPC,970@0 547 | |- name = "PowerPC,970" 548 | |- device_type = "cpu" 549 | |- reg = <0> 550 | |- clock-frequency = <5f5e1000> 551 | |- 64-bit 552 | |- linux,phandle = <2> 553 | 554 o memory@0 555 | |- name = "memory" 556 | |- device_type = "memory" 557 | |- reg = <00000000 00000000 00000000 20000000> 558 | |- linux,phandle = <3> 559 | 560 o chosen 561 |- name = "chosen" 562 |- bootargs = "root=/dev/sda2" 563 |- linux,phandle = <4> 564 565This tree is almost a minimal tree. It pretty much contains the 566minimal set of required nodes and properties to boot a linux kernel; 567that is, some basic model informations at the root, the CPUs, and the 568physical memory layout. It also includes misc information passed 569through /chosen, like in this example, the platform type (mandatory) 570and the kernel command line arguments (optional). 571 572The /cpus/PowerPC,970@0/64-bit property is an example of a 573property without a value. All other properties have a value. The 574significance of the #address-cells and #size-cells properties will be 575explained in chapter IV which defines precisely the required nodes and 576properties and their content. 577 578 5793) Device tree "structure" block 580 581The structure of the device tree is a linearized tree structure. The 582"OF_DT_BEGIN_NODE" token starts a new node, and the "OF_DT_END_NODE" 583ends that node definition. Child nodes are simply defined before 584"OF_DT_END_NODE" (that is nodes within the node). A 'token' is a 32 585bit value. The tree has to be "finished" with a OF_DT_END token 586 587Here's the basic structure of a single node: 588 589 * token OF_DT_BEGIN_NODE (that is 0x00000001) 590 * for version 1 to 3, this is the node full path as a zero 591 terminated string, starting with "/". For version 16 and later, 592 this is the node unit name only (or an empty string for the 593 root node) 594 * [align gap to next 4 bytes boundary] 595 * for each property: 596 * token OF_DT_PROP (that is 0x00000003) 597 * 32-bit value of property value size in bytes (or 0 if no 598 value) 599 * 32-bit value of offset in string block of property name 600 * property value data if any 601 * [align gap to next 4 bytes boundary] 602 * [child nodes if any] 603 * token OF_DT_END_NODE (that is 0x00000002) 604 605So the node content can be summarized as a start token, a full path, 606a list of properties, a list of child nodes, and an end token. Every 607child node is a full node structure itself as defined above. 608 609NOTE: The above definition requires that all property definitions for 610a particular node MUST precede any subnode definitions for that node. 611Although the structure would not be ambiguous if properties and 612subnodes were intermingled, the kernel parser requires that the 613properties come first (up until at least 2.6.22). Any tools 614manipulating a flattened tree must take care to preserve this 615constraint. 616 6174) Device tree "strings" block 618 619In order to save space, property names, which are generally redundant, 620are stored separately in the "strings" block. This block is simply the 621whole bunch of zero terminated strings for all property names 622concatenated together. The device-tree property definitions in the 623structure block will contain offset values from the beginning of the 624strings block. 625 626 627III - libfdt 628============ 629 630This library should be merged into dtc proper. 631This library should likely be worked into U-Boot and the kernel. 632 633 634IV - Utility Tools 635================== 636 6371) convert-dtsv0 -- Conversion to Version 1 638 639convert-dtsv0 is a small utility program which converts (DTS) 640Device Tree Source from the obsolete version 0 to version 1. 641 642Version 1 DTS files are marked by line "/dts-v1/;" at the top of the file. 643 644The syntax of the convert-dtsv0 command line is: 645 646 convert-dtsv0 [<input_filename ... >] 647 648Each file passed will be converted to the new /dts-v1/ version by creating 649a new file with a "v1" appended the filename. 650 651Comments, empty lines, etc. are preserved. 652 653 6542) fdtdump -- Flat Device Tree dumping utility 655 656The fdtdump program prints a readable version of a flat device tree file. 657 658The syntax of the fdtdump command line is: 659 660 fdtdump <DTB-file-name> 661