1204431SrajDevice Tree Compiler Manual 2204431Sraj=========================== 3204431Sraj 4204431SrajI - "dtc", the device tree compiler 5204431Sraj 1) Obtaining Sources 6266130Sian 1.1) Submitting Patches 7204431Sraj 2) Description 8204431Sraj 3) Command Line 9204431Sraj 4) Source File 10204431Sraj 4.1) Overview 11204431Sraj 4.2) Properties 12204431Sraj 4.3) Labels and References 13204431Sraj 14204431SrajII - The DT block format 15204431Sraj 1) Header 16204431Sraj 2) Device tree generalities 17204431Sraj 3) Device tree "structure" block 18204431Sraj 4) Device tree "strings" block 19204431Sraj 20204431Sraj 21204431SrajIII - libfdt 22204431Sraj 23204433SrajIV - Utility Tools 24204433Sraj 1) convert-dtsv0 -- Conversion to Version 1 25238742Simp 1) fdtdump 26204431Sraj 27204433Sraj 28204431SrajI - "dtc", the device tree compiler 29204431Sraj=================================== 30204431Sraj 31204431Sraj1) Sources 32204431Sraj 33204431SrajSource code for the Device Tree Compiler can be found at jdl.com. 34204431SrajThe gitweb interface is: 35204431Sraj 36204433Sraj http://git.jdl.com/gitweb/ 37204431Sraj 38204431SrajThe repository is here: 39204431Sraj 40204431Sraj git://www.jdl.com/software/dtc.git 41204431Sraj http://www.jdl.com/software/dtc.git 42204431Sraj 43204431SrajTarballs of the 1.0.0 and latest releases are here: 44204431Sraj 45204433Sraj http://www.jdl.com/software/dtc-v1.2.0.tgz 46204431Sraj http://www.jdl.com/software/dtc-latest.tgz 47204431Sraj 48266130Sian1.1) Submitting Patches 49204431Sraj 50266130SianPatches should be sent to jdl@jdl.com, and CC'ed to 51266130Siandevicetree-discuss@lists.ozlabs.org. 52266130Sian 53204431Sraj2) Description 54204431Sraj 55204431SrajThe Device Tree Compiler, dtc, takes as input a device-tree in 56204431Sraja given format and outputs a device-tree in another format. 57204431SrajTypically, the input format is "dts", a human readable source 58204431Srajformat, and creates a "dtb", or binary format as output. 59204431Sraj 60204431SrajThe currently supported Input Formats are: 61204431Sraj 62204431Sraj - "dtb": "blob" format. A flattened device-tree block with 63204431Sraj header in one binary blob. 64204431Sraj 65204431Sraj - "dts": "source" format. A text file containing a "source" 66204431Sraj for a device-tree. 67204431Sraj 68204431Sraj - "fs" format. A representation equivalent to the output of 69204431Sraj /proc/device-tree where nodes are directories and 70204431Sraj properties are files. 71204431Sraj 72204431SrajThe currently supported Output Formats are: 73204431Sraj 74204431Sraj - "dtb": "blob" format 75204431Sraj 76204431Sraj - "dts": "source" format 77204431Sraj 78204431Sraj - "asm": assembly language file. A file that can be sourced 79204431Sraj by gas to generate a device-tree "blob". That file can 80204431Sraj then simply be added to your Makefile. Additionally, the 81204431Sraj assembly file exports some symbols that can be used. 82204431Sraj 83204431Sraj 84204431Sraj3) Command Line 85204431Sraj 86204431SrajThe syntax of the dtc command line is: 87204431Sraj 88204431Sraj dtc [options] [<input_filename>] 89204431Sraj 90204431SrajOptions: 91204431Sraj 92204431Sraj <input_filename> 93204431Sraj The name of the input source file. If no <input_filename> 94204431Sraj or "-" is given, stdin is used. 95204431Sraj 96204431Sraj -b <number> 97204431Sraj Set the physical boot cpu. 98204431Sraj 99204431Sraj -f 100204431Sraj Force. Try to produce output even if the input tree has errors. 101204431Sraj 102204431Sraj -h 103204431Sraj Emit a brief usage and help message. 104204431Sraj 105204431Sraj -I <input_format> 106204431Sraj The source input format, as listed above. 107204431Sraj 108204431Sraj -o <output_filename> 109204431Sraj The name of the generated output file. Use "-" for stdout. 110204431Sraj 111204431Sraj -O <output_format> 112204431Sraj The generated output format, as listed above. 113204431Sraj 114238742Simp -d <dependency_filename> 115238742Simp Generate a dependency file during compilation. 116238742Simp 117204431Sraj -q 118204431Sraj Quiet: -q suppress warnings, -qq errors, -qqq all 119204431Sraj 120204431Sraj -R <number> 121204431Sraj Make space for <number> reserve map entries 122204431Sraj Relevant for dtb and asm output only. 123204431Sraj 124204431Sraj -S <bytes> 125204431Sraj Ensure the blob at least <bytes> long, adding additional 126204431Sraj space if needed. 127204431Sraj 128204431Sraj -v 129204431Sraj Print DTC version and exit. 130204431Sraj 131204431Sraj -V <output_version> 132204431Sraj Generate output conforming to the given <output_version>. 133204431Sraj By default the most recent version is generated. 134204431Sraj Relevant for dtb and asm output only. 135204431Sraj 136204431Sraj 137204431SrajThe <output_version> defines what version of the "blob" format will be 138204431Srajgenerated. Supported versions are 1, 2, 3, 16 and 17. The default is 139204431Srajalways the most recent version and is likely the highest number. 140204431Sraj 141204431SrajAdditionally, dtc performs various sanity checks on the tree. 142204431Sraj 143204431Sraj 144204431Sraj4) Device Tree Source file 145204431Sraj 146204431Sraj4.1) Overview 147204431Sraj 148204431SrajHere is a very rough overview of the layout of a DTS source file: 149204431Sraj 150204431Sraj 151204431Sraj sourcefile: list_of_memreserve devicetree 152204431Sraj 153204431Sraj memreserve: label 'memreserve' ADDR ADDR ';' 154204431Sraj | label 'memreserve' ADDR '-' ADDR ';' 155204431Sraj 156204431Sraj devicetree: '/' nodedef 157204431Sraj 158204431Sraj nodedef: '{' list_of_property list_of_subnode '}' ';' 159204431Sraj 160204431Sraj property: label PROPNAME '=' propdata ';' 161204431Sraj 162204431Sraj propdata: STRING 163204431Sraj | '<' list_of_cells '>' 164204431Sraj | '[' list_of_bytes ']' 165204431Sraj 166204431Sraj subnode: label nodename nodedef 167204431Sraj 168204431SrajThat structure forms a hierarchical layout of nodes and properties 169204431Srajrooted at an initial node as: 170204431Sraj 171204431Sraj / { 172204431Sraj } 173204431Sraj 174204431SrajBoth classic C style and C++ style comments are supported. 175204431Sraj 176204431SrajSource files may be directly included using the syntax: 177204431Sraj 178204431Sraj /include/ "filename" 179204431Sraj 180204431Sraj 181204431Sraj4.2) Properties 182204431Sraj 183204431SrajProperties are named, possibly labeled, values. Each value 184204431Srajis one of: 185204431Sraj 186204431Sraj - A null-teminated C-like string, 187204431Sraj - A numeric value fitting in 32 bits, 188204431Sraj - A list of 32-bit values 189204431Sraj - A byte sequence 190204431Sraj 191204431SrajHere are some example property definitions: 192204431Sraj 193204431Sraj - A property containing a 0 terminated string 194204431Sraj 195204431Sraj property1 = "string_value"; 196204431Sraj 197204431Sraj - A property containing a numerical 32-bit hexadecimal value 198204431Sraj 199204431Sraj property2 = <1234abcd>; 200204431Sraj 201204431Sraj - A property containing 3 numerical 32-bit hexadecimal values 202204431Sraj 203204431Sraj property3 = <12345678 12345678 deadbeef>; 204204431Sraj 205204431Sraj - A property whose content is an arbitrary array of bytes 206204431Sraj 207204431Sraj property4 = [0a 0b 0c 0d de ea ad be ef]; 208204431Sraj 209204431Sraj 210204431SrajNode may contain sub-nodes to obtain a hierarchical structure. 211204431SrajFor example: 212204431Sraj 213204431Sraj - A child node named "childnode" whose unit name is 214204431Sraj "childnode at address". It it turn has a string property 215204431Sraj called "childprop". 216204431Sraj 217204431Sraj childnode@addresss { 218204431Sraj childprop = "hello\n"; 219204431Sraj }; 220204431Sraj 221204431Sraj 222204431SrajBy default, all numeric values are hexadecimal. Alternate bases 223204431Srajmay be specified using a prefix "d#" for decimal, "b#" for binary, 224204431Srajand "o#" for octal. 225204431Sraj 226204431SrajStrings support common escape sequences from C: "\n", "\t", "\r", 227204431Sraj"\(octal value)", "\x(hex value)". 228204431Sraj 229204431Sraj 230204431Sraj4.3) Labels and References 231204431Sraj 232204431SrajLabels may be applied to nodes or properties. Labels appear 233204431Srajbefore a node name, and are referenced using an ampersand: &label. 234204431SrajAbsolute node path names are also allowed in node references. 235204431Sraj 236204431SrajIn this exmaple, a node is labled "mpic" and then referenced: 237204431Sraj 238204431Sraj mpic: interrupt-controller@40000 { 239204431Sraj ... 240204431Sraj }; 241204431Sraj 242204431Sraj ethernet-phy@3 { 243204431Sraj interrupt-parent = <&mpic>; 244204431Sraj ... 245204431Sraj }; 246204431Sraj 247204431SrajAnd used in properties, lables may appear before or after any value: 248204431Sraj 249204431Sraj randomnode { 250204431Sraj prop: string = data: "mystring\n" data_end: ; 251204431Sraj ... 252204431Sraj }; 253204431Sraj 254204431Sraj 255204431Sraj 256204431SrajII - The DT block format 257204431Sraj======================== 258204431Sraj 259204431SrajThis chapter defines the format of the flattened device-tree 260204431Srajpassed to the kernel. The actual content of the device tree 261204431Srajare described in the kernel documentation in the file 262204431Sraj 263204431Sraj linux-2.6/Documentation/powerpc/booting-without-of.txt 264204431Sraj 265204431SrajYou can find example of code manipulating that format within 266204431Srajthe kernel. For example, the file: 267204431Sraj 268204431Sraj including arch/powerpc/kernel/prom_init.c 269204431Sraj 270204431Srajwill generate a flattened device-tree from the Open Firmware 271204431Srajrepresentation. Other utilities such as fs2dt, which is part of 272204431Srajthe kexec tools, will generate one from a filesystem representation. 273204431SrajSome bootloaders such as U-Boot provide a bit more support by 274204431Srajusing the libfdt code. 275204431Sraj 276204431SrajFor booting the kernel, the device tree block has to be in main memory. 277204431SrajIt has to be accessible in both real mode and virtual mode with no 278204431Srajmapping other than main memory. If you are writing a simple flash 279204431Srajbootloader, it should copy the block to RAM before passing it to 280204431Srajthe kernel. 281204431Sraj 282204431Sraj 283204431Sraj1) Header 284204431Sraj--------- 285204431Sraj 286204431SrajThe kernel is entered with r3 pointing to an area of memory that is 287204431Srajroughly described in include/asm-powerpc/prom.h by the structure 288204431Srajboot_param_header: 289204431Sraj 290204431Sraj struct boot_param_header { 291204431Sraj u32 magic; /* magic word OF_DT_HEADER */ 292204431Sraj u32 totalsize; /* total size of DT block */ 293204431Sraj u32 off_dt_struct; /* offset to structure */ 294204431Sraj u32 off_dt_strings; /* offset to strings */ 295204431Sraj u32 off_mem_rsvmap; /* offset to memory reserve map */ 296204431Sraj u32 version; /* format version */ 297204431Sraj u32 last_comp_version; /* last compatible version */ 298204431Sraj 299204431Sraj /* version 2 fields below */ 300204431Sraj u32 boot_cpuid_phys; /* Which physical CPU id we're 301204431Sraj booting on */ 302204431Sraj /* version 3 fields below */ 303204431Sraj u32 size_dt_strings; /* size of the strings block */ 304204431Sraj 305204431Sraj /* version 17 fields below */ 306204431Sraj u32 size_dt_struct; /* size of the DT structure block */ 307204431Sraj }; 308204431Sraj 309204431SrajAlong with the constants: 310204431Sraj 311204431Sraj /* Definitions used by the flattened device tree */ 312204431Sraj #define OF_DT_HEADER 0xd00dfeed /* 4: version, 313204431Sraj 4: total size */ 314204431Sraj #define OF_DT_BEGIN_NODE 0x1 /* Start node: full name 315204431Sraj */ 316204431Sraj #define OF_DT_END_NODE 0x2 /* End node */ 317204431Sraj #define OF_DT_PROP 0x3 /* Property: name off, 318204431Sraj size, content */ 319204431Sraj #define OF_DT_END 0x9 320204431Sraj 321204431SrajAll values in this header are in big endian format, the various 322204431Srajfields in this header are defined more precisely below. All "offset" 323204431Srajvalues are in bytes from the start of the header; that is from the 324204431Srajvalue of r3. 325204431Sraj 326204431Sraj - magic 327204431Sraj 328204431Sraj This is a magic value that "marks" the beginning of the 329204431Sraj device-tree block header. It contains the value 0xd00dfeed and is 330204431Sraj defined by the constant OF_DT_HEADER 331204431Sraj 332204431Sraj - totalsize 333204431Sraj 334204431Sraj This is the total size of the DT block including the header. The 335204431Sraj "DT" block should enclose all data structures defined in this 336204431Sraj chapter (who are pointed to by offsets in this header). That is, 337204431Sraj the device-tree structure, strings, and the memory reserve map. 338204431Sraj 339204431Sraj - off_dt_struct 340204431Sraj 341204431Sraj This is an offset from the beginning of the header to the start 342204431Sraj of the "structure" part the device tree. (see 2) device tree) 343204431Sraj 344204431Sraj - off_dt_strings 345204431Sraj 346204431Sraj This is an offset from the beginning of the header to the start 347204431Sraj of the "strings" part of the device-tree 348204431Sraj 349204431Sraj - off_mem_rsvmap 350204431Sraj 351204431Sraj This is an offset from the beginning of the header to the start 352204431Sraj of the reserved memory map. This map is a list of pairs of 64- 353204431Sraj bit integers. Each pair is a physical address and a size. The 354204431Sraj list is terminated by an entry of size 0. This map provides the 355204431Sraj kernel with a list of physical memory areas that are "reserved" 356204431Sraj and thus not to be used for memory allocations, especially during 357204431Sraj early initialization. The kernel needs to allocate memory during 358204431Sraj boot for things like un-flattening the device-tree, allocating an 359204431Sraj MMU hash table, etc... Those allocations must be done in such a 360204431Sraj way to avoid overriding critical things like, on Open Firmware 361204431Sraj capable machines, the RTAS instance, or on some pSeries, the TCE 362204431Sraj tables used for the iommu. Typically, the reserve map should 363204431Sraj contain _at least_ this DT block itself (header,total_size). If 364204431Sraj you are passing an initrd to the kernel, you should reserve it as 365204431Sraj well. You do not need to reserve the kernel image itself. The map 366204431Sraj should be 64-bit aligned. 367204431Sraj 368204431Sraj - version 369204431Sraj 370204431Sraj This is the version of this structure. Version 1 stops 371204431Sraj here. Version 2 adds an additional field boot_cpuid_phys. 372204431Sraj Version 3 adds the size of the strings block, allowing the kernel 373204431Sraj to reallocate it easily at boot and free up the unused flattened 374204431Sraj structure after expansion. Version 16 introduces a new more 375204431Sraj "compact" format for the tree itself that is however not backward 376204431Sraj compatible. Version 17 adds an additional field, size_dt_struct, 377204431Sraj allowing it to be reallocated or moved more easily (this is 378204431Sraj particularly useful for bootloaders which need to make 379204431Sraj adjustments to a device tree based on probed information). You 380204431Sraj should always generate a structure of the highest version defined 381204431Sraj at the time of your implementation. Currently that is version 17, 382204431Sraj unless you explicitly aim at being backward compatible. 383204431Sraj 384204431Sraj - last_comp_version 385204431Sraj 386204431Sraj Last compatible version. This indicates down to what version of 387204431Sraj the DT block you are backward compatible. For example, version 2 388204431Sraj is backward compatible with version 1 (that is, a kernel build 389204431Sraj for version 1 will be able to boot with a version 2 format). You 390204431Sraj should put a 1 in this field if you generate a device tree of 391204431Sraj version 1 to 3, or 16 if you generate a tree of version 16 or 17 392204431Sraj using the new unit name format. 393204431Sraj 394204431Sraj - boot_cpuid_phys 395204431Sraj 396204431Sraj This field only exist on version 2 headers. It indicate which 397204431Sraj physical CPU ID is calling the kernel entry point. This is used, 398204431Sraj among others, by kexec. If you are on an SMP system, this value 399204431Sraj should match the content of the "reg" property of the CPU node in 400204431Sraj the device-tree corresponding to the CPU calling the kernel entry 401204431Sraj point (see further chapters for more informations on the required 402204431Sraj device-tree contents) 403204431Sraj 404204431Sraj - size_dt_strings 405204431Sraj 406204431Sraj This field only exists on version 3 and later headers. It 407204431Sraj gives the size of the "strings" section of the device tree (which 408204431Sraj starts at the offset given by off_dt_strings). 409204431Sraj 410204431Sraj - size_dt_struct 411204431Sraj 412204431Sraj This field only exists on version 17 and later headers. It gives 413204431Sraj the size of the "structure" section of the device tree (which 414204431Sraj starts at the offset given by off_dt_struct). 415204431Sraj 416204431SrajSo the typical layout of a DT block (though the various parts don't 417204431Srajneed to be in that order) looks like this (addresses go from top to 418204431Srajbottom): 419204431Sraj 420204431Sraj ------------------------------ 421204431Sraj r3 -> | struct boot_param_header | 422204431Sraj ------------------------------ 423204431Sraj | (alignment gap) (*) | 424204431Sraj ------------------------------ 425204431Sraj | memory reserve map | 426204431Sraj ------------------------------ 427204431Sraj | (alignment gap) | 428204431Sraj ------------------------------ 429204431Sraj | | 430204431Sraj | device-tree structure | 431204431Sraj | | 432204431Sraj ------------------------------ 433204431Sraj | (alignment gap) | 434204431Sraj ------------------------------ 435204431Sraj | | 436204431Sraj | device-tree strings | 437204431Sraj | | 438204431Sraj -----> ------------------------------ 439204431Sraj | 440204431Sraj | 441204431Sraj --- (r3 + totalsize) 442204431Sraj 443204431Sraj (*) The alignment gaps are not necessarily present; their presence 444204431Sraj and size are dependent on the various alignment requirements of 445204431Sraj the individual data blocks. 446204431Sraj 447204431Sraj 448204431Sraj2) Device tree generalities 449204431Sraj--------------------------- 450204431Sraj 451204431SrajThis device-tree itself is separated in two different blocks, a 452204431Srajstructure block and a strings block. Both need to be aligned to a 4 453204431Srajbyte boundary. 454204431Sraj 455204431SrajFirst, let's quickly describe the device-tree concept before detailing 456204431Srajthe storage format. This chapter does _not_ describe the detail of the 457204431Srajrequired types of nodes & properties for the kernel, this is done 458204431Srajlater in chapter III. 459204431Sraj 460204431SrajThe device-tree layout is strongly inherited from the definition of 461204431Srajthe Open Firmware IEEE 1275 device-tree. It's basically a tree of 462204431Srajnodes, each node having two or more named properties. A property can 463204431Srajhave a value or not. 464204431Sraj 465204431SrajIt is a tree, so each node has one and only one parent except for the 466204431Srajroot node who has no parent. 467204431Sraj 468204431SrajA node has 2 names. The actual node name is generally contained in a 469204431Srajproperty of type "name" in the node property list whose value is a 470204431Srajzero terminated string and is mandatory for version 1 to 3 of the 471204431Srajformat definition (as it is in Open Firmware). Version 16 makes it 472204431Srajoptional as it can generate it from the unit name defined below. 473204431Sraj 474204431SrajThere is also a "unit name" that is used to differentiate nodes with 475204431Srajthe same name at the same level, it is usually made of the node 476204431Srajnames, the "@" sign, and a "unit address", which definition is 477204431Srajspecific to the bus type the node sits on. 478204431Sraj 479204431SrajThe unit name doesn't exist as a property per-se but is included in 480204431Srajthe device-tree structure. It is typically used to represent "path" in 481204431Srajthe device-tree. More details about the actual format of these will be 482204431Srajbelow. 483204431Sraj 484204431SrajThe kernel powerpc generic code does not make any formal use of the 485204431Srajunit address (though some board support code may do) so the only real 486204431Srajrequirement here for the unit address is to ensure uniqueness of 487204431Srajthe node unit name at a given level of the tree. Nodes with no notion 488204431Srajof address and no possible sibling of the same name (like /memory or 489204431Sraj/cpus) may omit the unit address in the context of this specification, 490204431Srajor use the "@0" default unit address. The unit name is used to define 491204431Sraja node "full path", which is the concatenation of all parent node 492204431Srajunit names separated with "/". 493204431Sraj 494204431SrajThe root node doesn't have a defined name, and isn't required to have 495204431Sraja name property either if you are using version 3 or earlier of the 496204431Srajformat. It also has no unit address (no @ symbol followed by a unit 497204431Srajaddress). The root node unit name is thus an empty string. The full 498204431Srajpath to the root node is "/". 499204431Sraj 500204431SrajEvery node which actually represents an actual device (that is, a node 501204431Srajwhich isn't only a virtual "container" for more nodes, like "/cpus" 502204431Srajis) is also required to have a "device_type" property indicating the 503204431Srajtype of node . 504204431Sraj 505204431SrajFinally, every node that can be referenced from a property in another 506204431Srajnode is required to have a "linux,phandle" property. Real open 507204431Srajfirmware implementations provide a unique "phandle" value for every 508204431Srajnode that the "prom_init()" trampoline code turns into 509204431Sraj"linux,phandle" properties. However, this is made optional if the 510204431Srajflattened device tree is used directly. An example of a node 511204431Srajreferencing another node via "phandle" is when laying out the 512204431Srajinterrupt tree which will be described in a further version of this 513204431Srajdocument. 514204431Sraj 515204431SrajThis "linux, phandle" property is a 32-bit value that uniquely 516204431Srajidentifies a node. You are free to use whatever values or system of 517204431Srajvalues, internal pointers, or whatever to generate these, the only 518204431Srajrequirement is that every node for which you provide that property has 519204431Sraja unique value for it. 520204431Sraj 521204431SrajHere is an example of a simple device-tree. In this example, an "o" 522204431Srajdesignates a node followed by the node unit name. Properties are 523204431Srajpresented with their name followed by their content. "content" 524204431Srajrepresents an ASCII string (zero terminated) value, while <content> 525204431Srajrepresents a 32-bit hexadecimal value. The various nodes in this 526204431Srajexample will be discussed in a later chapter. At this point, it is 527204431Srajonly meant to give you a idea of what a device-tree looks like. I have 528204431Srajpurposefully kept the "name" and "linux,phandle" properties which 529204431Srajaren't necessary in order to give you a better idea of what the tree 530204431Srajlooks like in practice. 531204431Sraj 532204431Sraj / o device-tree 533204431Sraj |- name = "device-tree" 534204431Sraj |- model = "MyBoardName" 535204431Sraj |- compatible = "MyBoardFamilyName" 536204431Sraj |- #address-cells = <2> 537204431Sraj |- #size-cells = <2> 538204431Sraj |- linux,phandle = <0> 539204431Sraj | 540204431Sraj o cpus 541204431Sraj | | - name = "cpus" 542204431Sraj | | - linux,phandle = <1> 543204431Sraj | | - #address-cells = <1> 544204431Sraj | | - #size-cells = <0> 545204431Sraj | | 546204431Sraj | o PowerPC,970@0 547204431Sraj | |- name = "PowerPC,970" 548204431Sraj | |- device_type = "cpu" 549204431Sraj | |- reg = <0> 550204431Sraj | |- clock-frequency = <5f5e1000> 551204431Sraj | |- 64-bit 552204431Sraj | |- linux,phandle = <2> 553204431Sraj | 554204431Sraj o memory@0 555204431Sraj | |- name = "memory" 556204431Sraj | |- device_type = "memory" 557204431Sraj | |- reg = <00000000 00000000 00000000 20000000> 558204431Sraj | |- linux,phandle = <3> 559204431Sraj | 560204431Sraj o chosen 561204431Sraj |- name = "chosen" 562204431Sraj |- bootargs = "root=/dev/sda2" 563204431Sraj |- linux,phandle = <4> 564204431Sraj 565204431SrajThis tree is almost a minimal tree. It pretty much contains the 566204431Srajminimal set of required nodes and properties to boot a linux kernel; 567204431Srajthat is, some basic model informations at the root, the CPUs, and the 568204431Srajphysical memory layout. It also includes misc information passed 569204431Srajthrough /chosen, like in this example, the platform type (mandatory) 570204431Srajand the kernel command line arguments (optional). 571204431Sraj 572204431SrajThe /cpus/PowerPC,970@0/64-bit property is an example of a 573204431Srajproperty without a value. All other properties have a value. The 574204431Srajsignificance of the #address-cells and #size-cells properties will be 575204431Srajexplained in chapter IV which defines precisely the required nodes and 576204431Srajproperties and their content. 577204431Sraj 578204431Sraj 579204431Sraj3) Device tree "structure" block 580204431Sraj 581204431SrajThe structure of the device tree is a linearized tree structure. The 582204431Sraj"OF_DT_BEGIN_NODE" token starts a new node, and the "OF_DT_END_NODE" 583204431Srajends that node definition. Child nodes are simply defined before 584204431Sraj"OF_DT_END_NODE" (that is nodes within the node). A 'token' is a 32 585204431Srajbit value. The tree has to be "finished" with a OF_DT_END token 586204431Sraj 587204431SrajHere's the basic structure of a single node: 588204431Sraj 589204431Sraj * token OF_DT_BEGIN_NODE (that is 0x00000001) 590204431Sraj * for version 1 to 3, this is the node full path as a zero 591204431Sraj terminated string, starting with "/". For version 16 and later, 592204431Sraj this is the node unit name only (or an empty string for the 593204431Sraj root node) 594204431Sraj * [align gap to next 4 bytes boundary] 595204431Sraj * for each property: 596204431Sraj * token OF_DT_PROP (that is 0x00000003) 597204431Sraj * 32-bit value of property value size in bytes (or 0 if no 598204431Sraj value) 599204431Sraj * 32-bit value of offset in string block of property name 600204431Sraj * property value data if any 601204431Sraj * [align gap to next 4 bytes boundary] 602204431Sraj * [child nodes if any] 603204431Sraj * token OF_DT_END_NODE (that is 0x00000002) 604204431Sraj 605204431SrajSo the node content can be summarized as a start token, a full path, 606204431Sraja list of properties, a list of child nodes, and an end token. Every 607204431Srajchild node is a full node structure itself as defined above. 608204431Sraj 609204431SrajNOTE: The above definition requires that all property definitions for 610204431Sraja particular node MUST precede any subnode definitions for that node. 611204431SrajAlthough the structure would not be ambiguous if properties and 612204431Srajsubnodes were intermingled, the kernel parser requires that the 613204431Srajproperties come first (up until at least 2.6.22). Any tools 614204431Srajmanipulating a flattened tree must take care to preserve this 615204431Srajconstraint. 616204431Sraj 617204431Sraj4) Device tree "strings" block 618204431Sraj 619204431SrajIn order to save space, property names, which are generally redundant, 620204431Srajare stored separately in the "strings" block. This block is simply the 621204431Srajwhole bunch of zero terminated strings for all property names 622204431Srajconcatenated together. The device-tree property definitions in the 623204431Srajstructure block will contain offset values from the beginning of the 624204431Srajstrings block. 625204431Sraj 626204431Sraj 627204431SrajIII - libfdt 628204433Sraj============ 629204431Sraj 630204431SrajThis library should be merged into dtc proper. 631204431SrajThis library should likely be worked into U-Boot and the kernel. 632204433Sraj 633204433Sraj 634204433SrajIV - Utility Tools 635204433Sraj================== 636204433Sraj 637204433Sraj1) convert-dtsv0 -- Conversion to Version 1 638204433Sraj 639204433Srajconvert-dtsv0 is a small utility program which converts (DTS) 640204433SrajDevice Tree Source from the obsolete version 0 to version 1. 641204433Sraj 642204433SrajVersion 1 DTS files are marked by line "/dts-v1/;" at the top of the file. 643204433Sraj 644204433SrajThe syntax of the convert-dtsv0 command line is: 645204433Sraj 646204433Sraj convert-dtsv0 [<input_filename ... >] 647204433Sraj 648204433SrajEach file passed will be converted to the new /dts-v1/ version by creating 649204433Sraja new file with a "v1" appended the filename. 650204433Sraj 651204433SrajComments, empty lines, etc. are preserved. 652204433Sraj 653204433Sraj 654238742Simp2) fdtdump -- Flat Device Tree dumping utility 655204433Sraj 656238742SimpThe fdtdump program prints a readable version of a flat device tree file. 657204433Sraj 658238742SimpThe syntax of the fdtdump command line is: 659204433Sraj 660238742Simp fdtdump <DTB-file-name> 661