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