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