1 Booting the Linux/ppc kernel without Open Firmware 2 -------------------------------------------------- 3 4(c) 2005 Benjamin Herrenschmidt <benh at kernel.crashing.org>, 5 IBM Corp. 6(c) 2005 Becky Bruce <becky.bruce at freescale.com>, 7 Freescale Semiconductor, FSL SOC and 32-bit additions 8(c) 2006 MontaVista Software, Inc. 9 Flash chip node definition 10 11Table of Contents 12================= 13 14 I - Introduction 15 1) Entry point for arch/arm 16 2) Entry point for arch/powerpc 17 3) Entry point for arch/x86 18 19 II - The DT block format 20 1) Header 21 2) Device tree generalities 22 3) Device tree "structure" block 23 4) Device tree "strings" block 24 25 III - Required content of the device tree 26 1) Note about cells and address representation 27 2) Note about "compatible" properties 28 3) Note about "name" properties 29 4) Note about node and property names and character set 30 5) Required nodes and properties 31 a) The root node 32 b) The /cpus node 33 c) The /cpus/* nodes 34 d) the /memory node(s) 35 e) The /chosen node 36 f) the /soc<SOCname> node 37 38 IV - "dtc", the device tree compiler 39 40 V - Recommendations for a bootloader 41 42 VI - System-on-a-chip devices and nodes 43 1) Defining child nodes of an SOC 44 2) Representing devices without a current OF specification 45 46 VII - Specifying interrupt information for devices 47 1) interrupts property 48 2) interrupt-parent property 49 3) OpenPIC Interrupt Controllers 50 4) ISA Interrupt Controllers 51 52 VIII - Specifying device power management information (sleep property) 53 54 IX - Specifying dma bus information 55 56 Appendix A - Sample SOC node for MPC8540 57 58 59Revision Information 60==================== 61 62 May 18, 2005: Rev 0.1 - Initial draft, no chapter III yet. 63 64 May 19, 2005: Rev 0.2 - Add chapter III and bits & pieces here or 65 clarifies the fact that a lot of things are 66 optional, the kernel only requires a very 67 small device tree, though it is encouraged 68 to provide an as complete one as possible. 69 70 May 24, 2005: Rev 0.3 - Precise that DT block has to be in RAM 71 - Misc fixes 72 - Define version 3 and new format version 16 73 for the DT block (version 16 needs kernel 74 patches, will be fwd separately). 75 String block now has a size, and full path 76 is replaced by unit name for more 77 compactness. 78 linux,phandle is made optional, only nodes 79 that are referenced by other nodes need it. 80 "name" property is now automatically 81 deduced from the unit name 82 83 June 1, 2005: Rev 0.4 - Correct confusion between OF_DT_END and 84 OF_DT_END_NODE in structure definition. 85 - Change version 16 format to always align 86 property data to 4 bytes. Since tokens are 87 already aligned, that means no specific 88 required alignment between property size 89 and property data. The old style variable 90 alignment would make it impossible to do 91 "simple" insertion of properties using 92 memmove (thanks Milton for 93 noticing). Updated kernel patch as well 94 - Correct a few more alignment constraints 95 - Add a chapter about the device-tree 96 compiler and the textural representation of 97 the tree that can be "compiled" by dtc. 98 99 November 21, 2005: Rev 0.5 100 - Additions/generalizations for 32-bit 101 - Changed to reflect the new arch/powerpc 102 structure 103 - Added chapter VI 104 105 106 ToDo: 107 - Add some definitions of interrupt tree (simple/complex) 108 - Add some definitions for PCI host bridges 109 - Add some common address format examples 110 - Add definitions for standard properties and "compatible" 111 names for cells that are not already defined by the existing 112 OF spec. 113 - Compare FSL SOC use of PCI to standard and make sure no new 114 node definition required. 115 - Add more information about node definitions for SOC devices 116 that currently have no standard, like the FSL CPM. 117 118 119I - Introduction 120================ 121 122During the development of the Linux/ppc64 kernel, and more 123specifically, the addition of new platform types outside of the old 124IBM pSeries/iSeries pair, it was decided to enforce some strict rules 125regarding the kernel entry and bootloader <-> kernel interfaces, in 126order to avoid the degeneration that had become the ppc32 kernel entry 127point and the way a new platform should be added to the kernel. The 128legacy iSeries platform breaks those rules as it predates this scheme, 129but no new board support will be accepted in the main tree that 130doesn't follow them properly. In addition, since the advent of the 131arch/powerpc merged architecture for ppc32 and ppc64, new 32-bit 132platforms and 32-bit platforms which move into arch/powerpc will be 133required to use these rules as well. 134 135The main requirement that will be defined in more detail below is 136the presence of a device-tree whose format is defined after Open 137Firmware specification. However, in order to make life easier 138to embedded board vendors, the kernel doesn't require the device-tree 139to represent every device in the system and only requires some nodes 140and properties to be present. This will be described in detail in 141section III, but, for example, the kernel does not require you to 142create a node for every PCI device in the system. It is a requirement 143to have a node for PCI host bridges in order to provide interrupt 144routing information and memory/IO ranges, among others. It is also 145recommended to define nodes for on chip devices and other buses that 146don't specifically fit in an existing OF specification. This creates a 147great flexibility in the way the kernel can then probe those and match 148drivers to device, without having to hard code all sorts of tables. It 149also makes it more flexible for board vendors to do minor hardware 150upgrades without significantly impacting the kernel code or cluttering 151it with special cases. 152 153 1541) Entry point for arch/arm 155--------------------------- 156 157 There is one single entry point to the kernel, at the start 158 of the kernel image. That entry point supports two calling 159 conventions. A summary of the interface is described here. A full 160 description of the boot requirements is documented in 161 Documentation/arm/Booting 162 163 a) ATAGS interface. Minimal information is passed from firmware 164 to the kernel with a tagged list of predefined parameters. 165 166 r0 : 0 167 168 r1 : Machine type number 169 170 r2 : Physical address of tagged list in system RAM 171 172 b) Entry with a flattened device-tree block. Firmware loads the 173 physical address of the flattened device tree block (dtb) into r2, 174 r1 is not used, but it is considered good practice to use a valid 175 machine number as described in Documentation/arm/Booting. 176 177 r0 : 0 178 179 r1 : Valid machine type number. When using a device tree, 180 a single machine type number will often be assigned to 181 represent a class or family of SoCs. 182 183 r2 : physical pointer to the device-tree block 184 (defined in chapter II) in RAM. Device tree can be located 185 anywhere in system RAM, but it should be aligned on a 64 bit 186 boundary. 187 188 The kernel will differentiate between ATAGS and device tree booting by 189 reading the memory pointed to by r2 and looking for either the flattened 190 device tree block magic value (0xd00dfeed) or the ATAG_CORE value at 191 offset 0x4 from r2 (0x54410001). 192 1932) Entry point for arch/powerpc 194------------------------------- 195 196 There is one single entry point to the kernel, at the start 197 of the kernel image. That entry point supports two calling 198 conventions: 199 200 a) Boot from Open Firmware. If your firmware is compatible 201 with Open Firmware (IEEE 1275) or provides an OF compatible 202 client interface API (support for "interpret" callback of 203 forth words isn't required), you can enter the kernel with: 204 205 r5 : OF callback pointer as defined by IEEE 1275 206 bindings to powerpc. Only the 32-bit client interface 207 is currently supported 208 209 r3, r4 : address & length of an initrd if any or 0 210 211 The MMU is either on or off; the kernel will run the 212 trampoline located in arch/powerpc/kernel/prom_init.c to 213 extract the device-tree and other information from open 214 firmware and build a flattened device-tree as described 215 in b). prom_init() will then re-enter the kernel using 216 the second method. This trampoline code runs in the 217 context of the firmware, which is supposed to handle all 218 exceptions during that time. 219 220 b) Direct entry with a flattened device-tree block. This entry 221 point is called by a) after the OF trampoline and can also be 222 called directly by a bootloader that does not support the Open 223 Firmware client interface. It is also used by "kexec" to 224 implement "hot" booting of a new kernel from a previous 225 running one. This method is what I will describe in more 226 details in this document, as method a) is simply standard Open 227 Firmware, and thus should be implemented according to the 228 various standard documents defining it and its binding to the 229 PowerPC platform. The entry point definition then becomes: 230 231 r3 : physical pointer to the device-tree block 232 (defined in chapter II) in RAM 233 234 r4 : physical pointer to the kernel itself. This is 235 used by the assembly code to properly disable the MMU 236 in case you are entering the kernel with MMU enabled 237 and a non-1:1 mapping. 238 239 r5 : NULL (as to differentiate with method a) 240 241 Note about SMP entry: Either your firmware puts your other 242 CPUs in some sleep loop or spin loop in ROM where you can get 243 them out via a soft reset or some other means, in which case 244 you don't need to care, or you'll have to enter the kernel 245 with all CPUs. The way to do that with method b) will be 246 described in a later revision of this document. 247 248 Board supports (platforms) are not exclusive config options. An 249 arbitrary set of board supports can be built in a single kernel 250 image. The kernel will "know" what set of functions to use for a 251 given platform based on the content of the device-tree. Thus, you 252 should: 253 254 a) add your platform support as a _boolean_ option in 255 arch/powerpc/Kconfig, following the example of PPC_PSERIES, 256 PPC_PMAC and PPC_MAPLE. The later is probably a good 257 example of a board support to start from. 258 259 b) create your main platform file as 260 "arch/powerpc/platforms/myplatform/myboard_setup.c" and add it 261 to the Makefile under the condition of your CONFIG_ 262 option. This file will define a structure of type "ppc_md" 263 containing the various callbacks that the generic code will 264 use to get to your platform specific code 265 266 A kernel image may support multiple platforms, but only if the 267 platforms feature the same core architecture. A single kernel build 268 cannot support both configurations with Book E and configurations 269 with classic Powerpc architectures. 270 2713) Entry point for arch/x86 272------------------------------- 273 274 There is one single 32bit entry point to the kernel at code32_start, 275 the decompressor (the real mode entry point goes to the same 32bit 276 entry point once it switched into protected mode). That entry point 277 supports one calling convention which is documented in 278 Documentation/x86/boot.txt 279 The physical pointer to the device-tree block (defined in chapter II) 280 is passed via setup_data which requires at least boot protocol 2.09. 281 The type filed is defined as 282 283 #define SETUP_DTB 2 284 285 This device-tree is used as an extension to the "boot page". As such it 286 does not parse / consider data which is already covered by the boot 287 page. This includes memory size, reserved ranges, command line arguments 288 or initrd address. It simply holds information which can not be retrieved 289 otherwise like interrupt routing or a list of devices behind an I2C bus. 290 291II - The DT block format 292======================== 293 294 295This chapter defines the actual format of the flattened device-tree 296passed to the kernel. The actual content of it and kernel requirements 297are described later. You can find example of code manipulating that 298format in various places, including arch/powerpc/kernel/prom_init.c 299which will generate a flattened device-tree from the Open Firmware 300representation, or the fs2dt utility which is part of the kexec tools 301which will generate one from a filesystem representation. It is 302expected that a bootloader like uboot provides a bit more support, 303that will be discussed later as well. 304 305Note: The block has to be in main memory. It has to be accessible in 306both real mode and virtual mode with no mapping other than main 307memory. If you are writing a simple flash bootloader, it should copy 308the block to RAM before passing it to the kernel. 309 310 3111) Header 312--------- 313 314 The kernel is passed the physical address pointing to an area of memory 315 that is roughly described in include/linux/of_fdt.h by the structure 316 boot_param_header: 317 318struct boot_param_header { 319 u32 magic; /* magic word OF_DT_HEADER */ 320 u32 totalsize; /* total size of DT block */ 321 u32 off_dt_struct; /* offset to structure */ 322 u32 off_dt_strings; /* offset to strings */ 323 u32 off_mem_rsvmap; /* offset to memory reserve map 324 */ 325 u32 version; /* format version */ 326 u32 last_comp_version; /* last compatible version */ 327 328 /* version 2 fields below */ 329 u32 boot_cpuid_phys; /* Which physical CPU id we're 330 booting on */ 331 /* version 3 fields below */ 332 u32 size_dt_strings; /* size of the strings block */ 333 334 /* version 17 fields below */ 335 u32 size_dt_struct; /* size of the DT structure block */ 336}; 337 338 Along with the constants: 339 340/* Definitions used by the flattened device tree */ 341#define OF_DT_HEADER 0xd00dfeed /* 4: version, 342 4: total size */ 343#define OF_DT_BEGIN_NODE 0x1 /* Start node: full name 344 */ 345#define OF_DT_END_NODE 0x2 /* End node */ 346#define OF_DT_PROP 0x3 /* Property: name off, 347 size, content */ 348#define OF_DT_END 0x9 349 350 All values in this header are in big endian format, the various 351 fields in this header are defined more precisely below. All 352 "offset" values are in bytes from the start of the header; that is 353 from the physical base address of the device tree block. 354 355 - magic 356 357 This is a magic value that "marks" the beginning of the 358 device-tree block header. It contains the value 0xd00dfeed and is 359 defined by the constant OF_DT_HEADER 360 361 - totalsize 362 363 This is the total size of the DT block including the header. The 364 "DT" block should enclose all data structures defined in this 365 chapter (who are pointed to by offsets in this header). That is, 366 the device-tree structure, strings, and the memory reserve map. 367 368 - off_dt_struct 369 370 This is an offset from the beginning of the header to the start 371 of the "structure" part the device tree. (see 2) device tree) 372 373 - off_dt_strings 374 375 This is an offset from the beginning of the header to the start 376 of the "strings" part of the device-tree 377 378 - off_mem_rsvmap 379 380 This is an offset from the beginning of the header to the start 381 of the reserved memory map. This map is a list of pairs of 64- 382 bit integers. Each pair is a physical address and a size. The 383 list is terminated by an entry of size 0. This map provides the 384 kernel with a list of physical memory areas that are "reserved" 385 and thus not to be used for memory allocations, especially during 386 early initialization. The kernel needs to allocate memory during 387 boot for things like un-flattening the device-tree, allocating an 388 MMU hash table, etc... Those allocations must be done in such a 389 way to avoid overriding critical things like, on Open Firmware 390 capable machines, the RTAS instance, or on some pSeries, the TCE 391 tables used for the iommu. Typically, the reserve map should 392 contain _at least_ this DT block itself (header,total_size). If 393 you are passing an initrd to the kernel, you should reserve it as 394 well. You do not need to reserve the kernel image itself. The map 395 should be 64-bit aligned. 396 397 - version 398 399 This is the version of this structure. Version 1 stops 400 here. Version 2 adds an additional field boot_cpuid_phys. 401 Version 3 adds the size of the strings block, allowing the kernel 402 to reallocate it easily at boot and free up the unused flattened 403 structure after expansion. Version 16 introduces a new more 404 "compact" format for the tree itself that is however not backward 405 compatible. Version 17 adds an additional field, size_dt_struct, 406 allowing it to be reallocated or moved more easily (this is 407 particularly useful for bootloaders which need to make 408 adjustments to a device tree based on probed information). You 409 should always generate a structure of the highest version defined 410 at the time of your implementation. Currently that is version 17, 411 unless you explicitly aim at being backward compatible. 412 413 - last_comp_version 414 415 Last compatible version. This indicates down to what version of 416 the DT block you are backward compatible. For example, version 2 417 is backward compatible with version 1 (that is, a kernel build 418 for version 1 will be able to boot with a version 2 format). You 419 should put a 1 in this field if you generate a device tree of 420 version 1 to 3, or 16 if you generate a tree of version 16 or 17 421 using the new unit name format. 422 423 - boot_cpuid_phys 424 425 This field only exist on version 2 headers. It indicate which 426 physical CPU ID is calling the kernel entry point. This is used, 427 among others, by kexec. If you are on an SMP system, this value 428 should match the content of the "reg" property of the CPU node in 429 the device-tree corresponding to the CPU calling the kernel entry 430 point (see further chapters for more information on the required 431 device-tree contents) 432 433 - size_dt_strings 434 435 This field only exists on version 3 and later headers. It 436 gives the size of the "strings" section of the device tree (which 437 starts at the offset given by off_dt_strings). 438 439 - size_dt_struct 440 441 This field only exists on version 17 and later headers. It gives 442 the size of the "structure" section of the device tree (which 443 starts at the offset given by off_dt_struct). 444 445 So the typical layout of a DT block (though the various parts don't 446 need to be in that order) looks like this (addresses go from top to 447 bottom): 448 449 450 ------------------------------ 451 base -> | struct boot_param_header | 452 ------------------------------ 453 | (alignment gap) (*) | 454 ------------------------------ 455 | memory reserve map | 456 ------------------------------ 457 | (alignment gap) | 458 ------------------------------ 459 | | 460 | device-tree structure | 461 | | 462 ------------------------------ 463 | (alignment gap) | 464 ------------------------------ 465 | | 466 | device-tree strings | 467 | | 468 -----> ------------------------------ 469 | 470 | 471 --- (base + totalsize) 472 473 (*) The alignment gaps are not necessarily present; their presence 474 and size are dependent on the various alignment requirements of 475 the individual data blocks. 476 477 4782) Device tree generalities 479--------------------------- 480 481This device-tree itself is separated in two different blocks, a 482structure block and a strings block. Both need to be aligned to a 4 483byte boundary. 484 485First, let's quickly describe the device-tree concept before detailing 486the storage format. This chapter does _not_ describe the detail of the 487required types of nodes & properties for the kernel, this is done 488later in chapter III. 489 490The device-tree layout is strongly inherited from the definition of 491the Open Firmware IEEE 1275 device-tree. It's basically a tree of 492nodes, each node having two or more named properties. A property can 493have a value or not. 494 495It is a tree, so each node has one and only one parent except for the 496root node who has no parent. 497 498A node has 2 names. The actual node name is generally contained in a 499property of type "name" in the node property list whose value is a 500zero terminated string and is mandatory for version 1 to 3 of the 501format definition (as it is in Open Firmware). Version 16 makes it 502optional as it can generate it from the unit name defined below. 503 504There is also a "unit name" that is used to differentiate nodes with 505the same name at the same level, it is usually made of the node 506names, the "@" sign, and a "unit address", which definition is 507specific to the bus type the node sits on. 508 509The unit name doesn't exist as a property per-se but is included in 510the device-tree structure. It is typically used to represent "path" in 511the device-tree. More details about the actual format of these will be 512below. 513 514The kernel generic code does not make any formal use of the 515unit address (though some board support code may do) so the only real 516requirement here for the unit address is to ensure uniqueness of 517the node unit name at a given level of the tree. Nodes with no notion 518of address and no possible sibling of the same name (like /memory or 519/cpus) may omit the unit address in the context of this specification, 520or use the "@0" default unit address. The unit name is used to define 521a node "full path", which is the concatenation of all parent node 522unit names separated with "/". 523 524The root node doesn't have a defined name, and isn't required to have 525a name property either if you are using version 3 or earlier of the 526format. It also has no unit address (no @ symbol followed by a unit 527address). The root node unit name is thus an empty string. The full 528path to the root node is "/". 529 530Every node which actually represents an actual device (that is, a node 531which isn't only a virtual "container" for more nodes, like "/cpus" 532is) is also required to have a "compatible" property indicating the 533specific hardware and an optional list of devices it is fully 534backwards compatible with. 535 536Finally, every node that can be referenced from a property in another 537node is required to have either a "phandle" or a "linux,phandle" 538property. Real Open Firmware implementations provide a unique 539"phandle" value for every node that the "prom_init()" trampoline code 540turns into "linux,phandle" properties. However, this is made optional 541if the flattened device tree is used directly. An example of a node 542referencing another node via "phandle" is when laying out the 543interrupt tree which will be described in a further version of this 544document. 545 546The "phandle" property is a 32-bit value that uniquely 547identifies a node. You are free to use whatever values or system of 548values, internal pointers, or whatever to generate these, the only 549requirement is that every node for which you provide that property has 550a unique value for it. 551 552Here is an example of a simple device-tree. In this example, an "o" 553designates a node followed by the node unit name. Properties are 554presented with their name followed by their content. "content" 555represents an ASCII string (zero terminated) value, while <content> 556represents a 32-bit value, specified in decimal or hexadecimal (the 557latter prefixed 0x). The various nodes in this example will be 558discussed in a later chapter. At this point, it is only meant to give 559you a idea of what a device-tree looks like. I have purposefully kept 560the "name" and "linux,phandle" properties which aren't necessary in 561order to give you a better idea of what the tree looks like in 562practice. 563 564 / o device-tree 565 |- name = "device-tree" 566 |- model = "MyBoardName" 567 |- compatible = "MyBoardFamilyName" 568 |- #address-cells = <2> 569 |- #size-cells = <2> 570 |- linux,phandle = <0> 571 | 572 o cpus 573 | | - name = "cpus" 574 | | - linux,phandle = <1> 575 | | - #address-cells = <1> 576 | | - #size-cells = <0> 577 | | 578 | o PowerPC,970@0 579 | |- name = "PowerPC,970" 580 | |- device_type = "cpu" 581 | |- reg = <0> 582 | |- clock-frequency = <0x5f5e1000> 583 | |- 64-bit 584 | |- linux,phandle = <2> 585 | 586 o memory@0 587 | |- name = "memory" 588 | |- device_type = "memory" 589 | |- reg = <0x00000000 0x00000000 0x00000000 0x20000000> 590 | |- linux,phandle = <3> 591 | 592 o chosen 593 |- name = "chosen" 594 |- bootargs = "root=/dev/sda2" 595 |- linux,phandle = <4> 596 597This tree is almost a minimal tree. It pretty much contains the 598minimal set of required nodes and properties to boot a linux kernel; 599that is, some basic model information at the root, the CPUs, and the 600physical memory layout. It also includes misc information passed 601through /chosen, like in this example, the platform type (mandatory) 602and the kernel command line arguments (optional). 603 604The /cpus/PowerPC,970@0/64-bit property is an example of a 605property without a value. All other properties have a value. The 606significance of the #address-cells and #size-cells properties will be 607explained in chapter IV which defines precisely the required nodes and 608properties and their content. 609 610 6113) Device tree "structure" block 612 613The structure of the device tree is a linearized tree structure. The 614"OF_DT_BEGIN_NODE" token starts a new node, and the "OF_DT_END_NODE" 615ends that node definition. Child nodes are simply defined before 616"OF_DT_END_NODE" (that is nodes within the node). A 'token' is a 32 617bit value. The tree has to be "finished" with a OF_DT_END token 618 619Here's the basic structure of a single node: 620 621 * token OF_DT_BEGIN_NODE (that is 0x00000001) 622 * for version 1 to 3, this is the node full path as a zero 623 terminated string, starting with "/". For version 16 and later, 624 this is the node unit name only (or an empty string for the 625 root node) 626 * [align gap to next 4 bytes boundary] 627 * for each property: 628 * token OF_DT_PROP (that is 0x00000003) 629 * 32-bit value of property value size in bytes (or 0 if no 630 value) 631 * 32-bit value of offset in string block of property name 632 * property value data if any 633 * [align gap to next 4 bytes boundary] 634 * [child nodes if any] 635 * token OF_DT_END_NODE (that is 0x00000002) 636 637So the node content can be summarized as a start token, a full path, 638a list of properties, a list of child nodes, and an end token. Every 639child node is a full node structure itself as defined above. 640 641NOTE: The above definition requires that all property definitions for 642a particular node MUST precede any subnode definitions for that node. 643Although the structure would not be ambiguous if properties and 644subnodes were intermingled, the kernel parser requires that the 645properties come first (up until at least 2.6.22). Any tools 646manipulating a flattened tree must take care to preserve this 647constraint. 648 6494) Device tree "strings" block 650 651In order to save space, property names, which are generally redundant, 652are stored separately in the "strings" block. This block is simply the 653whole bunch of zero terminated strings for all property names 654concatenated together. The device-tree property definitions in the 655structure block will contain offset values from the beginning of the 656strings block. 657 658 659III - Required content of the device tree 660========================================= 661 662WARNING: All "linux,*" properties defined in this document apply only 663to a flattened device-tree. If your platform uses a real 664implementation of Open Firmware or an implementation compatible with 665the Open Firmware client interface, those properties will be created 666by the trampoline code in the kernel's prom_init() file. For example, 667that's where you'll have to add code to detect your board model and 668set the platform number. However, when using the flattened device-tree 669entry point, there is no prom_init() pass, and thus you have to 670provide those properties yourself. 671 672 6731) Note about cells and address representation 674---------------------------------------------- 675 676The general rule is documented in the various Open Firmware 677documentations. If you choose to describe a bus with the device-tree 678and there exist an OF bus binding, then you should follow the 679specification. However, the kernel does not require every single 680device or bus to be described by the device tree. 681 682In general, the format of an address for a device is defined by the 683parent bus type, based on the #address-cells and #size-cells 684properties. Note that the parent's parent definitions of #address-cells 685and #size-cells are not inherited so every node with children must specify 686them. The kernel requires the root node to have those properties defining 687addresses format for devices directly mapped on the processor bus. 688 689Those 2 properties define 'cells' for representing an address and a 690size. A "cell" is a 32-bit number. For example, if both contain 2 691like the example tree given above, then an address and a size are both 692composed of 2 cells, and each is a 64-bit number (cells are 693concatenated and expected to be in big endian format). Another example 694is the way Apple firmware defines them, with 2 cells for an address 695and one cell for a size. Most 32-bit implementations should define 696#address-cells and #size-cells to 1, which represents a 32-bit value. 697Some 32-bit processors allow for physical addresses greater than 32 698bits; these processors should define #address-cells as 2. 699 700"reg" properties are always a tuple of the type "address size" where 701the number of cells of address and size is specified by the bus 702#address-cells and #size-cells. When a bus supports various address 703spaces and other flags relative to a given address allocation (like 704prefetchable, etc...) those flags are usually added to the top level 705bits of the physical address. For example, a PCI physical address is 706made of 3 cells, the bottom two containing the actual address itself 707while the top cell contains address space indication, flags, and pci 708bus & device numbers. 709 710For buses that support dynamic allocation, it's the accepted practice 711to then not provide the address in "reg" (keep it 0) though while 712providing a flag indicating the address is dynamically allocated, and 713then, to provide a separate "assigned-addresses" property that 714contains the fully allocated addresses. See the PCI OF bindings for 715details. 716 717In general, a simple bus with no address space bits and no dynamic 718allocation is preferred if it reflects your hardware, as the existing 719kernel address parsing functions will work out of the box. If you 720define a bus type with a more complex address format, including things 721like address space bits, you'll have to add a bus translator to the 722prom_parse.c file of the recent kernels for your bus type. 723 724The "reg" property only defines addresses and sizes (if #size-cells is 725non-0) within a given bus. In order to translate addresses upward 726(that is into parent bus addresses, and possibly into CPU physical 727addresses), all buses must contain a "ranges" property. If the 728"ranges" property is missing at a given level, it's assumed that 729translation isn't possible, i.e., the registers are not visible on the 730parent bus. The format of the "ranges" property for a bus is a list 731of: 732 733 bus address, parent bus address, size 734 735"bus address" is in the format of the bus this bus node is defining, 736that is, for a PCI bridge, it would be a PCI address. Thus, (bus 737address, size) defines a range of addresses for child devices. "parent 738bus address" is in the format of the parent bus of this bus. For 739example, for a PCI host controller, that would be a CPU address. For a 740PCI<->ISA bridge, that would be a PCI address. It defines the base 741address in the parent bus where the beginning of that range is mapped. 742 743For new 64-bit board support, I recommend either the 2/2 format or 744Apple's 2/1 format which is slightly more compact since sizes usually 745fit in a single 32-bit word. New 32-bit board support should use a 7461/1 format, unless the processor supports physical addresses greater 747than 32-bits, in which case a 2/1 format is recommended. 748 749Alternatively, the "ranges" property may be empty, indicating that the 750registers are visible on the parent bus using an identity mapping 751translation. In other words, the parent bus address space is the same 752as the child bus address space. 753 7542) Note about "compatible" properties 755------------------------------------- 756 757These properties are optional, but recommended in devices and the root 758node. The format of a "compatible" property is a list of concatenated 759zero terminated strings. They allow a device to express its 760compatibility with a family of similar devices, in some cases, 761allowing a single driver to match against several devices regardless 762of their actual names. 763 7643) Note about "name" properties 765------------------------------- 766 767While earlier users of Open Firmware like OldWorld macintoshes tended 768to use the actual device name for the "name" property, it's nowadays 769considered a good practice to use a name that is closer to the device 770class (often equal to device_type). For example, nowadays, Ethernet 771controllers are named "ethernet", an additional "model" property 772defining precisely the chip type/model, and "compatible" property 773defining the family in case a single driver can driver more than one 774of these chips. However, the kernel doesn't generally put any 775restriction on the "name" property; it is simply considered good 776practice to follow the standard and its evolutions as closely as 777possible. 778 779Note also that the new format version 16 makes the "name" property 780optional. If it's absent for a node, then the node's unit name is then 781used to reconstruct the name. That is, the part of the unit name 782before the "@" sign is used (or the entire unit name if no "@" sign 783is present). 784 7854) Note about node and property names and character set 786------------------------------------------------------- 787 788While Open Firmware provides more flexible usage of 8859-1, this 789specification enforces more strict rules. Nodes and properties should 790be comprised only of ASCII characters 'a' to 'z', '0' to 791'9', ',', '.', '_', '+', '#', '?', and '-'. Node names additionally 792allow uppercase characters 'A' to 'Z' (property names should be 793lowercase. The fact that vendors like Apple don't respect this rule is 794irrelevant here). Additionally, node and property names should always 795begin with a character in the range 'a' to 'z' (or 'A' to 'Z' for node 796names). 797 798The maximum number of characters for both nodes and property names 799is 31. In the case of node names, this is only the leftmost part of 800a unit name (the pure "name" property), it doesn't include the unit 801address which can extend beyond that limit. 802 803 8045) Required nodes and properties 805-------------------------------- 806 These are all that are currently required. However, it is strongly 807 recommended that you expose PCI host bridges as documented in the 808 PCI binding to Open Firmware, and your interrupt tree as documented 809 in OF interrupt tree specification. 810 811 a) The root node 812 813 The root node requires some properties to be present: 814 815 - model : this is your board name/model 816 - #address-cells : address representation for "root" devices 817 - #size-cells: the size representation for "root" devices 818 - compatible : the board "family" generally finds its way here, 819 for example, if you have 2 board models with a similar layout, 820 that typically get driven by the same platform code in the 821 kernel, you would specify the exact board model in the 822 compatible property followed by an entry that represents the SoC 823 model. 824 825 The root node is also generally where you add additional properties 826 specific to your board like the serial number if any, that sort of 827 thing. It is recommended that if you add any "custom" property whose 828 name may clash with standard defined ones, you prefix them with your 829 vendor name and a comma. 830 831 b) The /cpus node 832 833 This node is the parent of all individual CPU nodes. It doesn't 834 have any specific requirements, though it's generally good practice 835 to have at least: 836 837 #address-cells = <00000001> 838 #size-cells = <00000000> 839 840 This defines that the "address" for a CPU is a single cell, and has 841 no meaningful size. This is not necessary but the kernel will assume 842 that format when reading the "reg" properties of a CPU node, see 843 below 844 845 c) The /cpus/* nodes 846 847 So under /cpus, you are supposed to create a node for every CPU on 848 the machine. There is no specific restriction on the name of the 849 CPU, though it's common to call it <architecture>,<core>. For 850 example, Apple uses PowerPC,G5 while IBM uses PowerPC,970FX. 851 However, the Generic Names convention suggests that it would be 852 better to simply use 'cpu' for each cpu node and use the compatible 853 property to identify the specific cpu core. 854 855 Required properties: 856 857 - device_type : has to be "cpu" 858 - reg : This is the physical CPU number, it's a single 32-bit cell 859 and is also used as-is as the unit number for constructing the 860 unit name in the full path. For example, with 2 CPUs, you would 861 have the full path: 862 /cpus/PowerPC,970FX@0 863 /cpus/PowerPC,970FX@1 864 (unit addresses do not require leading zeroes) 865 - d-cache-block-size : one cell, L1 data cache block size in bytes (*) 866 - i-cache-block-size : one cell, L1 instruction cache block size in 867 bytes 868 - d-cache-size : one cell, size of L1 data cache in bytes 869 - i-cache-size : one cell, size of L1 instruction cache in bytes 870 871(*) The cache "block" size is the size on which the cache management 872instructions operate. Historically, this document used the cache 873"line" size here which is incorrect. The kernel will prefer the cache 874block size and will fallback to cache line size for backward 875compatibility. 876 877 Recommended properties: 878 879 - timebase-frequency : a cell indicating the frequency of the 880 timebase in Hz. This is not directly used by the generic code, 881 but you are welcome to copy/paste the pSeries code for setting 882 the kernel timebase/decrementer calibration based on this 883 value. 884 - clock-frequency : a cell indicating the CPU core clock frequency 885 in Hz. A new property will be defined for 64-bit values, but if 886 your frequency is < 4Ghz, one cell is enough. Here as well as 887 for the above, the common code doesn't use that property, but 888 you are welcome to re-use the pSeries or Maple one. A future 889 kernel version might provide a common function for this. 890 - d-cache-line-size : one cell, L1 data cache line size in bytes 891 if different from the block size 892 - i-cache-line-size : one cell, L1 instruction cache line size in 893 bytes if different from the block size 894 895 You are welcome to add any property you find relevant to your board, 896 like some information about the mechanism used to soft-reset the 897 CPUs. For example, Apple puts the GPIO number for CPU soft reset 898 lines in there as a "soft-reset" property since they start secondary 899 CPUs by soft-resetting them. 900 901 902 d) the /memory node(s) 903 904 To define the physical memory layout of your board, you should 905 create one or more memory node(s). You can either create a single 906 node with all memory ranges in its reg property, or you can create 907 several nodes, as you wish. The unit address (@ part) used for the 908 full path is the address of the first range of memory defined by a 909 given node. If you use a single memory node, this will typically be 910 @0. 911 912 Required properties: 913 914 - device_type : has to be "memory" 915 - reg : This property contains all the physical memory ranges of 916 your board. It's a list of addresses/sizes concatenated 917 together, with the number of cells of each defined by the 918 #address-cells and #size-cells of the root node. For example, 919 with both of these properties being 2 like in the example given 920 earlier, a 970 based machine with 6Gb of RAM could typically 921 have a "reg" property here that looks like: 922 923 00000000 00000000 00000000 80000000 924 00000001 00000000 00000001 00000000 925 926 That is a range starting at 0 of 0x80000000 bytes and a range 927 starting at 0x100000000 and of 0x100000000 bytes. You can see 928 that there is no memory covering the IO hole between 2Gb and 929 4Gb. Some vendors prefer splitting those ranges into smaller 930 segments, but the kernel doesn't care. 931 932 e) The /chosen node 933 934 This node is a bit "special". Normally, that's where Open Firmware 935 puts some variable environment information, like the arguments, or 936 the default input/output devices. 937 938 This specification makes a few of these mandatory, but also defines 939 some linux-specific properties that would be normally constructed by 940 the prom_init() trampoline when booting with an OF client interface, 941 but that you have to provide yourself when using the flattened format. 942 943 Recommended properties: 944 945 - bootargs : This zero-terminated string is passed as the kernel 946 command line 947 - linux,stdout-path : This is the full path to your standard 948 console device if any. Typically, if you have serial devices on 949 your board, you may want to put the full path to the one set as 950 the default console in the firmware here, for the kernel to pick 951 it up as its own default console. 952 953 Note that u-boot creates and fills in the chosen node for platforms 954 that use it. 955 956 (Note: a practice that is now obsolete was to include a property 957 under /chosen called interrupt-controller which had a phandle value 958 that pointed to the main interrupt controller) 959 960 f) the /soc<SOCname> node 961 962 This node is used to represent a system-on-a-chip (SoC) and must be 963 present if the processor is a SoC. The top-level soc node contains 964 information that is global to all devices on the SoC. The node name 965 should contain a unit address for the SoC, which is the base address 966 of the memory-mapped register set for the SoC. The name of an SoC 967 node should start with "soc", and the remainder of the name should 968 represent the part number for the soc. For example, the MPC8540's 969 soc node would be called "soc8540". 970 971 Required properties: 972 973 - ranges : Should be defined as specified in 1) to describe the 974 translation of SoC addresses for memory mapped SoC registers. 975 - bus-frequency: Contains the bus frequency for the SoC node. 976 Typically, the value of this field is filled in by the boot 977 loader. 978 - compatible : Exact model of the SoC 979 980 981 Recommended properties: 982 983 - reg : This property defines the address and size of the 984 memory-mapped registers that are used for the SOC node itself. 985 It does not include the child device registers - these will be 986 defined inside each child node. The address specified in the 987 "reg" property should match the unit address of the SOC node. 988 - #address-cells : Address representation for "soc" devices. The 989 format of this field may vary depending on whether or not the 990 device registers are memory mapped. For memory mapped 991 registers, this field represents the number of cells needed to 992 represent the address of the registers. For SOCs that do not 993 use MMIO, a special address format should be defined that 994 contains enough cells to represent the required information. 995 See 1) above for more details on defining #address-cells. 996 - #size-cells : Size representation for "soc" devices 997 - #interrupt-cells : Defines the width of cells used to represent 998 interrupts. Typically this value is <2>, which includes a 999 32-bit number that represents the interrupt number, and a 1000 32-bit number that represents the interrupt sense and level. 1001 This field is only needed if the SOC contains an interrupt 1002 controller. 1003 1004 The SOC node may contain child nodes for each SOC device that the 1005 platform uses. Nodes should not be created for devices which exist 1006 on the SOC but are not used by a particular platform. See chapter VI 1007 for more information on how to specify devices that are part of a SOC. 1008 1009 Example SOC node for the MPC8540: 1010 1011 soc8540@e0000000 { 1012 #address-cells = <1>; 1013 #size-cells = <1>; 1014 #interrupt-cells = <2>; 1015 device_type = "soc"; 1016 ranges = <0x00000000 0xe0000000 0x00100000> 1017 reg = <0xe0000000 0x00003000>; 1018 bus-frequency = <0>; 1019 } 1020 1021 1022 1023IV - "dtc", the device tree compiler 1024==================================== 1025 1026 1027dtc source code can be found at 1028<http://git.jdl.com/gitweb/?p=dtc.git> 1029 1030WARNING: This version is still in early development stage; the 1031resulting device-tree "blobs" have not yet been validated with the 1032kernel. The current generated block lacks a useful reserve map (it will 1033be fixed to generate an empty one, it's up to the bootloader to fill 1034it up) among others. The error handling needs work, bugs are lurking, 1035etc... 1036 1037dtc basically takes a device-tree in a given format and outputs a 1038device-tree in another format. The currently supported formats are: 1039 1040 Input formats: 1041 ------------- 1042 1043 - "dtb": "blob" format, that is a flattened device-tree block 1044 with 1045 header all in a binary blob. 1046 - "dts": "source" format. This is a text file containing a 1047 "source" for a device-tree. The format is defined later in this 1048 chapter. 1049 - "fs" format. This is a representation equivalent to the 1050 output of /proc/device-tree, that is nodes are directories and 1051 properties are files 1052 1053 Output formats: 1054 --------------- 1055 1056 - "dtb": "blob" format 1057 - "dts": "source" format 1058 - "asm": assembly language file. This is a file that can be 1059 sourced by gas to generate a device-tree "blob". That file can 1060 then simply be added to your Makefile. Additionally, the 1061 assembly file exports some symbols that can be used. 1062 1063 1064The syntax of the dtc tool is 1065 1066 dtc [-I <input-format>] [-O <output-format>] 1067 [-o output-filename] [-V output_version] input_filename 1068 1069 1070The "output_version" defines what version of the "blob" format will be 1071generated. Supported versions are 1,2,3 and 16. The default is 1072currently version 3 but that may change in the future to version 16. 1073 1074Additionally, dtc performs various sanity checks on the tree, like the 1075uniqueness of linux, phandle properties, validity of strings, etc... 1076 1077The format of the .dts "source" file is "C" like, supports C and C++ 1078style comments. 1079 1080/ { 1081} 1082 1083The above is the "device-tree" definition. It's the only statement 1084supported currently at the toplevel. 1085 1086/ { 1087 property1 = "string_value"; /* define a property containing a 0 1088 * terminated string 1089 */ 1090 1091 property2 = <0x1234abcd>; /* define a property containing a 1092 * numerical 32-bit value (hexadecimal) 1093 */ 1094 1095 property3 = <0x12345678 0x12345678 0xdeadbeef>; 1096 /* define a property containing 3 1097 * numerical 32-bit values (cells) in 1098 * hexadecimal 1099 */ 1100 property4 = [0x0a 0x0b 0x0c 0x0d 0xde 0xea 0xad 0xbe 0xef]; 1101 /* define a property whose content is 1102 * an arbitrary array of bytes 1103 */ 1104 1105 childnode@address { /* define a child node named "childnode" 1106 * whose unit name is "childnode at 1107 * address" 1108 */ 1109 1110 childprop = "hello\n"; /* define a property "childprop" of 1111 * childnode (in this case, a string) 1112 */ 1113 }; 1114}; 1115 1116Nodes can contain other nodes etc... thus defining the hierarchical 1117structure of the tree. 1118 1119Strings support common escape sequences from C: "\n", "\t", "\r", 1120"\(octal value)", "\x(hex value)". 1121 1122It is also suggested that you pipe your source file through cpp (gcc 1123preprocessor) so you can use #include's, #define for constants, etc... 1124 1125Finally, various options are planned but not yet implemented, like 1126automatic generation of phandles, labels (exported to the asm file so 1127you can point to a property content and change it easily from whatever 1128you link the device-tree with), label or path instead of numeric value 1129in some cells to "point" to a node (replaced by a phandle at compile 1130time), export of reserve map address to the asm file, ability to 1131specify reserve map content at compile time, etc... 1132 1133We may provide a .h include file with common definitions of that 1134proves useful for some properties (like building PCI properties or 1135interrupt maps) though it may be better to add a notion of struct 1136definitions to the compiler... 1137 1138 1139V - Recommendations for a bootloader 1140==================================== 1141 1142 1143Here are some various ideas/recommendations that have been proposed 1144while all this has been defined and implemented. 1145 1146 - The bootloader may want to be able to use the device-tree itself 1147 and may want to manipulate it (to add/edit some properties, 1148 like physical memory size or kernel arguments). At this point, 2 1149 choices can be made. Either the bootloader works directly on the 1150 flattened format, or the bootloader has its own internal tree 1151 representation with pointers (similar to the kernel one) and 1152 re-flattens the tree when booting the kernel. The former is a bit 1153 more difficult to edit/modify, the later requires probably a bit 1154 more code to handle the tree structure. Note that the structure 1155 format has been designed so it's relatively easy to "insert" 1156 properties or nodes or delete them by just memmoving things 1157 around. It contains no internal offsets or pointers for this 1158 purpose. 1159 1160 - An example of code for iterating nodes & retrieving properties 1161 directly from the flattened tree format can be found in the kernel 1162 file drivers/of/fdt.c. Look at the of_scan_flat_dt() function, 1163 its usage in early_init_devtree(), and the corresponding various 1164 early_init_dt_scan_*() callbacks. That code can be re-used in a 1165 GPL bootloader, and as the author of that code, I would be happy 1166 to discuss possible free licensing to any vendor who wishes to 1167 integrate all or part of this code into a non-GPL bootloader. 1168 (reference needed; who is 'I' here? ---gcl Jan 31, 2011) 1169 1170 1171 1172VI - System-on-a-chip devices and nodes 1173======================================= 1174 1175Many companies are now starting to develop system-on-a-chip 1176processors, where the processor core (CPU) and many peripheral devices 1177exist on a single piece of silicon. For these SOCs, an SOC node 1178should be used that defines child nodes for the devices that make 1179up the SOC. While platforms are not required to use this model in 1180order to boot the kernel, it is highly encouraged that all SOC 1181implementations define as complete a flat-device-tree as possible to 1182describe the devices on the SOC. This will allow for the 1183genericization of much of the kernel code. 1184 1185 11861) Defining child nodes of an SOC 1187--------------------------------- 1188 1189Each device that is part of an SOC may have its own node entry inside 1190the SOC node. For each device that is included in the SOC, the unit 1191address property represents the address offset for this device's 1192memory-mapped registers in the parent's address space. The parent's 1193address space is defined by the "ranges" property in the top-level soc 1194node. The "reg" property for each node that exists directly under the 1195SOC node should contain the address mapping from the child address space 1196to the parent SOC address space and the size of the device's 1197memory-mapped register file. 1198 1199For many devices that may exist inside an SOC, there are predefined 1200specifications for the format of the device tree node. All SOC child 1201nodes should follow these specifications, except where noted in this 1202document. 1203 1204See appendix A for an example partial SOC node definition for the 1205MPC8540. 1206 1207 12082) Representing devices without a current OF specification 1209---------------------------------------------------------- 1210 1211Currently, there are many devices on SoCs that do not have a standard 1212representation defined as part of the Open Firmware specifications, 1213mainly because the boards that contain these SoCs are not currently 1214booted using Open Firmware. Binding documentation for new devices 1215should be added to the Documentation/devicetree/bindings directory. 1216That directory will expand as device tree support is added to more and 1217more SoCs. 1218 1219 1220VII - Specifying interrupt information for devices 1221=================================================== 1222 1223The device tree represents the buses and devices of a hardware 1224system in a form similar to the physical bus topology of the 1225hardware. 1226 1227In addition, a logical 'interrupt tree' exists which represents the 1228hierarchy and routing of interrupts in the hardware. 1229 1230The interrupt tree model is fully described in the 1231document "Open Firmware Recommended Practice: Interrupt 1232Mapping Version 0.9". The document is available at: 1233<http://www.openfirmware.org/ofwg/practice/> 1234 12351) interrupts property 1236---------------------- 1237 1238Devices that generate interrupts to a single interrupt controller 1239should use the conventional OF representation described in the 1240OF interrupt mapping documentation. 1241 1242Each device which generates interrupts must have an 'interrupt' 1243property. The interrupt property value is an arbitrary number of 1244of 'interrupt specifier' values which describe the interrupt or 1245interrupts for the device. 1246 1247The encoding of an interrupt specifier is determined by the 1248interrupt domain in which the device is located in the 1249interrupt tree. The root of an interrupt domain specifies in 1250its #interrupt-cells property the number of 32-bit cells 1251required to encode an interrupt specifier. See the OF interrupt 1252mapping documentation for a detailed description of domains. 1253 1254For example, the binding for the OpenPIC interrupt controller 1255specifies an #interrupt-cells value of 2 to encode the interrupt 1256number and level/sense information. All interrupt children in an 1257OpenPIC interrupt domain use 2 cells per interrupt in their interrupts 1258property. 1259 1260The PCI bus binding specifies a #interrupt-cell value of 1 to encode 1261which interrupt pin (INTA,INTB,INTC,INTD) is used. 1262 12632) interrupt-parent property 1264---------------------------- 1265 1266The interrupt-parent property is specified to define an explicit 1267link between a device node and its interrupt parent in 1268the interrupt tree. The value of interrupt-parent is the 1269phandle of the parent node. 1270 1271If the interrupt-parent property is not defined for a node, its 1272interrupt parent is assumed to be an ancestor in the node's 1273_device tree_ hierarchy. 1274 12753) OpenPIC Interrupt Controllers 1276-------------------------------- 1277 1278OpenPIC interrupt controllers require 2 cells to encode 1279interrupt information. The first cell defines the interrupt 1280number. The second cell defines the sense and level 1281information. 1282 1283Sense and level information should be encoded as follows: 1284 1285 0 = low to high edge sensitive type enabled 1286 1 = active low level sensitive type enabled 1287 2 = active high level sensitive type enabled 1288 3 = high to low edge sensitive type enabled 1289 12904) ISA Interrupt Controllers 1291---------------------------- 1292 1293ISA PIC interrupt controllers require 2 cells to encode 1294interrupt information. The first cell defines the interrupt 1295number. The second cell defines the sense and level 1296information. 1297 1298ISA PIC interrupt controllers should adhere to the ISA PIC 1299encodings listed below: 1300 1301 0 = active low level sensitive type enabled 1302 1 = active high level sensitive type enabled 1303 2 = high to low edge sensitive type enabled 1304 3 = low to high edge sensitive type enabled 1305 1306VIII - Specifying Device Power Management Information (sleep property) 1307=================================================================== 1308 1309Devices on SOCs often have mechanisms for placing devices into low-power 1310states that are decoupled from the devices' own register blocks. Sometimes, 1311this information is more complicated than a cell-index property can 1312reasonably describe. Thus, each device controlled in such a manner 1313may contain a "sleep" property which describes these connections. 1314 1315The sleep property consists of one or more sleep resources, each of 1316which consists of a phandle to a sleep controller, followed by a 1317controller-specific sleep specifier of zero or more cells. 1318 1319The semantics of what type of low power modes are possible are defined 1320by the sleep controller. Some examples of the types of low power modes 1321that may be supported are: 1322 1323 - Dynamic: The device may be disabled or enabled at any time. 1324 - System Suspend: The device may request to be disabled or remain 1325 awake during system suspend, but will not be disabled until then. 1326 - Permanent: The device is disabled permanently (until the next hard 1327 reset). 1328 1329Some devices may share a clock domain with each other, such that they should 1330only be suspended when none of the devices are in use. Where reasonable, 1331such nodes should be placed on a virtual bus, where the bus has the sleep 1332property. If the clock domain is shared among devices that cannot be 1333reasonably grouped in this manner, then create a virtual sleep controller 1334(similar to an interrupt nexus, except that defining a standardized 1335sleep-map should wait until its necessity is demonstrated). 1336 1337IX - Specifying dma bus information 1338 1339Some devices may have DMA memory range shifted relatively to the beginning of 1340RAM, or even placed outside of kernel RAM. For example, the Keystone 2 SoC 1341worked in LPAE mode with 4G memory has: 1342- RAM range: [0x8 0000 0000, 0x8 FFFF FFFF] 1343- DMA range: [ 0x8000 0000, 0xFFFF FFFF] 1344and DMA range is aliased into first 2G of RAM in HW. 1345 1346In such cases, DMA addresses translation should be performed between CPU phys 1347and DMA addresses. The "dma-ranges" property is intended to be used 1348for describing the configuration of such system in DT. 1349 1350In addition, each DMA master device on the DMA bus may or may not support 1351coherent DMA operations. The "dma-coherent" property is intended to be used 1352for identifying devices supported coherent DMA operations in DT. 1353 1354* DMA Bus master 1355Optional property: 1356- dma-ranges: <prop-encoded-array> encoded as arbitrary number of triplets of 1357 (child-bus-address, parent-bus-address, length). Each triplet specified 1358 describes a contiguous DMA address range. 1359 The dma-ranges property is used to describe the direct memory access (DMA) 1360 structure of a memory-mapped bus whose device tree parent can be accessed 1361 from DMA operations originating from the bus. It provides a means of 1362 defining a mapping or translation between the physical address space of 1363 the bus and the physical address space of the parent of the bus. 1364 (for more information see ePAPR specification) 1365 1366* DMA Bus child 1367Optional property: 1368- dma-ranges: <empty> value. if present - It means that DMA addresses 1369 translation has to be enabled for this device. 1370- dma-coherent: Present if dma operations are coherent 1371 1372Example: 1373soc { 1374 compatible = "ti,keystone","simple-bus"; 1375 ranges = <0x0 0x0 0x0 0xc0000000>; 1376 dma-ranges = <0x80000000 0x8 0x00000000 0x80000000>; 1377 1378 [...] 1379 1380 usb: usb@2680000 { 1381 compatible = "ti,keystone-dwc3"; 1382 1383 [...] 1384 dma-coherent; 1385 }; 1386}; 1387 1388Appendix A - Sample SOC node for MPC8540 1389======================================== 1390 1391 soc@e0000000 { 1392 #address-cells = <1>; 1393 #size-cells = <1>; 1394 compatible = "fsl,mpc8540-ccsr", "simple-bus"; 1395 device_type = "soc"; 1396 ranges = <0x00000000 0xe0000000 0x00100000> 1397 bus-frequency = <0>; 1398 interrupt-parent = <&pic>; 1399 1400 ethernet@24000 { 1401 #address-cells = <1>; 1402 #size-cells = <1>; 1403 device_type = "network"; 1404 model = "TSEC"; 1405 compatible = "gianfar", "simple-bus"; 1406 reg = <0x24000 0x1000>; 1407 local-mac-address = [ 0x00 0xE0 0x0C 0x00 0x73 0x00 ]; 1408 interrupts = <0x29 2 0x30 2 0x34 2>; 1409 phy-handle = <&phy0>; 1410 sleep = <&pmc 0x00000080>; 1411 ranges; 1412 1413 mdio@24520 { 1414 reg = <0x24520 0x20>; 1415 compatible = "fsl,gianfar-mdio"; 1416 1417 phy0: ethernet-phy@0 { 1418 interrupts = <5 1>; 1419 reg = <0>; 1420 }; 1421 1422 phy1: ethernet-phy@1 { 1423 interrupts = <5 1>; 1424 reg = <1>; 1425 }; 1426 1427 phy3: ethernet-phy@3 { 1428 interrupts = <7 1>; 1429 reg = <3>; 1430 }; 1431 }; 1432 }; 1433 1434 ethernet@25000 { 1435 device_type = "network"; 1436 model = "TSEC"; 1437 compatible = "gianfar"; 1438 reg = <0x25000 0x1000>; 1439 local-mac-address = [ 0x00 0xE0 0x0C 0x00 0x73 0x01 ]; 1440 interrupts = <0x13 2 0x14 2 0x18 2>; 1441 phy-handle = <&phy1>; 1442 sleep = <&pmc 0x00000040>; 1443 }; 1444 1445 ethernet@26000 { 1446 device_type = "network"; 1447 model = "FEC"; 1448 compatible = "gianfar"; 1449 reg = <0x26000 0x1000>; 1450 local-mac-address = [ 0x00 0xE0 0x0C 0x00 0x73 0x02 ]; 1451 interrupts = <0x41 2>; 1452 phy-handle = <&phy3>; 1453 sleep = <&pmc 0x00000020>; 1454 }; 1455 1456 serial@4500 { 1457 #address-cells = <1>; 1458 #size-cells = <1>; 1459 compatible = "fsl,mpc8540-duart", "simple-bus"; 1460 sleep = <&pmc 0x00000002>; 1461 ranges; 1462 1463 serial@4500 { 1464 device_type = "serial"; 1465 compatible = "ns16550"; 1466 reg = <0x4500 0x100>; 1467 clock-frequency = <0>; 1468 interrupts = <0x42 2>; 1469 }; 1470 1471 serial@4600 { 1472 device_type = "serial"; 1473 compatible = "ns16550"; 1474 reg = <0x4600 0x100>; 1475 clock-frequency = <0>; 1476 interrupts = <0x42 2>; 1477 }; 1478 }; 1479 1480 pic: pic@40000 { 1481 interrupt-controller; 1482 #address-cells = <0>; 1483 #interrupt-cells = <2>; 1484 reg = <0x40000 0x40000>; 1485 compatible = "chrp,open-pic"; 1486 device_type = "open-pic"; 1487 }; 1488 1489 i2c@3000 { 1490 interrupts = <0x43 2>; 1491 reg = <0x3000 0x100>; 1492 compatible = "fsl-i2c"; 1493 dfsrr; 1494 sleep = <&pmc 0x00000004>; 1495 }; 1496 1497 pmc: power@e0070 { 1498 compatible = "fsl,mpc8540-pmc", "fsl,mpc8548-pmc"; 1499 reg = <0xe0070 0x20>; 1500 }; 1501 }; 1502