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 Additional properties for the root node: 860 861 - serial-number : a string representing the device's serial number 862 863 b) The /cpus node 864 865 This node is the parent of all individual CPU nodes. It doesn't 866 have any specific requirements, though it's generally good practice 867 to have at least: 868 869 #address-cells = <00000001> 870 #size-cells = <00000000> 871 872 This defines that the "address" for a CPU is a single cell, and has 873 no meaningful size. This is not necessary but the kernel will assume 874 that format when reading the "reg" properties of a CPU node, see 875 below 876 877 c) The /cpus/* nodes 878 879 So under /cpus, you are supposed to create a node for every CPU on 880 the machine. There is no specific restriction on the name of the 881 CPU, though it's common to call it <architecture>,<core>. For 882 example, Apple uses PowerPC,G5 while IBM uses PowerPC,970FX. 883 However, the Generic Names convention suggests that it would be 884 better to simply use 'cpu' for each cpu node and use the compatible 885 property to identify the specific cpu core. 886 887 Required properties: 888 889 - device_type : has to be "cpu" 890 - reg : This is the physical CPU number, it's a single 32-bit cell 891 and is also used as-is as the unit number for constructing the 892 unit name in the full path. For example, with 2 CPUs, you would 893 have the full path: 894 /cpus/PowerPC,970FX@0 895 /cpus/PowerPC,970FX@1 896 (unit addresses do not require leading zeroes) 897 - d-cache-block-size : one cell, L1 data cache block size in bytes (*) 898 - i-cache-block-size : one cell, L1 instruction cache block size in 899 bytes 900 - d-cache-size : one cell, size of L1 data cache in bytes 901 - i-cache-size : one cell, size of L1 instruction cache in bytes 902 903(*) The cache "block" size is the size on which the cache management 904instructions operate. Historically, this document used the cache 905"line" size here which is incorrect. The kernel will prefer the cache 906block size and will fallback to cache line size for backward 907compatibility. 908 909 Recommended properties: 910 911 - timebase-frequency : a cell indicating the frequency of the 912 timebase in Hz. This is not directly used by the generic code, 913 but you are welcome to copy/paste the pSeries code for setting 914 the kernel timebase/decrementer calibration based on this 915 value. 916 - clock-frequency : a cell indicating the CPU core clock frequency 917 in Hz. A new property will be defined for 64-bit values, but if 918 your frequency is < 4Ghz, one cell is enough. Here as well as 919 for the above, the common code doesn't use that property, but 920 you are welcome to re-use the pSeries or Maple one. A future 921 kernel version might provide a common function for this. 922 - d-cache-line-size : one cell, L1 data cache line size in bytes 923 if different from the block size 924 - i-cache-line-size : one cell, L1 instruction cache line size in 925 bytes if different from the block size 926 927 You are welcome to add any property you find relevant to your board, 928 like some information about the mechanism used to soft-reset the 929 CPUs. For example, Apple puts the GPIO number for CPU soft reset 930 lines in there as a "soft-reset" property since they start secondary 931 CPUs by soft-resetting them. 932 933 934 d) the /memory node(s) 935 936 To define the physical memory layout of your board, you should 937 create one or more memory node(s). You can either create a single 938 node with all memory ranges in its reg property, or you can create 939 several nodes, as you wish. The unit address (@ part) used for the 940 full path is the address of the first range of memory defined by a 941 given node. If you use a single memory node, this will typically be 942 @0. 943 944 Required properties: 945 946 - device_type : has to be "memory" 947 - reg : This property contains all the physical memory ranges of 948 your board. It's a list of addresses/sizes concatenated 949 together, with the number of cells of each defined by the 950 #address-cells and #size-cells of the root node. For example, 951 with both of these properties being 2 like in the example given 952 earlier, a 970 based machine with 6Gb of RAM could typically 953 have a "reg" property here that looks like: 954 955 00000000 00000000 00000000 80000000 956 00000001 00000000 00000001 00000000 957 958 That is a range starting at 0 of 0x80000000 bytes and a range 959 starting at 0x100000000 and of 0x100000000 bytes. You can see 960 that there is no memory covering the IO hole between 2Gb and 961 4Gb. Some vendors prefer splitting those ranges into smaller 962 segments, but the kernel doesn't care. 963 964 e) The /chosen node 965 966 This node is a bit "special". Normally, that's where Open Firmware 967 puts some variable environment information, like the arguments, or 968 the default input/output devices. 969 970 This specification makes a few of these mandatory, but also defines 971 some linux-specific properties that would be normally constructed by 972 the prom_init() trampoline when booting with an OF client interface, 973 but that you have to provide yourself when using the flattened format. 974 975 Recommended properties: 976 977 - bootargs : This zero-terminated string is passed as the kernel 978 command line 979 - linux,stdout-path : This is the full path to your standard 980 console device if any. Typically, if you have serial devices on 981 your board, you may want to put the full path to the one set as 982 the default console in the firmware here, for the kernel to pick 983 it up as its own default console. 984 985 Note that u-boot creates and fills in the chosen node for platforms 986 that use it. 987 988 (Note: a practice that is now obsolete was to include a property 989 under /chosen called interrupt-controller which had a phandle value 990 that pointed to the main interrupt controller) 991 992 f) the /soc<SOCname> node 993 994 This node is used to represent a system-on-a-chip (SoC) and must be 995 present if the processor is a SoC. The top-level soc node contains 996 information that is global to all devices on the SoC. The node name 997 should contain a unit address for the SoC, which is the base address 998 of the memory-mapped register set for the SoC. The name of an SoC 999 node should start with "soc", and the remainder of the name should 1000 represent the part number for the soc. For example, the MPC8540's 1001 soc node would be called "soc8540". 1002 1003 Required properties: 1004 1005 - ranges : Should be defined as specified in 1) to describe the 1006 translation of SoC addresses for memory mapped SoC registers. 1007 - bus-frequency: Contains the bus frequency for the SoC node. 1008 Typically, the value of this field is filled in by the boot 1009 loader. 1010 - compatible : Exact model of the SoC 1011 1012 1013 Recommended properties: 1014 1015 - reg : This property defines the address and size of the 1016 memory-mapped registers that are used for the SOC node itself. 1017 It does not include the child device registers - these will be 1018 defined inside each child node. The address specified in the 1019 "reg" property should match the unit address of the SOC node. 1020 - #address-cells : Address representation for "soc" devices. The 1021 format of this field may vary depending on whether or not the 1022 device registers are memory mapped. For memory mapped 1023 registers, this field represents the number of cells needed to 1024 represent the address of the registers. For SOCs that do not 1025 use MMIO, a special address format should be defined that 1026 contains enough cells to represent the required information. 1027 See 1) above for more details on defining #address-cells. 1028 - #size-cells : Size representation for "soc" devices 1029 - #interrupt-cells : Defines the width of cells used to represent 1030 interrupts. Typically this value is <2>, which includes a 1031 32-bit number that represents the interrupt number, and a 1032 32-bit number that represents the interrupt sense and level. 1033 This field is only needed if the SOC contains an interrupt 1034 controller. 1035 1036 The SOC node may contain child nodes for each SOC device that the 1037 platform uses. Nodes should not be created for devices which exist 1038 on the SOC but are not used by a particular platform. See chapter VI 1039 for more information on how to specify devices that are part of a SOC. 1040 1041 Example SOC node for the MPC8540: 1042 1043 soc8540@e0000000 { 1044 #address-cells = <1>; 1045 #size-cells = <1>; 1046 #interrupt-cells = <2>; 1047 device_type = "soc"; 1048 ranges = <0x00000000 0xe0000000 0x00100000> 1049 reg = <0xe0000000 0x00003000>; 1050 bus-frequency = <0>; 1051 } 1052 1053 1054 1055IV - "dtc", the device tree compiler 1056==================================== 1057 1058 1059dtc source code can be found at 1060<http://git.jdl.com/gitweb/?p=dtc.git> 1061 1062WARNING: This version is still in early development stage; the 1063resulting device-tree "blobs" have not yet been validated with the 1064kernel. The current generated block lacks a useful reserve map (it will 1065be fixed to generate an empty one, it's up to the bootloader to fill 1066it up) among others. The error handling needs work, bugs are lurking, 1067etc... 1068 1069dtc basically takes a device-tree in a given format and outputs a 1070device-tree in another format. The currently supported formats are: 1071 1072 Input formats: 1073 ------------- 1074 1075 - "dtb": "blob" format, that is a flattened device-tree block 1076 with 1077 header all in a binary blob. 1078 - "dts": "source" format. This is a text file containing a 1079 "source" for a device-tree. The format is defined later in this 1080 chapter. 1081 - "fs" format. This is a representation equivalent to the 1082 output of /proc/device-tree, that is nodes are directories and 1083 properties are files 1084 1085 Output formats: 1086 --------------- 1087 1088 - "dtb": "blob" format 1089 - "dts": "source" format 1090 - "asm": assembly language file. This is a file that can be 1091 sourced by gas to generate a device-tree "blob". That file can 1092 then simply be added to your Makefile. Additionally, the 1093 assembly file exports some symbols that can be used. 1094 1095 1096The syntax of the dtc tool is 1097 1098 dtc [-I <input-format>] [-O <output-format>] 1099 [-o output-filename] [-V output_version] input_filename 1100 1101 1102The "output_version" defines what version of the "blob" format will be 1103generated. Supported versions are 1,2,3 and 16. The default is 1104currently version 3 but that may change in the future to version 16. 1105 1106Additionally, dtc performs various sanity checks on the tree, like the 1107uniqueness of linux, phandle properties, validity of strings, etc... 1108 1109The format of the .dts "source" file is "C" like, supports C and C++ 1110style comments. 1111 1112/ { 1113} 1114 1115The above is the "device-tree" definition. It's the only statement 1116supported currently at the toplevel. 1117 1118/ { 1119 property1 = "string_value"; /* define a property containing a 0 1120 * terminated string 1121 */ 1122 1123 property2 = <0x1234abcd>; /* define a property containing a 1124 * numerical 32-bit value (hexadecimal) 1125 */ 1126 1127 property3 = <0x12345678 0x12345678 0xdeadbeef>; 1128 /* define a property containing 3 1129 * numerical 32-bit values (cells) in 1130 * hexadecimal 1131 */ 1132 property4 = [0x0a 0x0b 0x0c 0x0d 0xde 0xea 0xad 0xbe 0xef]; 1133 /* define a property whose content is 1134 * an arbitrary array of bytes 1135 */ 1136 1137 childnode@address { /* define a child node named "childnode" 1138 * whose unit name is "childnode at 1139 * address" 1140 */ 1141 1142 childprop = "hello\n"; /* define a property "childprop" of 1143 * childnode (in this case, a string) 1144 */ 1145 }; 1146}; 1147 1148Nodes can contain other nodes etc... thus defining the hierarchical 1149structure of the tree. 1150 1151Strings support common escape sequences from C: "\n", "\t", "\r", 1152"\(octal value)", "\x(hex value)". 1153 1154It is also suggested that you pipe your source file through cpp (gcc 1155preprocessor) so you can use #include's, #define for constants, etc... 1156 1157Finally, various options are planned but not yet implemented, like 1158automatic generation of phandles, labels (exported to the asm file so 1159you can point to a property content and change it easily from whatever 1160you link the device-tree with), label or path instead of numeric value 1161in some cells to "point" to a node (replaced by a phandle at compile 1162time), export of reserve map address to the asm file, ability to 1163specify reserve map content at compile time, etc... 1164 1165We may provide a .h include file with common definitions of that 1166proves useful for some properties (like building PCI properties or 1167interrupt maps) though it may be better to add a notion of struct 1168definitions to the compiler... 1169 1170 1171V - Recommendations for a bootloader 1172==================================== 1173 1174 1175Here are some various ideas/recommendations that have been proposed 1176while all this has been defined and implemented. 1177 1178 - The bootloader may want to be able to use the device-tree itself 1179 and may want to manipulate it (to add/edit some properties, 1180 like physical memory size or kernel arguments). At this point, 2 1181 choices can be made. Either the bootloader works directly on the 1182 flattened format, or the bootloader has its own internal tree 1183 representation with pointers (similar to the kernel one) and 1184 re-flattens the tree when booting the kernel. The former is a bit 1185 more difficult to edit/modify, the later requires probably a bit 1186 more code to handle the tree structure. Note that the structure 1187 format has been designed so it's relatively easy to "insert" 1188 properties or nodes or delete them by just memmoving things 1189 around. It contains no internal offsets or pointers for this 1190 purpose. 1191 1192 - An example of code for iterating nodes & retrieving properties 1193 directly from the flattened tree format can be found in the kernel 1194 file drivers/of/fdt.c. Look at the of_scan_flat_dt() function, 1195 its usage in early_init_devtree(), and the corresponding various 1196 early_init_dt_scan_*() callbacks. That code can be re-used in a 1197 GPL bootloader, and as the author of that code, I would be happy 1198 to discuss possible free licensing to any vendor who wishes to 1199 integrate all or part of this code into a non-GPL bootloader. 1200 (reference needed; who is 'I' here? ---gcl Jan 31, 2011) 1201 1202 1203 1204VI - System-on-a-chip devices and nodes 1205======================================= 1206 1207Many companies are now starting to develop system-on-a-chip 1208processors, where the processor core (CPU) and many peripheral devices 1209exist on a single piece of silicon. For these SOCs, an SOC node 1210should be used that defines child nodes for the devices that make 1211up the SOC. While platforms are not required to use this model in 1212order to boot the kernel, it is highly encouraged that all SOC 1213implementations define as complete a flat-device-tree as possible to 1214describe the devices on the SOC. This will allow for the 1215genericization of much of the kernel code. 1216 1217 12181) Defining child nodes of an SOC 1219--------------------------------- 1220 1221Each device that is part of an SOC may have its own node entry inside 1222the SOC node. For each device that is included in the SOC, the unit 1223address property represents the address offset for this device's 1224memory-mapped registers in the parent's address space. The parent's 1225address space is defined by the "ranges" property in the top-level soc 1226node. The "reg" property for each node that exists directly under the 1227SOC node should contain the address mapping from the child address space 1228to the parent SOC address space and the size of the device's 1229memory-mapped register file. 1230 1231For many devices that may exist inside an SOC, there are predefined 1232specifications for the format of the device tree node. All SOC child 1233nodes should follow these specifications, except where noted in this 1234document. 1235 1236See appendix A for an example partial SOC node definition for the 1237MPC8540. 1238 1239 12402) Representing devices without a current OF specification 1241---------------------------------------------------------- 1242 1243Currently, there are many devices on SoCs that do not have a standard 1244representation defined as part of the Open Firmware specifications, 1245mainly because the boards that contain these SoCs are not currently 1246booted using Open Firmware. Binding documentation for new devices 1247should be added to the Documentation/devicetree/bindings directory. 1248That directory will expand as device tree support is added to more and 1249more SoCs. 1250 1251 1252VII - Specifying interrupt information for devices 1253=================================================== 1254 1255The device tree represents the buses and devices of a hardware 1256system in a form similar to the physical bus topology of the 1257hardware. 1258 1259In addition, a logical 'interrupt tree' exists which represents the 1260hierarchy and routing of interrupts in the hardware. 1261 1262The interrupt tree model is fully described in the 1263document "Open Firmware Recommended Practice: Interrupt 1264Mapping Version 0.9". The document is available at: 1265<http://www.openfirmware.org/ofwg/practice/> 1266 12671) interrupts property 1268---------------------- 1269 1270Devices that generate interrupts to a single interrupt controller 1271should use the conventional OF representation described in the 1272OF interrupt mapping documentation. 1273 1274Each device which generates interrupts must have an 'interrupt' 1275property. The interrupt property value is an arbitrary number of 1276of 'interrupt specifier' values which describe the interrupt or 1277interrupts for the device. 1278 1279The encoding of an interrupt specifier is determined by the 1280interrupt domain in which the device is located in the 1281interrupt tree. The root of an interrupt domain specifies in 1282its #interrupt-cells property the number of 32-bit cells 1283required to encode an interrupt specifier. See the OF interrupt 1284mapping documentation for a detailed description of domains. 1285 1286For example, the binding for the OpenPIC interrupt controller 1287specifies an #interrupt-cells value of 2 to encode the interrupt 1288number and level/sense information. All interrupt children in an 1289OpenPIC interrupt domain use 2 cells per interrupt in their interrupts 1290property. 1291 1292The PCI bus binding specifies a #interrupt-cell value of 1 to encode 1293which interrupt pin (INTA,INTB,INTC,INTD) is used. 1294 12952) interrupt-parent property 1296---------------------------- 1297 1298The interrupt-parent property is specified to define an explicit 1299link between a device node and its interrupt parent in 1300the interrupt tree. The value of interrupt-parent is the 1301phandle of the parent node. 1302 1303If the interrupt-parent property is not defined for a node, its 1304interrupt parent is assumed to be an ancestor in the node's 1305_device tree_ hierarchy. 1306 13073) OpenPIC Interrupt Controllers 1308-------------------------------- 1309 1310OpenPIC interrupt controllers require 2 cells to encode 1311interrupt information. The first cell defines the interrupt 1312number. The second cell defines the sense and level 1313information. 1314 1315Sense and level information should be encoded as follows: 1316 1317 0 = low to high edge sensitive type enabled 1318 1 = active low level sensitive type enabled 1319 2 = active high level sensitive type enabled 1320 3 = high to low edge sensitive type enabled 1321 13224) ISA Interrupt Controllers 1323---------------------------- 1324 1325ISA PIC interrupt controllers require 2 cells to encode 1326interrupt information. The first cell defines the interrupt 1327number. The second cell defines the sense and level 1328information. 1329 1330ISA PIC interrupt controllers should adhere to the ISA PIC 1331encodings listed below: 1332 1333 0 = active low level sensitive type enabled 1334 1 = active high level sensitive type enabled 1335 2 = high to low edge sensitive type enabled 1336 3 = low to high edge sensitive type enabled 1337 1338VIII - Specifying Device Power Management Information (sleep property) 1339=================================================================== 1340 1341Devices on SOCs often have mechanisms for placing devices into low-power 1342states that are decoupled from the devices' own register blocks. Sometimes, 1343this information is more complicated than a cell-index property can 1344reasonably describe. Thus, each device controlled in such a manner 1345may contain a "sleep" property which describes these connections. 1346 1347The sleep property consists of one or more sleep resources, each of 1348which consists of a phandle to a sleep controller, followed by a 1349controller-specific sleep specifier of zero or more cells. 1350 1351The semantics of what type of low power modes are possible are defined 1352by the sleep controller. Some examples of the types of low power modes 1353that may be supported are: 1354 1355 - Dynamic: The device may be disabled or enabled at any time. 1356 - System Suspend: The device may request to be disabled or remain 1357 awake during system suspend, but will not be disabled until then. 1358 - Permanent: The device is disabled permanently (until the next hard 1359 reset). 1360 1361Some devices may share a clock domain with each other, such that they should 1362only be suspended when none of the devices are in use. Where reasonable, 1363such nodes should be placed on a virtual bus, where the bus has the sleep 1364property. If the clock domain is shared among devices that cannot be 1365reasonably grouped in this manner, then create a virtual sleep controller 1366(similar to an interrupt nexus, except that defining a standardized 1367sleep-map should wait until its necessity is demonstrated). 1368 1369IX - Specifying dma bus information 1370 1371Some devices may have DMA memory range shifted relatively to the beginning of 1372RAM, or even placed outside of kernel RAM. For example, the Keystone 2 SoC 1373worked in LPAE mode with 4G memory has: 1374- RAM range: [0x8 0000 0000, 0x8 FFFF FFFF] 1375- DMA range: [ 0x8000 0000, 0xFFFF FFFF] 1376and DMA range is aliased into first 2G of RAM in HW. 1377 1378In such cases, DMA addresses translation should be performed between CPU phys 1379and DMA addresses. The "dma-ranges" property is intended to be used 1380for describing the configuration of such system in DT. 1381 1382In addition, each DMA master device on the DMA bus may or may not support 1383coherent DMA operations. The "dma-coherent" property is intended to be used 1384for identifying devices supported coherent DMA operations in DT. 1385 1386* DMA Bus master 1387Optional property: 1388- dma-ranges: <prop-encoded-array> encoded as arbitrary number of triplets of 1389 (child-bus-address, parent-bus-address, length). Each triplet specified 1390 describes a contiguous DMA address range. 1391 The dma-ranges property is used to describe the direct memory access (DMA) 1392 structure of a memory-mapped bus whose device tree parent can be accessed 1393 from DMA operations originating from the bus. It provides a means of 1394 defining a mapping or translation between the physical address space of 1395 the bus and the physical address space of the parent of the bus. 1396 (for more information see ePAPR specification) 1397 1398* DMA Bus child 1399Optional property: 1400- dma-ranges: <empty> value. if present - It means that DMA addresses 1401 translation has to be enabled for this device. 1402- dma-coherent: Present if dma operations are coherent 1403 1404Example: 1405soc { 1406 compatible = "ti,keystone","simple-bus"; 1407 ranges = <0x0 0x0 0x0 0xc0000000>; 1408 dma-ranges = <0x80000000 0x8 0x00000000 0x80000000>; 1409 1410 [...] 1411 1412 usb: usb@2680000 { 1413 compatible = "ti,keystone-dwc3"; 1414 1415 [...] 1416 dma-coherent; 1417 }; 1418}; 1419 1420Appendix A - Sample SOC node for MPC8540 1421======================================== 1422 1423 soc@e0000000 { 1424 #address-cells = <1>; 1425 #size-cells = <1>; 1426 compatible = "fsl,mpc8540-ccsr", "simple-bus"; 1427 device_type = "soc"; 1428 ranges = <0x00000000 0xe0000000 0x00100000> 1429 bus-frequency = <0>; 1430 interrupt-parent = <&pic>; 1431 1432 ethernet@24000 { 1433 #address-cells = <1>; 1434 #size-cells = <1>; 1435 device_type = "network"; 1436 model = "TSEC"; 1437 compatible = "gianfar", "simple-bus"; 1438 reg = <0x24000 0x1000>; 1439 local-mac-address = [ 0x00 0xE0 0x0C 0x00 0x73 0x00 ]; 1440 interrupts = <0x29 2 0x30 2 0x34 2>; 1441 phy-handle = <&phy0>; 1442 sleep = <&pmc 0x00000080>; 1443 ranges; 1444 1445 mdio@24520 { 1446 reg = <0x24520 0x20>; 1447 compatible = "fsl,gianfar-mdio"; 1448 1449 phy0: ethernet-phy@0 { 1450 interrupts = <5 1>; 1451 reg = <0>; 1452 }; 1453 1454 phy1: ethernet-phy@1 { 1455 interrupts = <5 1>; 1456 reg = <1>; 1457 }; 1458 1459 phy3: ethernet-phy@3 { 1460 interrupts = <7 1>; 1461 reg = <3>; 1462 }; 1463 }; 1464 }; 1465 1466 ethernet@25000 { 1467 device_type = "network"; 1468 model = "TSEC"; 1469 compatible = "gianfar"; 1470 reg = <0x25000 0x1000>; 1471 local-mac-address = [ 0x00 0xE0 0x0C 0x00 0x73 0x01 ]; 1472 interrupts = <0x13 2 0x14 2 0x18 2>; 1473 phy-handle = <&phy1>; 1474 sleep = <&pmc 0x00000040>; 1475 }; 1476 1477 ethernet@26000 { 1478 device_type = "network"; 1479 model = "FEC"; 1480 compatible = "gianfar"; 1481 reg = <0x26000 0x1000>; 1482 local-mac-address = [ 0x00 0xE0 0x0C 0x00 0x73 0x02 ]; 1483 interrupts = <0x41 2>; 1484 phy-handle = <&phy3>; 1485 sleep = <&pmc 0x00000020>; 1486 }; 1487 1488 serial@4500 { 1489 #address-cells = <1>; 1490 #size-cells = <1>; 1491 compatible = "fsl,mpc8540-duart", "simple-bus"; 1492 sleep = <&pmc 0x00000002>; 1493 ranges; 1494 1495 serial@4500 { 1496 device_type = "serial"; 1497 compatible = "ns16550"; 1498 reg = <0x4500 0x100>; 1499 clock-frequency = <0>; 1500 interrupts = <0x42 2>; 1501 }; 1502 1503 serial@4600 { 1504 device_type = "serial"; 1505 compatible = "ns16550"; 1506 reg = <0x4600 0x100>; 1507 clock-frequency = <0>; 1508 interrupts = <0x42 2>; 1509 }; 1510 }; 1511 1512 pic: pic@40000 { 1513 interrupt-controller; 1514 #address-cells = <0>; 1515 #interrupt-cells = <2>; 1516 reg = <0x40000 0x40000>; 1517 compatible = "chrp,open-pic"; 1518 device_type = "open-pic"; 1519 }; 1520 1521 i2c@3000 { 1522 interrupts = <0x43 2>; 1523 reg = <0x3000 0x100>; 1524 compatible = "fsl-i2c"; 1525 dfsrr; 1526 sleep = <&pmc 0x00000004>; 1527 }; 1528 1529 pmc: power@e0070 { 1530 compatible = "fsl,mpc8540-pmc", "fsl,mpc8548-pmc"; 1531 reg = <0xe0070 0x20>; 1532 }; 1533 }; 1534