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