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