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