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