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 |
| 15 | 1) Entry point for arch/powerpc |
| 16 | 2) Board support |
| 17 | |
| 18 | II - The DT block format |
| 19 | 1) Header |
| 20 | 2) Device tree generalities |
| 21 | 3) Device tree "structure" block |
| 22 | 4) Device tree "strings" block |
| 23 | |
| 24 | III - Required content of the device tree |
| 25 | 1) Note about cells and address representation |
| 26 | 2) Note about "compatible" properties |
| 27 | 3) Note about "name" properties |
| 28 | 4) Note about node and property names and character set |
| 29 | 5) Required nodes and properties |
| 30 | a) The root node |
| 31 | b) The /cpus node |
| 32 | c) The /cpus/* nodes |
| 33 | d) the /memory node(s) |
| 34 | e) The /chosen node |
| 35 | f) the /soc<SOCname> node |
| 36 | |
| 37 | IV - "dtc", the device tree compiler |
| 38 | |
| 39 | V - Recommendations for a bootloader |
| 40 | |
| 41 | VI - System-on-a-chip devices and nodes |
| 42 | 1) Defining child nodes of an SOC |
| 43 | 2) Representing devices without a current OF specification |
| 44 | a) MDIO IO device |
Stuart Yoder | 5e1e9ba | 2007-06-06 04:29:14 +1000 | [diff] [blame] | 45 | b) Gianfar-compatible ethernet nodes |
Roy Zang | a4ecaba | 2007-06-19 15:19:31 +0800 | [diff] [blame] | 46 | c) PHY nodes |
Stuart Yoder | 5e1e9ba | 2007-06-06 04:29:14 +1000 | [diff] [blame] | 47 | d) Interrupt controllers |
| 48 | e) I2C |
| 49 | f) Freescale SOC USB controllers |
| 50 | g) Freescale SOC SEC Security Engines |
| 51 | h) Board Control and Status (BCSR) |
| 52 | i) Freescale QUICC Engine module (QE) |
David Gibson | 2099172 | 2007-09-07 13:23:53 +1000 | [diff] [blame] | 53 | j) CFI or JEDEC memory-mapped NOR flash |
Roy Zang | 3b824f8 | 2007-06-19 15:19:18 +0800 | [diff] [blame] | 54 | k) Global Utilities Block |
Timur Tabi | bc556ba | 2008-01-08 10:30:58 -0600 | [diff] [blame] | 55 | l) Freescale Communications Processor Module |
| 56 | m) Chipselect/Local Bus |
| 57 | n) 4xx/Axon EMAC ethernet nodes |
| 58 | o) Xilinx IP cores |
Timur Tabi | c7d24a2 | 2008-01-18 09:24:53 -0600 | [diff] [blame] | 59 | p) Freescale Synchronous Serial Interface |
Valentine Barshak | 41abd68 | 2007-09-25 05:27:56 +1000 | [diff] [blame] | 60 | q) USB EHCI controllers |
Stuart Yoder | 5e1e9ba | 2007-06-06 04:29:14 +1000 | [diff] [blame] | 61 | |
Dale Farnsworth | f5412c4 | 2008-04-08 08:12:07 +1000 | [diff] [blame] | 62 | VII - Marvell Discovery mv64[345]6x System Controller chips |
| 63 | 1) The /system-controller node |
| 64 | 2) Child nodes of /system-controller |
| 65 | a) Marvell Discovery MDIO bus |
| 66 | b) Marvell Discovery ethernet controller |
| 67 | c) Marvell Discovery PHY nodes |
| 68 | d) Marvell Discovery SDMA nodes |
| 69 | e) Marvell Discovery BRG nodes |
| 70 | f) Marvell Discovery CUNIT nodes |
| 71 | g) Marvell Discovery MPSCROUTING nodes |
| 72 | h) Marvell Discovery MPSCINTR nodes |
| 73 | i) Marvell Discovery MPSC nodes |
| 74 | j) Marvell Discovery Watch Dog Timer nodes |
| 75 | k) Marvell Discovery I2C nodes |
| 76 | l) Marvell Discovery PIC (Programmable Interrupt Controller) nodes |
| 77 | m) Marvell Discovery MPP (Multipurpose Pins) multiplexing nodes |
| 78 | n) Marvell Discovery GPP (General Purpose Pins) nodes |
| 79 | o) Marvell Discovery PCI host bridge node |
| 80 | p) Marvell Discovery CPU Error nodes |
| 81 | q) Marvell Discovery SRAM Controller nodes |
| 82 | r) Marvell Discovery PCI Error Handler nodes |
| 83 | s) Marvell Discovery Memory Controller nodes |
| 84 | |
| 85 | VIII - Specifying interrupt information for devices |
Stuart Yoder | 5e1e9ba | 2007-06-06 04:29:14 +1000 | [diff] [blame] | 86 | 1) interrupts property |
| 87 | 2) interrupt-parent property |
| 88 | 3) OpenPIC Interrupt Controllers |
| 89 | 4) ISA Interrupt Controllers |
| 90 | |
Anton Vorontsov | b7ce341 | 2008-04-11 23:06:36 +1000 | [diff] [blame] | 91 | VIII - Specifying GPIO information for devices |
| 92 | 1) gpios property |
| 93 | 2) gpio-controller nodes |
| 94 | |
Stuart Yoder | 5e1e9ba | 2007-06-06 04:29:14 +1000 | [diff] [blame] | 95 | Appendix A - Sample SOC node for MPC8540 |
| 96 | |
| 97 | |
| 98 | Revision Information |
| 99 | ==================== |
| 100 | |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 101 | May 18, 2005: Rev 0.1 - Initial draft, no chapter III yet. |
| 102 | |
| 103 | May 19, 2005: Rev 0.2 - Add chapter III and bits & pieces here or |
| 104 | clarifies the fact that a lot of things are |
| 105 | optional, the kernel only requires a very |
| 106 | small device tree, though it is encouraged |
| 107 | to provide an as complete one as possible. |
| 108 | |
| 109 | May 24, 2005: Rev 0.3 - Precise that DT block has to be in RAM |
| 110 | - Misc fixes |
| 111 | - Define version 3 and new format version 16 |
| 112 | for the DT block (version 16 needs kernel |
| 113 | patches, will be fwd separately). |
| 114 | String block now has a size, and full path |
| 115 | is replaced by unit name for more |
| 116 | compactness. |
| 117 | linux,phandle is made optional, only nodes |
| 118 | that are referenced by other nodes need it. |
| 119 | "name" property is now automatically |
| 120 | deduced from the unit name |
| 121 | |
| 122 | June 1, 2005: Rev 0.4 - Correct confusion between OF_DT_END and |
| 123 | OF_DT_END_NODE in structure definition. |
| 124 | - Change version 16 format to always align |
| 125 | property data to 4 bytes. Since tokens are |
| 126 | already aligned, that means no specific |
Matt LaPlante | 5d3f083 | 2006-11-30 05:21:10 +0100 | [diff] [blame] | 127 | required alignment between property size |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 128 | and property data. The old style variable |
| 129 | alignment would make it impossible to do |
| 130 | "simple" insertion of properties using |
Domen Puncer | 5dd6016 | 2007-03-02 21:44:45 +1100 | [diff] [blame] | 131 | memmove (thanks Milton for |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 132 | noticing). Updated kernel patch as well |
Matt LaPlante | 5d3f083 | 2006-11-30 05:21:10 +0100 | [diff] [blame] | 133 | - Correct a few more alignment constraints |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 134 | - Add a chapter about the device-tree |
| 135 | compiler and the textural representation of |
| 136 | the tree that can be "compiled" by dtc. |
| 137 | |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 138 | November 21, 2005: Rev 0.5 |
| 139 | - Additions/generalizations for 32-bit |
| 140 | - Changed to reflect the new arch/powerpc |
| 141 | structure |
| 142 | - Added chapter VI |
| 143 | |
| 144 | |
| 145 | ToDo: |
| 146 | - Add some definitions of interrupt tree (simple/complex) |
Domen Puncer | 5dd6016 | 2007-03-02 21:44:45 +1100 | [diff] [blame] | 147 | - Add some definitions for PCI host bridges |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 148 | - Add some common address format examples |
| 149 | - Add definitions for standard properties and "compatible" |
| 150 | names for cells that are not already defined by the existing |
| 151 | OF spec. |
| 152 | - Compare FSL SOC use of PCI to standard and make sure no new |
| 153 | node definition required. |
| 154 | - Add more information about node definitions for SOC devices |
| 155 | that currently have no standard, like the FSL CPM. |
| 156 | |
| 157 | |
| 158 | I - Introduction |
| 159 | ================ |
| 160 | |
| 161 | During the recent development of the Linux/ppc64 kernel, and more |
| 162 | specifically, the addition of new platform types outside of the old |
| 163 | IBM pSeries/iSeries pair, it was decided to enforce some strict rules |
| 164 | regarding the kernel entry and bootloader <-> kernel interfaces, in |
| 165 | order to avoid the degeneration that had become the ppc32 kernel entry |
| 166 | point and the way a new platform should be added to the kernel. The |
| 167 | legacy iSeries platform breaks those rules as it predates this scheme, |
| 168 | but no new board support will be accepted in the main tree that |
| 169 | doesn't follows them properly. In addition, since the advent of the |
| 170 | arch/powerpc merged architecture for ppc32 and ppc64, new 32-bit |
| 171 | platforms and 32-bit platforms which move into arch/powerpc will be |
| 172 | required to use these rules as well. |
| 173 | |
| 174 | The main requirement that will be defined in more detail below is |
| 175 | the presence of a device-tree whose format is defined after Open |
| 176 | Firmware specification. However, in order to make life easier |
| 177 | to embedded board vendors, the kernel doesn't require the device-tree |
| 178 | to represent every device in the system and only requires some nodes |
| 179 | and properties to be present. This will be described in detail in |
| 180 | section III, but, for example, the kernel does not require you to |
| 181 | create a node for every PCI device in the system. It is a requirement |
| 182 | to have a node for PCI host bridges in order to provide interrupt |
| 183 | routing informations and memory/IO ranges, among others. It is also |
| 184 | recommended to define nodes for on chip devices and other busses that |
| 185 | don't specifically fit in an existing OF specification. This creates a |
| 186 | great flexibility in the way the kernel can then probe those and match |
| 187 | drivers to device, without having to hard code all sorts of tables. It |
| 188 | also makes it more flexible for board vendors to do minor hardware |
| 189 | upgrades without significantly impacting the kernel code or cluttering |
| 190 | it with special cases. |
| 191 | |
| 192 | |
| 193 | 1) Entry point for arch/powerpc |
| 194 | ------------------------------- |
| 195 | |
| 196 | There is one and one single entry point to the kernel, at the start |
| 197 | of the kernel image. That entry point supports two calling |
| 198 | conventions: |
| 199 | |
| 200 | a) Boot from Open Firmware. If your firmware is compatible |
| 201 | with Open Firmware (IEEE 1275) or provides an OF compatible |
| 202 | client interface API (support for "interpret" callback of |
| 203 | forth words isn't required), you can enter the kernel with: |
| 204 | |
| 205 | r5 : OF callback pointer as defined by IEEE 1275 |
Domen Puncer | 5dd6016 | 2007-03-02 21:44:45 +1100 | [diff] [blame] | 206 | bindings to powerpc. Only the 32-bit client interface |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 207 | is currently supported |
| 208 | |
| 209 | r3, r4 : address & length of an initrd if any or 0 |
| 210 | |
| 211 | The MMU is either on or off; the kernel will run the |
| 212 | trampoline located in arch/powerpc/kernel/prom_init.c to |
| 213 | extract the device-tree and other information from open |
| 214 | firmware and build a flattened device-tree as described |
| 215 | in b). prom_init() will then re-enter the kernel using |
| 216 | the second method. This trampoline code runs in the |
| 217 | context of the firmware, which is supposed to handle all |
| 218 | exceptions during that time. |
| 219 | |
| 220 | b) Direct entry with a flattened device-tree block. This entry |
| 221 | point is called by a) after the OF trampoline and can also be |
| 222 | called directly by a bootloader that does not support the Open |
| 223 | Firmware client interface. It is also used by "kexec" to |
| 224 | implement "hot" booting of a new kernel from a previous |
| 225 | running one. This method is what I will describe in more |
| 226 | details in this document, as method a) is simply standard Open |
| 227 | Firmware, and thus should be implemented according to the |
| 228 | various standard documents defining it and its binding to the |
| 229 | PowerPC platform. The entry point definition then becomes: |
| 230 | |
| 231 | r3 : physical pointer to the device-tree block |
| 232 | (defined in chapter II) in RAM |
| 233 | |
| 234 | r4 : physical pointer to the kernel itself. This is |
| 235 | used by the assembly code to properly disable the MMU |
| 236 | in case you are entering the kernel with MMU enabled |
| 237 | and a non-1:1 mapping. |
| 238 | |
Matt LaPlante | 2fe0ae7 | 2006-10-03 22:50:39 +0200 | [diff] [blame] | 239 | r5 : NULL (as to differentiate with method a) |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 240 | |
| 241 | Note about SMP entry: Either your firmware puts your other |
| 242 | CPUs in some sleep loop or spin loop in ROM where you can get |
| 243 | them out via a soft reset or some other means, in which case |
| 244 | you don't need to care, or you'll have to enter the kernel |
| 245 | with all CPUs. The way to do that with method b) will be |
| 246 | described in a later revision of this document. |
| 247 | |
| 248 | |
| 249 | 2) Board support |
| 250 | ---------------- |
| 251 | |
| 252 | 64-bit kernels: |
| 253 | |
| 254 | Board supports (platforms) are not exclusive config options. An |
| 255 | arbitrary set of board supports can be built in a single kernel |
| 256 | image. The kernel will "know" what set of functions to use for a |
| 257 | given platform based on the content of the device-tree. Thus, you |
| 258 | should: |
| 259 | |
| 260 | a) add your platform support as a _boolean_ option in |
| 261 | arch/powerpc/Kconfig, following the example of PPC_PSERIES, |
| 262 | PPC_PMAC and PPC_MAPLE. The later is probably a good |
| 263 | example of a board support to start from. |
| 264 | |
| 265 | b) create your main platform file as |
| 266 | "arch/powerpc/platforms/myplatform/myboard_setup.c" and add it |
| 267 | to the Makefile under the condition of your CONFIG_ |
| 268 | option. This file will define a structure of type "ppc_md" |
| 269 | containing the various callbacks that the generic code will |
| 270 | use to get to your platform specific code |
| 271 | |
| 272 | c) Add a reference to your "ppc_md" structure in the |
| 273 | "machines" table in arch/powerpc/kernel/setup_64.c if you are |
| 274 | a 64-bit platform. |
| 275 | |
| 276 | d) request and get assigned a platform number (see PLATFORM_* |
| 277 | constants in include/asm-powerpc/processor.h |
| 278 | |
| 279 | 32-bit embedded kernels: |
| 280 | |
| 281 | Currently, board support is essentially an exclusive config option. |
| 282 | The kernel is configured for a single platform. Part of the reason |
| 283 | for this is to keep kernels on embedded systems small and efficient; |
| 284 | part of this is due to the fact the code is already that way. In the |
| 285 | future, a kernel may support multiple platforms, but only if the |
Domen Puncer | 5dd6016 | 2007-03-02 21:44:45 +1100 | [diff] [blame] | 286 | platforms feature the same core architecture. A single kernel build |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 287 | cannot support both configurations with Book E and configurations |
| 288 | with classic Powerpc architectures. |
| 289 | |
| 290 | 32-bit embedded platforms that are moved into arch/powerpc using a |
| 291 | flattened device tree should adopt the merged tree practice of |
| 292 | setting ppc_md up dynamically, even though the kernel is currently |
| 293 | built with support for only a single platform at a time. This allows |
| 294 | unification of the setup code, and will make it easier to go to a |
| 295 | multiple-platform-support model in the future. |
| 296 | |
| 297 | NOTE: I believe the above will be true once Ben's done with the merge |
| 298 | of the boot sequences.... someone speak up if this is wrong! |
| 299 | |
| 300 | To add a 32-bit embedded platform support, follow the instructions |
| 301 | for 64-bit platforms above, with the exception that the Kconfig |
| 302 | option should be set up such that the kernel builds exclusively for |
| 303 | the platform selected. The processor type for the platform should |
| 304 | enable another config option to select the specific board |
| 305 | supported. |
| 306 | |
Domen Puncer | 5dd6016 | 2007-03-02 21:44:45 +1100 | [diff] [blame] | 307 | NOTE: If Ben doesn't merge the setup files, may need to change this to |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 308 | point to setup_32.c |
| 309 | |
| 310 | |
| 311 | I will describe later the boot process and various callbacks that |
| 312 | your platform should implement. |
| 313 | |
| 314 | |
| 315 | II - The DT block format |
| 316 | ======================== |
| 317 | |
| 318 | |
| 319 | This chapter defines the actual format of the flattened device-tree |
| 320 | passed to the kernel. The actual content of it and kernel requirements |
| 321 | are described later. You can find example of code manipulating that |
| 322 | format in various places, including arch/powerpc/kernel/prom_init.c |
| 323 | which will generate a flattened device-tree from the Open Firmware |
| 324 | representation, or the fs2dt utility which is part of the kexec tools |
| 325 | which will generate one from a filesystem representation. It is |
| 326 | expected that a bootloader like uboot provides a bit more support, |
| 327 | that will be discussed later as well. |
| 328 | |
| 329 | Note: The block has to be in main memory. It has to be accessible in |
| 330 | both real mode and virtual mode with no mapping other than main |
| 331 | memory. If you are writing a simple flash bootloader, it should copy |
| 332 | the block to RAM before passing it to the kernel. |
| 333 | |
| 334 | |
| 335 | 1) Header |
| 336 | --------- |
| 337 | |
| 338 | The kernel is entered with r3 pointing to an area of memory that is |
Matt LaPlante | d6bc8ac | 2006-10-03 22:54:15 +0200 | [diff] [blame] | 339 | roughly described in include/asm-powerpc/prom.h by the structure |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 340 | boot_param_header: |
| 341 | |
| 342 | struct boot_param_header { |
| 343 | u32 magic; /* magic word OF_DT_HEADER */ |
| 344 | u32 totalsize; /* total size of DT block */ |
| 345 | u32 off_dt_struct; /* offset to structure */ |
| 346 | u32 off_dt_strings; /* offset to strings */ |
| 347 | u32 off_mem_rsvmap; /* offset to memory reserve map |
Domen Puncer | 5dd6016 | 2007-03-02 21:44:45 +1100 | [diff] [blame] | 348 | */ |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 349 | u32 version; /* format version */ |
| 350 | u32 last_comp_version; /* last compatible version */ |
| 351 | |
| 352 | /* version 2 fields below */ |
| 353 | u32 boot_cpuid_phys; /* Which physical CPU id we're |
| 354 | booting on */ |
| 355 | /* version 3 fields below */ |
| 356 | u32 size_dt_strings; /* size of the strings block */ |
David Gibson | 0e0293c | 2007-03-14 11:50:40 +1100 | [diff] [blame] | 357 | |
| 358 | /* version 17 fields below */ |
| 359 | u32 size_dt_struct; /* size of the DT structure block */ |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 360 | }; |
| 361 | |
| 362 | Along with the constants: |
| 363 | |
| 364 | /* Definitions used by the flattened device tree */ |
| 365 | #define OF_DT_HEADER 0xd00dfeed /* 4: version, |
| 366 | 4: total size */ |
| 367 | #define OF_DT_BEGIN_NODE 0x1 /* Start node: full name |
Domen Puncer | 5dd6016 | 2007-03-02 21:44:45 +1100 | [diff] [blame] | 368 | */ |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 369 | #define OF_DT_END_NODE 0x2 /* End node */ |
| 370 | #define OF_DT_PROP 0x3 /* Property: name off, |
| 371 | size, content */ |
| 372 | #define OF_DT_END 0x9 |
| 373 | |
| 374 | All values in this header are in big endian format, the various |
| 375 | fields in this header are defined more precisely below. All |
| 376 | "offset" values are in bytes from the start of the header; that is |
| 377 | from the value of r3. |
| 378 | |
| 379 | - magic |
| 380 | |
| 381 | This is a magic value that "marks" the beginning of the |
| 382 | device-tree block header. It contains the value 0xd00dfeed and is |
| 383 | defined by the constant OF_DT_HEADER |
| 384 | |
| 385 | - totalsize |
| 386 | |
| 387 | This is the total size of the DT block including the header. The |
| 388 | "DT" block should enclose all data structures defined in this |
| 389 | chapter (who are pointed to by offsets in this header). That is, |
| 390 | the device-tree structure, strings, and the memory reserve map. |
| 391 | |
| 392 | - off_dt_struct |
| 393 | |
| 394 | This is an offset from the beginning of the header to the start |
| 395 | of the "structure" part the device tree. (see 2) device tree) |
| 396 | |
| 397 | - off_dt_strings |
| 398 | |
| 399 | This is an offset from the beginning of the header to the start |
| 400 | of the "strings" part of the device-tree |
| 401 | |
| 402 | - off_mem_rsvmap |
| 403 | |
| 404 | 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] | 405 | 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] | 406 | bit integers. Each pair is a physical address and a size. The |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 407 | list is terminated by an entry of size 0. This map provides the |
| 408 | kernel with a list of physical memory areas that are "reserved" |
| 409 | and thus not to be used for memory allocations, especially during |
| 410 | early initialization. The kernel needs to allocate memory during |
| 411 | boot for things like un-flattening the device-tree, allocating an |
| 412 | MMU hash table, etc... Those allocations must be done in such a |
| 413 | way to avoid overriding critical things like, on Open Firmware |
| 414 | capable machines, the RTAS instance, or on some pSeries, the TCE |
| 415 | tables used for the iommu. Typically, the reserve map should |
| 416 | contain _at least_ this DT block itself (header,total_size). If |
| 417 | you are passing an initrd to the kernel, you should reserve it as |
| 418 | 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] | 419 | should be 64-bit aligned. |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 420 | |
| 421 | - version |
| 422 | |
| 423 | This is the version of this structure. Version 1 stops |
| 424 | here. Version 2 adds an additional field boot_cpuid_phys. |
| 425 | Version 3 adds the size of the strings block, allowing the kernel |
| 426 | to reallocate it easily at boot and free up the unused flattened |
| 427 | structure after expansion. Version 16 introduces a new more |
| 428 | "compact" format for the tree itself that is however not backward |
David Gibson | 0e0293c | 2007-03-14 11:50:40 +1100 | [diff] [blame] | 429 | compatible. Version 17 adds an additional field, size_dt_struct, |
| 430 | allowing it to be reallocated or moved more easily (this is |
| 431 | particularly useful for bootloaders which need to make |
| 432 | adjustments to a device tree based on probed information). You |
| 433 | should always generate a structure of the highest version defined |
| 434 | at the time of your implementation. Currently that is version 17, |
| 435 | unless you explicitly aim at being backward compatible. |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 436 | |
| 437 | - last_comp_version |
| 438 | |
| 439 | Last compatible version. This indicates down to what version of |
| 440 | the DT block you are backward compatible. For example, version 2 |
| 441 | is backward compatible with version 1 (that is, a kernel build |
| 442 | for version 1 will be able to boot with a version 2 format). You |
| 443 | 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] | 444 | 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] | 445 | using the new unit name format. |
| 446 | |
| 447 | - boot_cpuid_phys |
| 448 | |
| 449 | This field only exist on version 2 headers. It indicate which |
| 450 | physical CPU ID is calling the kernel entry point. This is used, |
| 451 | among others, by kexec. If you are on an SMP system, this value |
| 452 | should match the content of the "reg" property of the CPU node in |
| 453 | the device-tree corresponding to the CPU calling the kernel entry |
| 454 | point (see further chapters for more informations on the required |
| 455 | device-tree contents) |
| 456 | |
David Gibson | 0e0293c | 2007-03-14 11:50:40 +1100 | [diff] [blame] | 457 | - size_dt_strings |
| 458 | |
| 459 | This field only exists on version 3 and later headers. It |
| 460 | gives the size of the "strings" section of the device tree (which |
| 461 | starts at the offset given by off_dt_strings). |
| 462 | |
| 463 | - size_dt_struct |
| 464 | |
| 465 | This field only exists on version 17 and later headers. It gives |
| 466 | the size of the "structure" section of the device tree (which |
| 467 | starts at the offset given by off_dt_struct). |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 468 | |
| 469 | So the typical layout of a DT block (though the various parts don't |
| 470 | need to be in that order) looks like this (addresses go from top to |
| 471 | bottom): |
| 472 | |
| 473 | |
| 474 | ------------------------------ |
| 475 | r3 -> | struct boot_param_header | |
| 476 | ------------------------------ |
| 477 | | (alignment gap) (*) | |
| 478 | ------------------------------ |
| 479 | | memory reserve map | |
| 480 | ------------------------------ |
| 481 | | (alignment gap) | |
| 482 | ------------------------------ |
| 483 | | | |
| 484 | | device-tree structure | |
| 485 | | | |
| 486 | ------------------------------ |
| 487 | | (alignment gap) | |
| 488 | ------------------------------ |
| 489 | | | |
| 490 | | device-tree strings | |
| 491 | | | |
| 492 | -----> ------------------------------ |
| 493 | | |
| 494 | | |
| 495 | --- (r3 + totalsize) |
| 496 | |
| 497 | (*) The alignment gaps are not necessarily present; their presence |
| 498 | and size are dependent on the various alignment requirements of |
| 499 | the individual data blocks. |
| 500 | |
| 501 | |
| 502 | 2) Device tree generalities |
| 503 | --------------------------- |
| 504 | |
| 505 | This device-tree itself is separated in two different blocks, a |
| 506 | structure block and a strings block. Both need to be aligned to a 4 |
| 507 | byte boundary. |
| 508 | |
| 509 | First, let's quickly describe the device-tree concept before detailing |
| 510 | the storage format. This chapter does _not_ describe the detail of the |
| 511 | required types of nodes & properties for the kernel, this is done |
| 512 | later in chapter III. |
| 513 | |
| 514 | The device-tree layout is strongly inherited from the definition of |
| 515 | the Open Firmware IEEE 1275 device-tree. It's basically a tree of |
| 516 | nodes, each node having two or more named properties. A property can |
| 517 | have a value or not. |
| 518 | |
| 519 | It is a tree, so each node has one and only one parent except for the |
| 520 | root node who has no parent. |
| 521 | |
| 522 | A node has 2 names. The actual node name is generally contained in a |
| 523 | property of type "name" in the node property list whose value is a |
| 524 | 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] | 525 | format definition (as it is in Open Firmware). Version 16 makes it |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 526 | optional as it can generate it from the unit name defined below. |
| 527 | |
Matt LaPlante | 2fe0ae7 | 2006-10-03 22:50:39 +0200 | [diff] [blame] | 528 | 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] | 529 | 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] | 530 | names, the "@" sign, and a "unit address", which definition is |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 531 | specific to the bus type the node sits on. |
| 532 | |
| 533 | The unit name doesn't exist as a property per-se but is included in |
| 534 | the device-tree structure. It is typically used to represent "path" in |
| 535 | the device-tree. More details about the actual format of these will be |
| 536 | below. |
| 537 | |
| 538 | The kernel powerpc generic code does not make any formal use of the |
| 539 | unit address (though some board support code may do) so the only real |
| 540 | requirement here for the unit address is to ensure uniqueness of |
| 541 | the node unit name at a given level of the tree. Nodes with no notion |
| 542 | of address and no possible sibling of the same name (like /memory or |
| 543 | /cpus) may omit the unit address in the context of this specification, |
| 544 | or use the "@0" default unit address. The unit name is used to define |
| 545 | a node "full path", which is the concatenation of all parent node |
| 546 | unit names separated with "/". |
| 547 | |
| 548 | The root node doesn't have a defined name, and isn't required to have |
| 549 | a name property either if you are using version 3 or earlier of the |
| 550 | format. It also has no unit address (no @ symbol followed by a unit |
| 551 | address). The root node unit name is thus an empty string. The full |
| 552 | path to the root node is "/". |
| 553 | |
| 554 | Every node which actually represents an actual device (that is, a node |
| 555 | which isn't only a virtual "container" for more nodes, like "/cpus" |
| 556 | is) is also required to have a "device_type" property indicating the |
| 557 | type of node . |
| 558 | |
| 559 | Finally, every node that can be referenced from a property in another |
| 560 | node is required to have a "linux,phandle" property. Real open |
| 561 | firmware implementations provide a unique "phandle" value for every |
| 562 | node that the "prom_init()" trampoline code turns into |
| 563 | "linux,phandle" properties. However, this is made optional if the |
| 564 | flattened device tree is used directly. An example of a node |
| 565 | referencing another node via "phandle" is when laying out the |
| 566 | interrupt tree which will be described in a further version of this |
| 567 | document. |
| 568 | |
Domen Puncer | 5dd6016 | 2007-03-02 21:44:45 +1100 | [diff] [blame] | 569 | This "linux, phandle" property is a 32-bit value that uniquely |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 570 | identifies a node. You are free to use whatever values or system of |
| 571 | values, internal pointers, or whatever to generate these, the only |
| 572 | requirement is that every node for which you provide that property has |
| 573 | a unique value for it. |
| 574 | |
| 575 | Here is an example of a simple device-tree. In this example, an "o" |
| 576 | designates a node followed by the node unit name. Properties are |
| 577 | presented with their name followed by their content. "content" |
| 578 | represents an ASCII string (zero terminated) value, while <content> |
Domen Puncer | 5dd6016 | 2007-03-02 21:44:45 +1100 | [diff] [blame] | 579 | represents a 32-bit hexadecimal value. The various nodes in this |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 580 | example will be discussed in a later chapter. At this point, it is |
| 581 | only meant to give you a idea of what a device-tree looks like. I have |
| 582 | purposefully kept the "name" and "linux,phandle" properties which |
| 583 | aren't necessary in order to give you a better idea of what the tree |
| 584 | looks like in practice. |
| 585 | |
| 586 | / o device-tree |
| 587 | |- name = "device-tree" |
| 588 | |- model = "MyBoardName" |
| 589 | |- compatible = "MyBoardFamilyName" |
| 590 | |- #address-cells = <2> |
| 591 | |- #size-cells = <2> |
| 592 | |- linux,phandle = <0> |
| 593 | | |
| 594 | o cpus |
| 595 | | | - name = "cpus" |
| 596 | | | - linux,phandle = <1> |
| 597 | | | - #address-cells = <1> |
| 598 | | | - #size-cells = <0> |
| 599 | | | |
| 600 | | o PowerPC,970@0 |
| 601 | | |- name = "PowerPC,970" |
| 602 | | |- device_type = "cpu" |
| 603 | | |- reg = <0> |
| 604 | | |- clock-frequency = <5f5e1000> |
Timur Tabi | 32aed2a | 2007-02-14 15:29:07 -0600 | [diff] [blame] | 605 | | |- 64-bit |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 606 | | |- linux,phandle = <2> |
| 607 | | |
| 608 | o memory@0 |
| 609 | | |- name = "memory" |
| 610 | | |- device_type = "memory" |
| 611 | | |- reg = <00000000 00000000 00000000 20000000> |
| 612 | | |- linux,phandle = <3> |
| 613 | | |
| 614 | o chosen |
| 615 | |- name = "chosen" |
| 616 | |- bootargs = "root=/dev/sda2" |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 617 | |- linux,phandle = <4> |
| 618 | |
| 619 | This tree is almost a minimal tree. It pretty much contains the |
| 620 | minimal set of required nodes and properties to boot a linux kernel; |
| 621 | that is, some basic model informations at the root, the CPUs, and the |
| 622 | physical memory layout. It also includes misc information passed |
| 623 | through /chosen, like in this example, the platform type (mandatory) |
| 624 | and the kernel command line arguments (optional). |
| 625 | |
Timur Tabi | 32aed2a | 2007-02-14 15:29:07 -0600 | [diff] [blame] | 626 | 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] | 627 | property without a value. All other properties have a value. The |
| 628 | significance of the #address-cells and #size-cells properties will be |
| 629 | explained in chapter IV which defines precisely the required nodes and |
| 630 | properties and their content. |
| 631 | |
| 632 | |
| 633 | 3) Device tree "structure" block |
| 634 | |
| 635 | The structure of the device tree is a linearized tree structure. The |
| 636 | "OF_DT_BEGIN_NODE" token starts a new node, and the "OF_DT_END_NODE" |
| 637 | ends that node definition. Child nodes are simply defined before |
| 638 | "OF_DT_END_NODE" (that is nodes within the node). A 'token' is a 32 |
| 639 | bit value. The tree has to be "finished" with a OF_DT_END token |
| 640 | |
| 641 | Here's the basic structure of a single node: |
| 642 | |
| 643 | * token OF_DT_BEGIN_NODE (that is 0x00000001) |
| 644 | * for version 1 to 3, this is the node full path as a zero |
| 645 | terminated string, starting with "/". For version 16 and later, |
| 646 | this is the node unit name only (or an empty string for the |
| 647 | root node) |
| 648 | * [align gap to next 4 bytes boundary] |
| 649 | * for each property: |
| 650 | * token OF_DT_PROP (that is 0x00000003) |
Domen Puncer | 5dd6016 | 2007-03-02 21:44:45 +1100 | [diff] [blame] | 651 | * 32-bit value of property value size in bytes (or 0 if no |
| 652 | value) |
| 653 | * 32-bit value of offset in string block of property name |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 654 | * property value data if any |
| 655 | * [align gap to next 4 bytes boundary] |
| 656 | * [child nodes if any] |
| 657 | * token OF_DT_END_NODE (that is 0x00000002) |
| 658 | |
Domen Puncer | 5dd6016 | 2007-03-02 21:44:45 +1100 | [diff] [blame] | 659 | 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] | 660 | 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] | 661 | child node is a full node structure itself as defined above. |
| 662 | |
David Gibson | eff2ebd | 2007-06-28 15:56:26 +1000 | [diff] [blame] | 663 | NOTE: The above definition requires that all property definitions for |
| 664 | a particular node MUST precede any subnode definitions for that node. |
| 665 | Although the structure would not be ambiguous if properties and |
| 666 | subnodes were intermingled, the kernel parser requires that the |
| 667 | properties come first (up until at least 2.6.22). Any tools |
| 668 | manipulating a flattened tree must take care to preserve this |
| 669 | constraint. |
| 670 | |
Matt LaPlante | 53cb472 | 2006-10-03 22:55:17 +0200 | [diff] [blame] | 671 | 4) Device tree "strings" block |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 672 | |
| 673 | In order to save space, property names, which are generally redundant, |
| 674 | are stored separately in the "strings" block. This block is simply the |
| 675 | whole bunch of zero terminated strings for all property names |
| 676 | concatenated together. The device-tree property definitions in the |
| 677 | structure block will contain offset values from the beginning of the |
| 678 | strings block. |
| 679 | |
| 680 | |
| 681 | III - Required content of the device tree |
| 682 | ========================================= |
| 683 | |
| 684 | WARNING: All "linux,*" properties defined in this document apply only |
| 685 | to a flattened device-tree. If your platform uses a real |
| 686 | implementation of Open Firmware or an implementation compatible with |
| 687 | the Open Firmware client interface, those properties will be created |
| 688 | by the trampoline code in the kernel's prom_init() file. For example, |
| 689 | 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] | 690 | set the platform number. However, when using the flattened device-tree |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 691 | entry point, there is no prom_init() pass, and thus you have to |
| 692 | provide those properties yourself. |
| 693 | |
| 694 | |
| 695 | 1) Note about cells and address representation |
| 696 | ---------------------------------------------- |
| 697 | |
| 698 | The general rule is documented in the various Open Firmware |
Domen Puncer | 5dd6016 | 2007-03-02 21:44:45 +1100 | [diff] [blame] | 699 | documentations. If you choose to describe a bus with the device-tree |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 700 | and there exist an OF bus binding, then you should follow the |
| 701 | specification. However, the kernel does not require every single |
| 702 | device or bus to be described by the device tree. |
| 703 | |
| 704 | In general, the format of an address for a device is defined by the |
| 705 | parent bus type, based on the #address-cells and #size-cells |
Mark A. Greer | 5b14e5f | 2008-01-04 02:40:47 +1100 | [diff] [blame] | 706 | properties. Note that the parent's parent definitions of #address-cells |
| 707 | and #size-cells are not inhereted so every node with children must specify |
| 708 | them. The kernel requires the root node to have those properties defining |
| 709 | addresses format for devices directly mapped on the processor bus. |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 710 | |
| 711 | Those 2 properties define 'cells' for representing an address and a |
Domen Puncer | 5dd6016 | 2007-03-02 21:44:45 +1100 | [diff] [blame] | 712 | 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] | 713 | 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] | 714 | 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] | 715 | concatenated and expected to be in big endian format). Another example |
| 716 | is the way Apple firmware defines them, with 2 cells for an address |
| 717 | and one cell for a size. Most 32-bit implementations should define |
| 718 | #address-cells and #size-cells to 1, which represents a 32-bit value. |
| 719 | Some 32-bit processors allow for physical addresses greater than 32 |
| 720 | bits; these processors should define #address-cells as 2. |
| 721 | |
| 722 | "reg" properties are always a tuple of the type "address size" where |
| 723 | the number of cells of address and size is specified by the bus |
| 724 | #address-cells and #size-cells. When a bus supports various address |
| 725 | spaces and other flags relative to a given address allocation (like |
| 726 | prefetchable, etc...) those flags are usually added to the top level |
| 727 | bits of the physical address. For example, a PCI physical address is |
| 728 | made of 3 cells, the bottom two containing the actual address itself |
| 729 | while the top cell contains address space indication, flags, and pci |
| 730 | bus & device numbers. |
| 731 | |
| 732 | For busses that support dynamic allocation, it's the accepted practice |
| 733 | to then not provide the address in "reg" (keep it 0) though while |
| 734 | providing a flag indicating the address is dynamically allocated, and |
| 735 | then, to provide a separate "assigned-addresses" property that |
| 736 | contains the fully allocated addresses. See the PCI OF bindings for |
| 737 | details. |
| 738 | |
| 739 | In general, a simple bus with no address space bits and no dynamic |
| 740 | allocation is preferred if it reflects your hardware, as the existing |
| 741 | kernel address parsing functions will work out of the box. If you |
| 742 | define a bus type with a more complex address format, including things |
| 743 | like address space bits, you'll have to add a bus translator to the |
| 744 | prom_parse.c file of the recent kernels for your bus type. |
| 745 | |
Stephen Neuendorffer | e1fd186 | 2007-12-04 12:08:57 +1100 | [diff] [blame] | 746 | The "reg" property only defines addresses and sizes (if #size-cells is |
| 747 | non-0) within a given bus. In order to translate addresses upward |
Domen Puncer | 5dd6016 | 2007-03-02 21:44:45 +1100 | [diff] [blame] | 748 | (that is into parent bus addresses, and possibly into CPU physical |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 749 | addresses), all busses must contain a "ranges" property. If the |
| 750 | "ranges" property is missing at a given level, it's assumed that |
Stephen Neuendorffer | e1fd186 | 2007-12-04 12:08:57 +1100 | [diff] [blame] | 751 | translation isn't possible, i.e., the registers are not visible on the |
| 752 | parent bus. The format of the "ranges" property for a bus is a list |
| 753 | of: |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 754 | |
| 755 | bus address, parent bus address, size |
| 756 | |
| 757 | "bus address" is in the format of the bus this bus node is defining, |
| 758 | that is, for a PCI bridge, it would be a PCI address. Thus, (bus |
| 759 | address, size) defines a range of addresses for child devices. "parent |
| 760 | bus address" is in the format of the parent bus of this bus. For |
| 761 | example, for a PCI host controller, that would be a CPU address. For a |
| 762 | PCI<->ISA bridge, that would be a PCI address. It defines the base |
| 763 | address in the parent bus where the beginning of that range is mapped. |
| 764 | |
Domen Puncer | 5dd6016 | 2007-03-02 21:44:45 +1100 | [diff] [blame] | 765 | For a new 64-bit powerpc board, I recommend either the 2/2 format or |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 766 | Apple's 2/1 format which is slightly more compact since sizes usually |
Domen Puncer | 5dd6016 | 2007-03-02 21:44:45 +1100 | [diff] [blame] | 767 | fit in a single 32-bit word. New 32-bit powerpc boards should use a |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 768 | 1/1 format, unless the processor supports physical addresses greater |
| 769 | than 32-bits, in which case a 2/1 format is recommended. |
| 770 | |
Stephen Neuendorffer | e1fd186 | 2007-12-04 12:08:57 +1100 | [diff] [blame] | 771 | Alternatively, the "ranges" property may be empty, indicating that the |
| 772 | registers are visible on the parent bus using an identity mapping |
| 773 | translation. In other words, the parent bus address space is the same |
| 774 | as the child bus address space. |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 775 | |
| 776 | 2) Note about "compatible" properties |
| 777 | ------------------------------------- |
| 778 | |
| 779 | These properties are optional, but recommended in devices and the root |
| 780 | node. The format of a "compatible" property is a list of concatenated |
| 781 | zero terminated strings. They allow a device to express its |
| 782 | compatibility with a family of similar devices, in some cases, |
| 783 | allowing a single driver to match against several devices regardless |
| 784 | of their actual names. |
| 785 | |
| 786 | 3) Note about "name" properties |
| 787 | ------------------------------- |
| 788 | |
| 789 | While earlier users of Open Firmware like OldWorld macintoshes tended |
| 790 | to use the actual device name for the "name" property, it's nowadays |
| 791 | considered a good practice to use a name that is closer to the device |
| 792 | class (often equal to device_type). For example, nowadays, ethernet |
| 793 | controllers are named "ethernet", an additional "model" property |
| 794 | defining precisely the chip type/model, and "compatible" property |
| 795 | defining the family in case a single driver can driver more than one |
| 796 | of these chips. However, the kernel doesn't generally put any |
| 797 | restriction on the "name" property; it is simply considered good |
| 798 | practice to follow the standard and its evolutions as closely as |
| 799 | possible. |
| 800 | |
| 801 | Note also that the new format version 16 makes the "name" property |
| 802 | optional. If it's absent for a node, then the node's unit name is then |
| 803 | used to reconstruct the name. That is, the part of the unit name |
| 804 | before the "@" sign is used (or the entire unit name if no "@" sign |
| 805 | is present). |
| 806 | |
| 807 | 4) Note about node and property names and character set |
| 808 | ------------------------------------------------------- |
| 809 | |
Matt LaPlante | a2ffd27 | 2006-10-03 22:49:15 +0200 | [diff] [blame] | 810 | While open firmware provides more flexible usage of 8859-1, this |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 811 | specification enforces more strict rules. Nodes and properties should |
| 812 | be comprised only of ASCII characters 'a' to 'z', '0' to |
| 813 | '9', ',', '.', '_', '+', '#', '?', and '-'. Node names additionally |
| 814 | allow uppercase characters 'A' to 'Z' (property names should be |
| 815 | lowercase. The fact that vendors like Apple don't respect this rule is |
| 816 | irrelevant here). Additionally, node and property names should always |
| 817 | begin with a character in the range 'a' to 'z' (or 'A' to 'Z' for node |
| 818 | names). |
| 819 | |
| 820 | The maximum number of characters for both nodes and property names |
| 821 | is 31. In the case of node names, this is only the leftmost part of |
| 822 | a unit name (the pure "name" property), it doesn't include the unit |
| 823 | address which can extend beyond that limit. |
| 824 | |
| 825 | |
| 826 | 5) Required nodes and properties |
| 827 | -------------------------------- |
| 828 | These are all that are currently required. However, it is strongly |
| 829 | recommended that you expose PCI host bridges as documented in the |
| 830 | PCI binding to open firmware, and your interrupt tree as documented |
| 831 | in OF interrupt tree specification. |
| 832 | |
| 833 | a) The root node |
| 834 | |
| 835 | The root node requires some properties to be present: |
| 836 | |
| 837 | - model : this is your board name/model |
| 838 | - #address-cells : address representation for "root" devices |
| 839 | - #size-cells: the size representation for "root" devices |
Benjamin Herrenschmidt | e822250 | 2006-03-28 23:15:54 +1100 | [diff] [blame] | 840 | - device_type : This property shouldn't be necessary. However, if |
| 841 | you decide to create a device_type for your root node, make sure it |
| 842 | is _not_ "chrp" unless your platform is a pSeries or PAPR compliant |
| 843 | one for 64-bit, or a CHRP-type machine for 32-bit as this will |
| 844 | matched by the kernel this way. |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 845 | |
| 846 | Additionally, some recommended properties are: |
| 847 | |
| 848 | - compatible : the board "family" generally finds its way here, |
| 849 | for example, if you have 2 board models with a similar layout, |
| 850 | that typically get driven by the same platform code in the |
| 851 | kernel, you would use a different "model" property but put a |
| 852 | value in "compatible". The kernel doesn't directly use that |
Stuart Yoder | 143a42d | 2007-02-16 11:30:29 -0600 | [diff] [blame] | 853 | value but it is generally useful. |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 854 | |
| 855 | The root node is also generally where you add additional properties |
| 856 | 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] | 857 | thing. It is recommended that if you add any "custom" property whose |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 858 | name may clash with standard defined ones, you prefix them with your |
| 859 | vendor name and a comma. |
| 860 | |
| 861 | b) The /cpus node |
| 862 | |
| 863 | This node is the parent of all individual CPU nodes. It doesn't |
| 864 | have any specific requirements, though it's generally good practice |
| 865 | to have at least: |
| 866 | |
| 867 | #address-cells = <00000001> |
| 868 | #size-cells = <00000000> |
| 869 | |
| 870 | This defines that the "address" for a CPU is a single cell, and has |
| 871 | no meaningful size. This is not necessary but the kernel will assume |
| 872 | that format when reading the "reg" properties of a CPU node, see |
| 873 | below |
| 874 | |
| 875 | c) The /cpus/* nodes |
| 876 | |
| 877 | So under /cpus, you are supposed to create a node for every CPU on |
| 878 | the machine. There is no specific restriction on the name of the |
| 879 | CPU, though It's common practice to call it PowerPC,<name>. For |
| 880 | example, Apple uses PowerPC,G5 while IBM uses PowerPC,970FX. |
| 881 | |
| 882 | Required properties: |
| 883 | |
| 884 | - device_type : has to be "cpu" |
Domen Puncer | 5dd6016 | 2007-03-02 21:44:45 +1100 | [diff] [blame] | 885 | - 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] | 886 | and is also used as-is as the unit number for constructing the |
| 887 | unit name in the full path. For example, with 2 CPUs, you would |
| 888 | have the full path: |
| 889 | /cpus/PowerPC,970FX@0 |
| 890 | /cpus/PowerPC,970FX@1 |
| 891 | (unit addresses do not require leading zeroes) |
Benjamin Herrenschmidt | 20474ab | 2007-10-28 08:49:28 +1100 | [diff] [blame] | 892 | - d-cache-block-size : one cell, L1 data cache block size in bytes (*) |
| 893 | - i-cache-block-size : one cell, L1 instruction cache block size in |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 894 | bytes |
| 895 | - d-cache-size : one cell, size of L1 data cache in bytes |
| 896 | - i-cache-size : one cell, size of L1 instruction cache in bytes |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 897 | |
Benjamin Herrenschmidt | 20474ab | 2007-10-28 08:49:28 +1100 | [diff] [blame] | 898 | (*) The cache "block" size is the size on which the cache management |
| 899 | instructions operate. Historically, this document used the cache |
| 900 | "line" size here which is incorrect. The kernel will prefer the cache |
| 901 | block size and will fallback to cache line size for backward |
| 902 | compatibility. |
| 903 | |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 904 | Recommended properties: |
| 905 | |
| 906 | - timebase-frequency : a cell indicating the frequency of the |
| 907 | timebase in Hz. This is not directly used by the generic code, |
| 908 | but you are welcome to copy/paste the pSeries code for setting |
| 909 | the kernel timebase/decrementer calibration based on this |
| 910 | value. |
| 911 | - clock-frequency : a cell indicating the CPU core clock frequency |
Domen Puncer | 5dd6016 | 2007-03-02 21:44:45 +1100 | [diff] [blame] | 912 | 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] | 913 | your frequency is < 4Ghz, one cell is enough. Here as well as |
| 914 | for the above, the common code doesn't use that property, but |
| 915 | you are welcome to re-use the pSeries or Maple one. A future |
| 916 | kernel version might provide a common function for this. |
Benjamin Herrenschmidt | 20474ab | 2007-10-28 08:49:28 +1100 | [diff] [blame] | 917 | - d-cache-line-size : one cell, L1 data cache line size in bytes |
| 918 | if different from the block size |
| 919 | - i-cache-line-size : one cell, L1 instruction cache line size in |
| 920 | bytes if different from the block size |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 921 | |
| 922 | You are welcome to add any property you find relevant to your board, |
| 923 | like some information about the mechanism used to soft-reset the |
| 924 | CPUs. For example, Apple puts the GPIO number for CPU soft reset |
| 925 | lines in there as a "soft-reset" property since they start secondary |
| 926 | CPUs by soft-resetting them. |
| 927 | |
| 928 | |
| 929 | d) the /memory node(s) |
| 930 | |
| 931 | To define the physical memory layout of your board, you should |
| 932 | create one or more memory node(s). You can either create a single |
| 933 | node with all memory ranges in its reg property, or you can create |
| 934 | several nodes, as you wish. The unit address (@ part) used for the |
| 935 | full path is the address of the first range of memory defined by a |
| 936 | given node. If you use a single memory node, this will typically be |
| 937 | @0. |
| 938 | |
| 939 | Required properties: |
| 940 | |
| 941 | - device_type : has to be "memory" |
| 942 | - reg : This property contains all the physical memory ranges of |
| 943 | your board. It's a list of addresses/sizes concatenated |
| 944 | together, with the number of cells of each defined by the |
| 945 | #address-cells and #size-cells of the root node. For example, |
Matt LaPlante | 6c28f2c | 2006-10-03 22:46:31 +0200 | [diff] [blame] | 946 | with both of these properties being 2 like in the example given |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 947 | earlier, a 970 based machine with 6Gb of RAM could typically |
| 948 | have a "reg" property here that looks like: |
| 949 | |
| 950 | 00000000 00000000 00000000 80000000 |
| 951 | 00000001 00000000 00000001 00000000 |
| 952 | |
| 953 | That is a range starting at 0 of 0x80000000 bytes and a range |
| 954 | starting at 0x100000000 and of 0x100000000 bytes. You can see |
| 955 | that there is no memory covering the IO hole between 2Gb and |
| 956 | 4Gb. Some vendors prefer splitting those ranges into smaller |
| 957 | segments, but the kernel doesn't care. |
| 958 | |
| 959 | e) The /chosen node |
| 960 | |
| 961 | This node is a bit "special". Normally, that's where open firmware |
| 962 | puts some variable environment information, like the arguments, or |
Stuart Yoder | d1bff9e | 2007-02-19 11:25:05 -0600 | [diff] [blame] | 963 | the default input/output devices. |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 964 | |
| 965 | This specification makes a few of these mandatory, but also defines |
| 966 | some linux-specific properties that would be normally constructed by |
| 967 | the prom_init() trampoline when booting with an OF client interface, |
| 968 | but that you have to provide yourself when using the flattened format. |
| 969 | |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 970 | Recommended properties: |
| 971 | |
| 972 | - bootargs : This zero-terminated string is passed as the kernel |
| 973 | command line |
| 974 | - linux,stdout-path : This is the full path to your standard |
| 975 | console device if any. Typically, if you have serial devices on |
| 976 | your board, you may want to put the full path to the one set as |
| 977 | the default console in the firmware here, for the kernel to pick |
Matt LaPlante | 5d3f083 | 2006-11-30 05:21:10 +0100 | [diff] [blame] | 978 | it up as its own default console. If you look at the function |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 979 | set_preferred_console() in arch/ppc64/kernel/setup.c, you'll see |
| 980 | that the kernel tries to find out the default console and has |
| 981 | knowledge of various types like 8250 serial ports. You may want |
| 982 | to extend this function to add your own. |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 983 | |
| 984 | Note that u-boot creates and fills in the chosen node for platforms |
| 985 | that use it. |
| 986 | |
Stuart Yoder | d1bff9e | 2007-02-19 11:25:05 -0600 | [diff] [blame] | 987 | (Note: a practice that is now obsolete was to include a property |
| 988 | under /chosen called interrupt-controller which had a phandle value |
| 989 | that pointed to the main interrupt controller) |
| 990 | |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 991 | f) the /soc<SOCname> node |
| 992 | |
| 993 | This node is used to represent a system-on-a-chip (SOC) and must be |
| 994 | present if the processor is a SOC. The top-level soc node contains |
| 995 | information that is global to all devices on the SOC. The node name |
| 996 | should contain a unit address for the SOC, which is the base address |
| 997 | of the memory-mapped register set for the SOC. The name of an soc |
| 998 | node should start with "soc", and the remainder of the name should |
| 999 | represent the part number for the soc. For example, the MPC8540's |
| 1000 | soc node would be called "soc8540". |
| 1001 | |
| 1002 | Required properties: |
| 1003 | |
| 1004 | - device_type : Should be "soc" |
| 1005 | - ranges : Should be defined as specified in 1) to describe the |
| 1006 | translation of SOC addresses for memory mapped SOC registers. |
Becky Bruce | 7d4b95a | 2006-02-06 14:26:31 -0600 | [diff] [blame] | 1007 | - bus-frequency: Contains the bus frequency for the SOC node. |
| 1008 | Typically, the value of this field is filled in by the boot |
| 1009 | loader. |
| 1010 | |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 1011 | |
| 1012 | Recommended properties: |
| 1013 | |
| 1014 | - reg : This property defines the address and size of the |
| 1015 | memory-mapped registers that are used for the SOC node itself. |
| 1016 | It does not include the child device registers - these will be |
| 1017 | defined inside each child node. The address specified in the |
| 1018 | "reg" property should match the unit address of the SOC node. |
| 1019 | - #address-cells : Address representation for "soc" devices. The |
| 1020 | format of this field may vary depending on whether or not the |
| 1021 | device registers are memory mapped. For memory mapped |
| 1022 | registers, this field represents the number of cells needed to |
| 1023 | represent the address of the registers. For SOCs that do not |
| 1024 | use MMIO, a special address format should be defined that |
| 1025 | contains enough cells to represent the required information. |
| 1026 | See 1) above for more details on defining #address-cells. |
| 1027 | - #size-cells : Size representation for "soc" devices |
| 1028 | - #interrupt-cells : Defines the width of cells used to represent |
| 1029 | interrupts. Typically this value is <2>, which includes a |
| 1030 | 32-bit number that represents the interrupt number, and a |
| 1031 | 32-bit number that represents the interrupt sense and level. |
| 1032 | This field is only needed if the SOC contains an interrupt |
| 1033 | controller. |
| 1034 | |
| 1035 | The SOC node may contain child nodes for each SOC device that the |
| 1036 | platform uses. Nodes should not be created for devices which exist |
| 1037 | 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] | 1038 | 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] | 1039 | |
| 1040 | Example SOC node for the MPC8540: |
| 1041 | |
| 1042 | soc8540@e0000000 { |
| 1043 | #address-cells = <1>; |
| 1044 | #size-cells = <1>; |
| 1045 | #interrupt-cells = <2>; |
| 1046 | device_type = "soc"; |
| 1047 | ranges = <00000000 e0000000 00100000> |
| 1048 | reg = <e0000000 00003000>; |
Becky Bruce | 7d4b95a | 2006-02-06 14:26:31 -0600 | [diff] [blame] | 1049 | bus-frequency = <0>; |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 1050 | } |
| 1051 | |
| 1052 | |
| 1053 | |
| 1054 | IV - "dtc", the device tree compiler |
| 1055 | ==================================== |
| 1056 | |
| 1057 | |
| 1058 | dtc source code can be found at |
| 1059 | <http://ozlabs.org/~dgibson/dtc/dtc.tar.gz> |
| 1060 | |
| 1061 | WARNING: This version is still in early development stage; the |
| 1062 | resulting device-tree "blobs" have not yet been validated with the |
| 1063 | kernel. The current generated bloc lacks a useful reserve map (it will |
| 1064 | be fixed to generate an empty one, it's up to the bootloader to fill |
| 1065 | it up) among others. The error handling needs work, bugs are lurking, |
| 1066 | etc... |
| 1067 | |
| 1068 | dtc basically takes a device-tree in a given format and outputs a |
| 1069 | device-tree in another format. The currently supported formats are: |
| 1070 | |
| 1071 | Input formats: |
| 1072 | ------------- |
| 1073 | |
| 1074 | - "dtb": "blob" format, that is a flattened device-tree block |
| 1075 | with |
| 1076 | header all in a binary blob. |
| 1077 | - "dts": "source" format. This is a text file containing a |
| 1078 | "source" for a device-tree. The format is defined later in this |
| 1079 | chapter. |
| 1080 | - "fs" format. This is a representation equivalent to the |
| 1081 | output of /proc/device-tree, that is nodes are directories and |
| 1082 | properties are files |
| 1083 | |
| 1084 | Output formats: |
| 1085 | --------------- |
| 1086 | |
| 1087 | - "dtb": "blob" format |
| 1088 | - "dts": "source" format |
| 1089 | - "asm": assembly language file. This is a file that can be |
| 1090 | sourced by gas to generate a device-tree "blob". That file can |
| 1091 | then simply be added to your Makefile. Additionally, the |
Matt LaPlante | 6c28f2c | 2006-10-03 22:46:31 +0200 | [diff] [blame] | 1092 | assembly file exports some symbols that can be used. |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 1093 | |
| 1094 | |
| 1095 | The syntax of the dtc tool is |
| 1096 | |
| 1097 | dtc [-I <input-format>] [-O <output-format>] |
| 1098 | [-o output-filename] [-V output_version] input_filename |
| 1099 | |
| 1100 | |
Domen Puncer | 5dd6016 | 2007-03-02 21:44:45 +1100 | [diff] [blame] | 1101 | The "output_version" defines what version of the "blob" format will be |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 1102 | generated. Supported versions are 1,2,3 and 16. The default is |
| 1103 | currently version 3 but that may change in the future to version 16. |
| 1104 | |
| 1105 | Additionally, dtc performs various sanity checks on the tree, like the |
Matt LaPlante | 6c28f2c | 2006-10-03 22:46:31 +0200 | [diff] [blame] | 1106 | uniqueness of linux, phandle properties, validity of strings, etc... |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 1107 | |
| 1108 | 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] | 1109 | style comments. |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 1110 | |
| 1111 | / { |
| 1112 | } |
| 1113 | |
| 1114 | The above is the "device-tree" definition. It's the only statement |
| 1115 | supported currently at the toplevel. |
| 1116 | |
| 1117 | / { |
| 1118 | property1 = "string_value"; /* define a property containing a 0 |
| 1119 | * terminated string |
| 1120 | */ |
| 1121 | |
| 1122 | property2 = <1234abcd>; /* define a property containing a |
Domen Puncer | 5dd6016 | 2007-03-02 21:44:45 +1100 | [diff] [blame] | 1123 | * numerical 32-bit value (hexadecimal) |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 1124 | */ |
| 1125 | |
| 1126 | property3 = <12345678 12345678 deadbeef>; |
| 1127 | /* define a property containing 3 |
Domen Puncer | 5dd6016 | 2007-03-02 21:44:45 +1100 | [diff] [blame] | 1128 | * numerical 32-bit values (cells) in |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 1129 | * hexadecimal |
| 1130 | */ |
| 1131 | property4 = [0a 0b 0c 0d de ea ad be ef]; |
| 1132 | /* define a property whose content is |
| 1133 | * an arbitrary array of bytes |
| 1134 | */ |
| 1135 | |
| 1136 | childnode@addresss { /* define a child node named "childnode" |
| 1137 | * whose unit name is "childnode at |
| 1138 | * address" |
| 1139 | */ |
| 1140 | |
| 1141 | childprop = "hello\n"; /* define a property "childprop" of |
| 1142 | * childnode (in this case, a string) |
| 1143 | */ |
| 1144 | }; |
| 1145 | }; |
| 1146 | |
| 1147 | Nodes can contain other nodes etc... thus defining the hierarchical |
| 1148 | structure of the tree. |
| 1149 | |
| 1150 | Strings support common escape sequences from C: "\n", "\t", "\r", |
| 1151 | "\(octal value)", "\x(hex value)". |
| 1152 | |
| 1153 | It is also suggested that you pipe your source file through cpp (gcc |
| 1154 | preprocessor) so you can use #include's, #define for constants, etc... |
| 1155 | |
| 1156 | Finally, various options are planned but not yet implemented, like |
| 1157 | automatic generation of phandles, labels (exported to the asm file so |
| 1158 | you can point to a property content and change it easily from whatever |
| 1159 | you link the device-tree with), label or path instead of numeric value |
| 1160 | in some cells to "point" to a node (replaced by a phandle at compile |
| 1161 | time), export of reserve map address to the asm file, ability to |
| 1162 | specify reserve map content at compile time, etc... |
| 1163 | |
| 1164 | We may provide a .h include file with common definitions of that |
| 1165 | proves useful for some properties (like building PCI properties or |
| 1166 | interrupt maps) though it may be better to add a notion of struct |
| 1167 | definitions to the compiler... |
| 1168 | |
| 1169 | |
| 1170 | V - Recommendations for a bootloader |
| 1171 | ==================================== |
| 1172 | |
| 1173 | |
| 1174 | Here are some various ideas/recommendations that have been proposed |
| 1175 | while all this has been defined and implemented. |
| 1176 | |
| 1177 | - The bootloader may want to be able to use the device-tree itself |
| 1178 | and may want to manipulate it (to add/edit some properties, |
| 1179 | like physical memory size or kernel arguments). At this point, 2 |
| 1180 | choices can be made. Either the bootloader works directly on the |
| 1181 | flattened format, or the bootloader has its own internal tree |
| 1182 | representation with pointers (similar to the kernel one) and |
| 1183 | re-flattens the tree when booting the kernel. The former is a bit |
| 1184 | more difficult to edit/modify, the later requires probably a bit |
| 1185 | more code to handle the tree structure. Note that the structure |
| 1186 | format has been designed so it's relatively easy to "insert" |
| 1187 | properties or nodes or delete them by just memmoving things |
| 1188 | around. It contains no internal offsets or pointers for this |
| 1189 | purpose. |
| 1190 | |
Matt LaPlante | d6bc8ac | 2006-10-03 22:54:15 +0200 | [diff] [blame] | 1191 | - An example of code for iterating nodes & retrieving properties |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 1192 | directly from the flattened tree format can be found in the kernel |
| 1193 | file arch/ppc64/kernel/prom.c, look at scan_flat_dt() function, |
Matt LaPlante | d6bc8ac | 2006-10-03 22:54:15 +0200 | [diff] [blame] | 1194 | its usage in early_init_devtree(), and the corresponding various |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 1195 | early_init_dt_scan_*() callbacks. That code can be re-used in a |
| 1196 | 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] | 1197 | to discuss possible free licensing to any vendor who wishes to |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 1198 | integrate all or part of this code into a non-GPL bootloader. |
| 1199 | |
| 1200 | |
| 1201 | |
| 1202 | VI - System-on-a-chip devices and nodes |
| 1203 | ======================================= |
| 1204 | |
| 1205 | Many companies are now starting to develop system-on-a-chip |
Domen Puncer | 5dd6016 | 2007-03-02 21:44:45 +1100 | [diff] [blame] | 1206 | processors, where the processor core (CPU) and many peripheral devices |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 1207 | exist on a single piece of silicon. For these SOCs, an SOC node |
| 1208 | should be used that defines child nodes for the devices that make |
| 1209 | up the SOC. While platforms are not required to use this model in |
| 1210 | order to boot the kernel, it is highly encouraged that all SOC |
| 1211 | implementations define as complete a flat-device-tree as possible to |
| 1212 | describe the devices on the SOC. This will allow for the |
| 1213 | genericization of much of the kernel code. |
| 1214 | |
| 1215 | |
| 1216 | 1) Defining child nodes of an SOC |
| 1217 | --------------------------------- |
| 1218 | |
| 1219 | Each device that is part of an SOC may have its own node entry inside |
| 1220 | the SOC node. For each device that is included in the SOC, the unit |
| 1221 | address property represents the address offset for this device's |
| 1222 | memory-mapped registers in the parent's address space. The parent's |
| 1223 | address space is defined by the "ranges" property in the top-level soc |
| 1224 | node. The "reg" property for each node that exists directly under the |
| 1225 | SOC node should contain the address mapping from the child address space |
| 1226 | to the parent SOC address space and the size of the device's |
| 1227 | memory-mapped register file. |
| 1228 | |
| 1229 | For many devices that may exist inside an SOC, there are predefined |
| 1230 | specifications for the format of the device tree node. All SOC child |
| 1231 | nodes should follow these specifications, except where noted in this |
| 1232 | document. |
| 1233 | |
| 1234 | See appendix A for an example partial SOC node definition for the |
| 1235 | MPC8540. |
| 1236 | |
| 1237 | |
Stuart Yoder | 2756590 | 2007-03-02 13:42:33 -0600 | [diff] [blame] | 1238 | 2) Representing devices without a current OF specification |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 1239 | ---------------------------------------------------------- |
| 1240 | |
| 1241 | Currently, there are many devices on SOCs that do not have a standard |
| 1242 | representation pre-defined as part of the open firmware |
| 1243 | specifications, mainly because the boards that contain these SOCs are |
| 1244 | not currently booted using open firmware. This section contains |
| 1245 | descriptions for the SOC devices for which new nodes have been |
| 1246 | defined; this list will expand as more and more SOC-containing |
| 1247 | platforms are moved over to use the flattened-device-tree model. |
| 1248 | |
| 1249 | a) MDIO IO device |
| 1250 | |
| 1251 | The MDIO is a bus to which the PHY devices are connected. For each |
| 1252 | device that exists on this bus, a child node should be created. See |
| 1253 | the definition of the PHY node below for an example of how to define |
| 1254 | a PHY. |
| 1255 | |
| 1256 | Required properties: |
| 1257 | - reg : Offset and length of the register set for the device |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 1258 | - compatible : Should define the compatible device type for the |
Kumar Gala | e77b28e | 2007-12-12 00:28:35 -0600 | [diff] [blame] | 1259 | mdio. Currently, this is most likely to be "fsl,gianfar-mdio" |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 1260 | |
| 1261 | Example: |
| 1262 | |
| 1263 | mdio@24520 { |
| 1264 | reg = <24520 20>; |
Kumar Gala | e77b28e | 2007-12-12 00:28:35 -0600 | [diff] [blame] | 1265 | compatible = "fsl,gianfar-mdio"; |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 1266 | |
| 1267 | ethernet-phy@0 { |
| 1268 | ...... |
| 1269 | }; |
| 1270 | }; |
| 1271 | |
| 1272 | |
| 1273 | b) Gianfar-compatible ethernet nodes |
| 1274 | |
| 1275 | Required properties: |
| 1276 | |
| 1277 | - device_type : Should be "network" |
| 1278 | - model : Model of the device. Can be "TSEC", "eTSEC", or "FEC" |
| 1279 | - compatible : Should be "gianfar" |
| 1280 | - reg : Offset and length of the register set for the device |
Jon Loeliger | f583165 | 2006-08-17 08:42:35 -0500 | [diff] [blame] | 1281 | - mac-address : List of bytes representing the ethernet address of |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 1282 | this controller |
| 1283 | - interrupts : <a b> where a is the interrupt number and b is a |
| 1284 | field that represents an encoding of the sense and level |
| 1285 | information for the interrupt. This should be encoded based on |
| 1286 | the information in section 2) depending on the type of interrupt |
| 1287 | controller you have. |
| 1288 | - interrupt-parent : the phandle for the interrupt controller that |
| 1289 | services interrupts for this device. |
| 1290 | - phy-handle : The phandle for the PHY connected to this ethernet |
| 1291 | controller. |
Vitaly Bordug | a21e282 | 2007-12-07 01:51:31 +0300 | [diff] [blame] | 1292 | - fixed-link : <a b c d e> where a is emulated phy id - choose any, |
| 1293 | but unique to the all specified fixed-links, b is duplex - 0 half, |
| 1294 | 1 full, c is link speed - d#10/d#100/d#1000, d is pause - 0 no |
| 1295 | pause, 1 pause, e is asym_pause - 0 no asym_pause, 1 asym_pause. |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 1296 | |
Scott Wood | e0a2f28 | 2007-03-16 12:28:46 -0500 | [diff] [blame] | 1297 | Recommended properties: |
| 1298 | |
Andy Fleming | cc65185 | 2007-07-10 17:28:49 -0500 | [diff] [blame] | 1299 | - phy-connection-type : a string naming the controller/PHY interface type, |
| 1300 | i.e., "mii" (default), "rmii", "gmii", "rgmii", "rgmii-id", "sgmii", |
| 1301 | "tbi", or "rtbi". This property is only really needed if the connection |
| 1302 | is of type "rgmii-id", as all other connection types are detected by |
| 1303 | hardware. |
| 1304 | |
Scott Wood | e0a2f28 | 2007-03-16 12:28:46 -0500 | [diff] [blame] | 1305 | |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 1306 | Example: |
| 1307 | |
| 1308 | ethernet@24000 { |
| 1309 | #size-cells = <0>; |
| 1310 | device_type = "network"; |
| 1311 | model = "TSEC"; |
| 1312 | compatible = "gianfar"; |
| 1313 | reg = <24000 1000>; |
Jon Loeliger | f583165 | 2006-08-17 08:42:35 -0500 | [diff] [blame] | 1314 | mac-address = [ 00 E0 0C 00 73 00 ]; |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 1315 | interrupts = <d 3 e 3 12 3>; |
| 1316 | interrupt-parent = <40000>; |
| 1317 | phy-handle = <2452000> |
| 1318 | }; |
| 1319 | |
| 1320 | |
| 1321 | |
| 1322 | c) PHY nodes |
| 1323 | |
| 1324 | Required properties: |
| 1325 | |
| 1326 | - device_type : Should be "ethernet-phy" |
| 1327 | - interrupts : <a b> where a is the interrupt number and b is a |
| 1328 | field that represents an encoding of the sense and level |
| 1329 | information for the interrupt. This should be encoded based on |
| 1330 | the information in section 2) depending on the type of interrupt |
| 1331 | controller you have. |
| 1332 | - interrupt-parent : the phandle for the interrupt controller that |
| 1333 | services interrupts for this device. |
| 1334 | - reg : The ID number for the phy, usually a small integer |
| 1335 | - linux,phandle : phandle for this node; likely referenced by an |
| 1336 | ethernet controller node. |
| 1337 | |
| 1338 | |
| 1339 | Example: |
| 1340 | |
| 1341 | ethernet-phy@0 { |
| 1342 | linux,phandle = <2452000> |
| 1343 | interrupt-parent = <40000>; |
| 1344 | interrupts = <35 1>; |
| 1345 | reg = <0>; |
| 1346 | device_type = "ethernet-phy"; |
| 1347 | }; |
| 1348 | |
| 1349 | |
| 1350 | d) Interrupt controllers |
| 1351 | |
| 1352 | Some SOC devices contain interrupt controllers that are different |
| 1353 | from the standard Open PIC specification. The SOC device nodes for |
| 1354 | these types of controllers should be specified just like a standard |
| 1355 | OpenPIC controller. Sense and level information should be encoded |
| 1356 | as specified in section 2) of this chapter for each device that |
| 1357 | specifies an interrupt. |
| 1358 | |
| 1359 | Example : |
| 1360 | |
| 1361 | pic@40000 { |
| 1362 | linux,phandle = <40000>; |
| 1363 | clock-frequency = <0>; |
| 1364 | interrupt-controller; |
| 1365 | #address-cells = <0>; |
| 1366 | reg = <40000 40000>; |
| 1367 | built-in; |
| 1368 | compatible = "chrp,open-pic"; |
| 1369 | device_type = "open-pic"; |
| 1370 | big-endian; |
| 1371 | }; |
| 1372 | |
| 1373 | |
| 1374 | e) I2C |
| 1375 | |
| 1376 | Required properties : |
| 1377 | |
| 1378 | - device_type : Should be "i2c" |
| 1379 | - reg : Offset and length of the register set for the device |
| 1380 | |
| 1381 | Recommended properties : |
| 1382 | |
| 1383 | - compatible : Should be "fsl-i2c" for parts compatible with |
| 1384 | Freescale I2C specifications. |
| 1385 | - interrupts : <a b> where a is the interrupt number and b is a |
| 1386 | field that represents an encoding of the sense and level |
| 1387 | information for the interrupt. This should be encoded based on |
| 1388 | the information in section 2) depending on the type of interrupt |
| 1389 | controller you have. |
| 1390 | - interrupt-parent : the phandle for the interrupt controller that |
| 1391 | services interrupts for this device. |
| 1392 | - dfsrr : boolean; if defined, indicates that this I2C device has |
| 1393 | a digital filter sampling rate register |
| 1394 | - fsl5200-clocking : boolean; if defined, indicated that this device |
| 1395 | uses the FSL 5200 clocking mechanism. |
| 1396 | |
| 1397 | Example : |
| 1398 | |
| 1399 | i2c@3000 { |
| 1400 | interrupt-parent = <40000>; |
| 1401 | interrupts = <1b 3>; |
| 1402 | reg = <3000 18>; |
| 1403 | device_type = "i2c"; |
| 1404 | compatible = "fsl-i2c"; |
| 1405 | dfsrr; |
| 1406 | }; |
| 1407 | |
| 1408 | |
Becky Bruce | ad71f12 | 2006-02-07 13:44:08 -0600 | [diff] [blame] | 1409 | f) Freescale SOC USB controllers |
| 1410 | |
| 1411 | The device node for a USB controller that is part of a Freescale |
| 1412 | SOC is as described in the document "Open Firmware Recommended |
| 1413 | Practice : Universal Serial Bus" with the following modifications |
| 1414 | and additions : |
| 1415 | |
| 1416 | Required properties : |
Domen Puncer | 5dd6016 | 2007-03-02 21:44:45 +1100 | [diff] [blame] | 1417 | - compatible : Should be "fsl-usb2-mph" for multi port host USB |
| 1418 | controllers, or "fsl-usb2-dr" for dual role USB controllers |
| 1419 | - phy_type : For multi port host USB controllers, should be one of |
| 1420 | "ulpi", or "serial". For dual role USB controllers, should be |
Becky Bruce | ad71f12 | 2006-02-07 13:44:08 -0600 | [diff] [blame] | 1421 | one of "ulpi", "utmi", "utmi_wide", or "serial". |
| 1422 | - reg : Offset and length of the register set for the device |
| 1423 | - port0 : boolean; if defined, indicates port0 is connected for |
| 1424 | fsl-usb2-mph compatible controllers. Either this property or |
| 1425 | "port1" (or both) must be defined for "fsl-usb2-mph" compatible |
| 1426 | controllers. |
| 1427 | - port1 : boolean; if defined, indicates port1 is connected for |
| 1428 | fsl-usb2-mph compatible controllers. Either this property or |
| 1429 | "port0" (or both) must be defined for "fsl-usb2-mph" compatible |
| 1430 | controllers. |
Li Yang | ea5b7a6 | 2007-02-07 13:51:09 +0800 | [diff] [blame] | 1431 | - dr_mode : indicates the working mode for "fsl-usb2-dr" compatible |
| 1432 | controllers. Can be "host", "peripheral", or "otg". Default to |
| 1433 | "host" if not defined for backward compatibility. |
Becky Bruce | ad71f12 | 2006-02-07 13:44:08 -0600 | [diff] [blame] | 1434 | |
| 1435 | Recommended properties : |
| 1436 | - interrupts : <a b> where a is the interrupt number and b is a |
| 1437 | field that represents an encoding of the sense and level |
| 1438 | information for the interrupt. This should be encoded based on |
| 1439 | the information in section 2) depending on the type of interrupt |
| 1440 | controller you have. |
| 1441 | - interrupt-parent : the phandle for the interrupt controller that |
| 1442 | services interrupts for this device. |
| 1443 | |
Domen Puncer | 5dd6016 | 2007-03-02 21:44:45 +1100 | [diff] [blame] | 1444 | Example multi port host USB controller device node : |
Becky Bruce | ad71f12 | 2006-02-07 13:44:08 -0600 | [diff] [blame] | 1445 | usb@22000 { |
Becky Bruce | ad71f12 | 2006-02-07 13:44:08 -0600 | [diff] [blame] | 1446 | compatible = "fsl-usb2-mph"; |
| 1447 | reg = <22000 1000>; |
| 1448 | #address-cells = <1>; |
| 1449 | #size-cells = <0>; |
| 1450 | interrupt-parent = <700>; |
| 1451 | interrupts = <27 1>; |
| 1452 | phy_type = "ulpi"; |
| 1453 | port0; |
| 1454 | port1; |
| 1455 | }; |
| 1456 | |
Domen Puncer | 5dd6016 | 2007-03-02 21:44:45 +1100 | [diff] [blame] | 1457 | Example dual role USB controller device node : |
Becky Bruce | ad71f12 | 2006-02-07 13:44:08 -0600 | [diff] [blame] | 1458 | usb@23000 { |
Becky Bruce | ad71f12 | 2006-02-07 13:44:08 -0600 | [diff] [blame] | 1459 | compatible = "fsl-usb2-dr"; |
| 1460 | reg = <23000 1000>; |
| 1461 | #address-cells = <1>; |
| 1462 | #size-cells = <0>; |
| 1463 | interrupt-parent = <700>; |
| 1464 | interrupts = <26 1>; |
Li Yang | ea5b7a6 | 2007-02-07 13:51:09 +0800 | [diff] [blame] | 1465 | dr_mode = "otg"; |
Becky Bruce | ad71f12 | 2006-02-07 13:44:08 -0600 | [diff] [blame] | 1466 | phy = "ulpi"; |
| 1467 | }; |
| 1468 | |
| 1469 | |
Kim Phillips | b88a0b1 | 2006-03-22 14:39:03 -0600 | [diff] [blame] | 1470 | g) Freescale SOC SEC Security Engines |
| 1471 | |
| 1472 | Required properties: |
| 1473 | |
| 1474 | - device_type : Should be "crypto" |
| 1475 | - model : Model of the device. Should be "SEC1" or "SEC2" |
| 1476 | - compatible : Should be "talitos" |
| 1477 | - reg : Offset and length of the register set for the device |
| 1478 | - interrupts : <a b> where a is the interrupt number and b is a |
| 1479 | field that represents an encoding of the sense and level |
| 1480 | information for the interrupt. This should be encoded based on |
| 1481 | the information in section 2) depending on the type of interrupt |
| 1482 | controller you have. |
| 1483 | - interrupt-parent : the phandle for the interrupt controller that |
| 1484 | services interrupts for this device. |
| 1485 | - num-channels : An integer representing the number of channels |
| 1486 | available. |
| 1487 | - channel-fifo-len : An integer representing the number of |
| 1488 | descriptor pointers each channel fetch fifo can hold. |
| 1489 | - exec-units-mask : The bitmask representing what execution units |
Domen Puncer | 5dd6016 | 2007-03-02 21:44:45 +1100 | [diff] [blame] | 1490 | (EUs) are available. It's a single 32-bit cell. EU information |
Kim Phillips | b88a0b1 | 2006-03-22 14:39:03 -0600 | [diff] [blame] | 1491 | should be encoded following the SEC's Descriptor Header Dword |
| 1492 | EU_SEL0 field documentation, i.e. as follows: |
| 1493 | |
| 1494 | bit 0 = reserved - should be 0 |
| 1495 | bit 1 = set if SEC has the ARC4 EU (AFEU) |
| 1496 | bit 2 = set if SEC has the DES/3DES EU (DEU) |
| 1497 | bit 3 = set if SEC has the message digest EU (MDEU) |
| 1498 | bit 4 = set if SEC has the random number generator EU (RNG) |
| 1499 | bit 5 = set if SEC has the public key EU (PKEU) |
| 1500 | bit 6 = set if SEC has the AES EU (AESU) |
| 1501 | bit 7 = set if SEC has the Kasumi EU (KEU) |
| 1502 | |
| 1503 | bits 8 through 31 are reserved for future SEC EUs. |
| 1504 | |
| 1505 | - descriptor-types-mask : The bitmask representing what descriptors |
Domen Puncer | 5dd6016 | 2007-03-02 21:44:45 +1100 | [diff] [blame] | 1506 | are available. It's a single 32-bit cell. Descriptor type |
Kim Phillips | b88a0b1 | 2006-03-22 14:39:03 -0600 | [diff] [blame] | 1507 | information should be encoded following the SEC's Descriptor |
| 1508 | Header Dword DESC_TYPE field documentation, i.e. as follows: |
| 1509 | |
| 1510 | bit 0 = set if SEC supports the aesu_ctr_nonsnoop desc. type |
| 1511 | bit 1 = set if SEC supports the ipsec_esp descriptor type |
| 1512 | bit 2 = set if SEC supports the common_nonsnoop desc. type |
| 1513 | bit 3 = set if SEC supports the 802.11i AES ccmp desc. type |
| 1514 | bit 4 = set if SEC supports the hmac_snoop_no_afeu desc. type |
| 1515 | bit 5 = set if SEC supports the srtp descriptor type |
| 1516 | bit 6 = set if SEC supports the non_hmac_snoop_no_afeu desc.type |
| 1517 | bit 7 = set if SEC supports the pkeu_assemble descriptor type |
| 1518 | bit 8 = set if SEC supports the aesu_key_expand_output desc.type |
| 1519 | bit 9 = set if SEC supports the pkeu_ptmul descriptor type |
| 1520 | bit 10 = set if SEC supports the common_nonsnoop_afeu desc. type |
| 1521 | bit 11 = set if SEC supports the pkeu_ptadd_dbl descriptor type |
| 1522 | |
| 1523 | ..and so on and so forth. |
| 1524 | |
| 1525 | Example: |
| 1526 | |
| 1527 | /* MPC8548E */ |
| 1528 | crypto@30000 { |
| 1529 | device_type = "crypto"; |
| 1530 | model = "SEC2"; |
| 1531 | compatible = "talitos"; |
| 1532 | reg = <30000 10000>; |
| 1533 | interrupts = <1d 3>; |
| 1534 | interrupt-parent = <40000>; |
| 1535 | num-channels = <4>; |
Kim Phillips | cbdb54d | 2006-07-03 15:10:14 -0500 | [diff] [blame] | 1536 | channel-fifo-len = <18>; |
Kim Phillips | b88a0b1 | 2006-03-22 14:39:03 -0600 | [diff] [blame] | 1537 | exec-units-mask = <000000fe>; |
Kim Phillips | cbdb54d | 2006-07-03 15:10:14 -0500 | [diff] [blame] | 1538 | descriptor-types-mask = <012b0ebf>; |
Kim Phillips | b88a0b1 | 2006-03-22 14:39:03 -0600 | [diff] [blame] | 1539 | }; |
| 1540 | |
Li Yang | 9a1ab88 | 2006-10-02 20:08:59 -0500 | [diff] [blame] | 1541 | h) Board Control and Status (BCSR) |
| 1542 | |
| 1543 | Required properties: |
| 1544 | |
| 1545 | - device_type : Should be "board-control" |
| 1546 | - reg : Offset and length of the register set for the device |
| 1547 | |
| 1548 | Example: |
| 1549 | |
| 1550 | bcsr@f8000000 { |
| 1551 | device_type = "board-control"; |
| 1552 | reg = <f8000000 8000>; |
| 1553 | }; |
| 1554 | |
| 1555 | i) Freescale QUICC Engine module (QE) |
| 1556 | This represents qe module that is installed on PowerQUICC II Pro. |
Scott Wood | e631ae3 | 2007-09-14 13:04:54 -0500 | [diff] [blame] | 1557 | |
| 1558 | NOTE: This is an interim binding; it should be updated to fit |
| 1559 | in with the CPM binding later in this document. |
| 1560 | |
Li Yang | 9a1ab88 | 2006-10-02 20:08:59 -0500 | [diff] [blame] | 1561 | Basically, it is a bus of devices, that could act more or less |
| 1562 | as a complete entity (UCC, USB etc ). All of them should be siblings on |
| 1563 | the "root" qe node, using the common properties from there. |
Michael Opdenacker | 59c5159 | 2007-05-09 08:57:56 +0200 | [diff] [blame] | 1564 | The description below applies to the qe of MPC8360 and |
Li Yang | 9a1ab88 | 2006-10-02 20:08:59 -0500 | [diff] [blame] | 1565 | more nodes and properties would be extended in the future. |
| 1566 | |
| 1567 | i) Root QE device |
| 1568 | |
| 1569 | Required properties: |
Anton Vorontsov | a2dd70a | 2008-01-24 18:39:59 +0300 | [diff] [blame] | 1570 | - compatible : should be "fsl,qe"; |
Li Yang | 9a1ab88 | 2006-10-02 20:08:59 -0500 | [diff] [blame] | 1571 | - model : precise model of the QE, Can be "QE", "CPM", or "CPM2" |
| 1572 | - reg : offset and length of the device registers. |
| 1573 | - bus-frequency : the clock frequency for QUICC Engine. |
| 1574 | |
| 1575 | Recommended properties |
| 1576 | - brg-frequency : the internal clock source frequency for baud-rate |
| 1577 | generators in Hz. |
| 1578 | |
| 1579 | Example: |
| 1580 | qe@e0100000 { |
| 1581 | #address-cells = <1>; |
| 1582 | #size-cells = <1>; |
| 1583 | #interrupt-cells = <2>; |
Anton Vorontsov | a2dd70a | 2008-01-24 18:39:59 +0300 | [diff] [blame] | 1584 | compatible = "fsl,qe"; |
Li Yang | 9a1ab88 | 2006-10-02 20:08:59 -0500 | [diff] [blame] | 1585 | ranges = <0 e0100000 00100000>; |
| 1586 | reg = <e0100000 480>; |
| 1587 | brg-frequency = <0>; |
| 1588 | bus-frequency = <179A7B00>; |
| 1589 | } |
| 1590 | |
| 1591 | |
| 1592 | ii) SPI (Serial Peripheral Interface) |
| 1593 | |
| 1594 | Required properties: |
Anton Vorontsov | f3a2b29 | 2008-01-24 18:40:07 +0300 | [diff] [blame] | 1595 | - cell-index : SPI controller index. |
| 1596 | - compatible : should be "fsl,spi". |
Peter Korsgaard | f023dc7 | 2007-10-03 18:29:09 +0200 | [diff] [blame] | 1597 | - mode : the SPI operation mode, it can be "cpu" or "cpu-qe". |
Li Yang | 9a1ab88 | 2006-10-02 20:08:59 -0500 | [diff] [blame] | 1598 | - reg : Offset and length of the register set for the device |
| 1599 | - interrupts : <a b> where a is the interrupt number and b is a |
| 1600 | field that represents an encoding of the sense and level |
| 1601 | information for the interrupt. This should be encoded based on |
| 1602 | the information in section 2) depending on the type of interrupt |
| 1603 | controller you have. |
| 1604 | - interrupt-parent : the phandle for the interrupt controller that |
| 1605 | services interrupts for this device. |
| 1606 | |
| 1607 | Example: |
| 1608 | spi@4c0 { |
Anton Vorontsov | f3a2b29 | 2008-01-24 18:40:07 +0300 | [diff] [blame] | 1609 | cell-index = <0>; |
| 1610 | compatible = "fsl,spi"; |
Li Yang | 9a1ab88 | 2006-10-02 20:08:59 -0500 | [diff] [blame] | 1611 | reg = <4c0 40>; |
| 1612 | interrupts = <82 0>; |
| 1613 | interrupt-parent = <700>; |
| 1614 | mode = "cpu"; |
| 1615 | }; |
| 1616 | |
| 1617 | |
| 1618 | iii) USB (Universal Serial Bus Controller) |
| 1619 | |
| 1620 | Required properties: |
Li Yang | 9a1ab88 | 2006-10-02 20:08:59 -0500 | [diff] [blame] | 1621 | - compatible : could be "qe_udc" or "fhci-hcd". |
| 1622 | - mode : the could be "host" or "slave". |
| 1623 | - reg : Offset and length of the register set for the device |
| 1624 | - interrupts : <a b> where a is the interrupt number and b is a |
| 1625 | field that represents an encoding of the sense and level |
| 1626 | information for the interrupt. This should be encoded based on |
| 1627 | the information in section 2) depending on the type of interrupt |
| 1628 | controller you have. |
| 1629 | - interrupt-parent : the phandle for the interrupt controller that |
| 1630 | services interrupts for this device. |
| 1631 | |
| 1632 | Example(slave): |
| 1633 | usb@6c0 { |
Li Yang | 9a1ab88 | 2006-10-02 20:08:59 -0500 | [diff] [blame] | 1634 | compatible = "qe_udc"; |
| 1635 | reg = <6c0 40>; |
| 1636 | interrupts = <8b 0>; |
| 1637 | interrupt-parent = <700>; |
| 1638 | mode = "slave"; |
| 1639 | }; |
| 1640 | |
| 1641 | |
| 1642 | iv) UCC (Unified Communications Controllers) |
| 1643 | |
| 1644 | Required properties: |
| 1645 | - device_type : should be "network", "hldc", "uart", "transparent" |
Timur Tabi | 845cf50 | 2008-01-09 17:35:05 -0600 | [diff] [blame] | 1646 | "bisync", "atm", or "serial". |
Li Yang | 9a1ab88 | 2006-10-02 20:08:59 -0500 | [diff] [blame] | 1647 | - compatible : could be "ucc_geth" or "fsl_atm" and so on. |
Anton Vorontsov | 56626f3 | 2008-04-11 20:06:54 +0400 | [diff] [blame] | 1648 | - cell-index : the ucc number(1-8), corresponding to UCCx in UM. |
Li Yang | 9a1ab88 | 2006-10-02 20:08:59 -0500 | [diff] [blame] | 1649 | - reg : Offset and length of the register set for the device |
| 1650 | - interrupts : <a b> where a is the interrupt number and b is a |
| 1651 | field that represents an encoding of the sense and level |
| 1652 | information for the interrupt. This should be encoded based on |
| 1653 | the information in section 2) depending on the type of interrupt |
| 1654 | controller you have. |
| 1655 | - interrupt-parent : the phandle for the interrupt controller that |
| 1656 | services interrupts for this device. |
| 1657 | - pio-handle : The phandle for the Parallel I/O port configuration. |
Timur Tabi | 845cf50 | 2008-01-09 17:35:05 -0600 | [diff] [blame] | 1658 | - port-number : for UART drivers, the port number to use, between 0 and 3. |
| 1659 | This usually corresponds to the /dev/ttyQE device, e.g. <0> = /dev/ttyQE0. |
| 1660 | The port number is added to the minor number of the device. Unlike the |
| 1661 | CPM UART driver, the port-number is required for the QE UART driver. |
| 1662 | - soft-uart : for UART drivers, if specified this means the QE UART device |
| 1663 | driver should use "Soft-UART" mode, which is needed on some SOCs that have |
| 1664 | broken UART hardware. Soft-UART is provided via a microcode upload. |
Timur Tabi | 174b0da | 2007-12-03 15:17:58 -0600 | [diff] [blame] | 1665 | - rx-clock-name: the UCC receive clock source |
| 1666 | "none": clock source is disabled |
| 1667 | "brg1" through "brg16": clock source is BRG1-BRG16, respectively |
| 1668 | "clk1" through "clk24": clock source is CLK1-CLK24, respectively |
| 1669 | - tx-clock-name: the UCC transmit clock source |
| 1670 | "none": clock source is disabled |
| 1671 | "brg1" through "brg16": clock source is BRG1-BRG16, respectively |
| 1672 | "clk1" through "clk24": clock source is CLK1-CLK24, respectively |
| 1673 | The following two properties are deprecated. rx-clock has been replaced |
| 1674 | with rx-clock-name, and tx-clock has been replaced with tx-clock-name. |
| 1675 | Drivers that currently use the deprecated properties should continue to |
| 1676 | do so, in order to support older device trees, but they should be updated |
| 1677 | to check for the new properties first. |
Li Yang | 9a1ab88 | 2006-10-02 20:08:59 -0500 | [diff] [blame] | 1678 | - rx-clock : represents the UCC receive clock source. |
| 1679 | 0x00 : clock source is disabled; |
| 1680 | 0x1~0x10 : clock source is BRG1~BRG16 respectively; |
| 1681 | 0x11~0x28: clock source is QE_CLK1~QE_CLK24 respectively. |
| 1682 | - tx-clock: represents the UCC transmit clock source; |
| 1683 | 0x00 : clock source is disabled; |
| 1684 | 0x1~0x10 : clock source is BRG1~BRG16 respectively; |
| 1685 | 0x11~0x28: clock source is QE_CLK1~QE_CLK24 respectively. |
| 1686 | |
| 1687 | Required properties for network device_type: |
| 1688 | - mac-address : list of bytes representing the ethernet address. |
| 1689 | - phy-handle : The phandle for the PHY connected to this controller. |
| 1690 | |
Scott Wood | e0a2f28 | 2007-03-16 12:28:46 -0500 | [diff] [blame] | 1691 | Recommended properties: |
Kim Phillips | 60c1922 | 2007-04-24 07:26:10 +1000 | [diff] [blame] | 1692 | - phy-connection-type : a string naming the controller/PHY interface type, |
Kim Phillips | 34be456 | 2007-11-05 12:15:35 -0600 | [diff] [blame] | 1693 | i.e., "mii" (default), "rmii", "gmii", "rgmii", "rgmii-id" (Internal |
| 1694 | Delay), "rgmii-txid" (delay on TX only), "rgmii-rxid" (delay on RX only), |
| 1695 | "tbi", or "rtbi". |
Scott Wood | e0a2f28 | 2007-03-16 12:28:46 -0500 | [diff] [blame] | 1696 | |
Li Yang | 9a1ab88 | 2006-10-02 20:08:59 -0500 | [diff] [blame] | 1697 | Example: |
| 1698 | ucc@2000 { |
| 1699 | device_type = "network"; |
| 1700 | compatible = "ucc_geth"; |
Anton Vorontsov | 56626f3 | 2008-04-11 20:06:54 +0400 | [diff] [blame] | 1701 | cell-index = <1>; |
Li Yang | 9a1ab88 | 2006-10-02 20:08:59 -0500 | [diff] [blame] | 1702 | reg = <2000 200>; |
| 1703 | interrupts = <a0 0>; |
| 1704 | interrupt-parent = <700>; |
| 1705 | mac-address = [ 00 04 9f 00 23 23 ]; |
| 1706 | rx-clock = "none"; |
| 1707 | tx-clock = "clk9"; |
| 1708 | phy-handle = <212000>; |
Kim Phillips | 60c1922 | 2007-04-24 07:26:10 +1000 | [diff] [blame] | 1709 | phy-connection-type = "gmii"; |
Li Yang | 9a1ab88 | 2006-10-02 20:08:59 -0500 | [diff] [blame] | 1710 | pio-handle = <140001>; |
| 1711 | }; |
| 1712 | |
| 1713 | |
| 1714 | v) Parallel I/O Ports |
| 1715 | |
| 1716 | This node configures Parallel I/O ports for CPUs with QE support. |
| 1717 | The node should reside in the "soc" node of the tree. For each |
| 1718 | device that using parallel I/O ports, a child node should be created. |
| 1719 | See the definition of the Pin configuration nodes below for more |
| 1720 | information. |
| 1721 | |
| 1722 | Required properties: |
| 1723 | - device_type : should be "par_io". |
| 1724 | - reg : offset to the register set and its length. |
| 1725 | - num-ports : number of Parallel I/O ports |
| 1726 | |
| 1727 | Example: |
| 1728 | par_io@1400 { |
| 1729 | reg = <1400 100>; |
| 1730 | #address-cells = <1>; |
| 1731 | #size-cells = <0>; |
| 1732 | device_type = "par_io"; |
| 1733 | num-ports = <7>; |
| 1734 | ucc_pin@01 { |
| 1735 | ...... |
| 1736 | }; |
| 1737 | |
| 1738 | |
| 1739 | vi) Pin configuration nodes |
| 1740 | |
| 1741 | Required properties: |
| 1742 | - linux,phandle : phandle of this node; likely referenced by a QE |
| 1743 | device. |
| 1744 | - pio-map : array of pin configurations. Each pin is defined by 6 |
| 1745 | integers. The six numbers are respectively: port, pin, dir, |
| 1746 | open_drain, assignment, has_irq. |
| 1747 | - port : port number of the pin; 0-6 represent port A-G in UM. |
| 1748 | - pin : pin number in the port. |
| 1749 | - dir : direction of the pin, should encode as follows: |
| 1750 | |
| 1751 | 0 = The pin is disabled |
| 1752 | 1 = The pin is an output |
| 1753 | 2 = The pin is an input |
| 1754 | 3 = The pin is I/O |
| 1755 | |
| 1756 | - open_drain : indicates the pin is normal or wired-OR: |
| 1757 | |
| 1758 | 0 = The pin is actively driven as an output |
| 1759 | 1 = The pin is an open-drain driver. As an output, the pin is |
| 1760 | driven active-low, otherwise it is three-stated. |
| 1761 | |
| 1762 | - assignment : function number of the pin according to the Pin Assignment |
| 1763 | tables in User Manual. Each pin can have up to 4 possible functions in |
| 1764 | QE and two options for CPM. |
Matt LaPlante | a982ac0 | 2007-05-09 07:35:06 +0200 | [diff] [blame] | 1765 | - has_irq : indicates if the pin is used as source of external |
Li Yang | 9a1ab88 | 2006-10-02 20:08:59 -0500 | [diff] [blame] | 1766 | interrupts. |
| 1767 | |
| 1768 | Example: |
| 1769 | ucc_pin@01 { |
| 1770 | linux,phandle = <140001>; |
| 1771 | pio-map = < |
| 1772 | /* port pin dir open_drain assignment has_irq */ |
| 1773 | 0 3 1 0 1 0 /* TxD0 */ |
| 1774 | 0 4 1 0 1 0 /* TxD1 */ |
| 1775 | 0 5 1 0 1 0 /* TxD2 */ |
| 1776 | 0 6 1 0 1 0 /* TxD3 */ |
| 1777 | 1 6 1 0 3 0 /* TxD4 */ |
| 1778 | 1 7 1 0 1 0 /* TxD5 */ |
| 1779 | 1 9 1 0 2 0 /* TxD6 */ |
| 1780 | 1 a 1 0 2 0 /* TxD7 */ |
| 1781 | 0 9 2 0 1 0 /* RxD0 */ |
| 1782 | 0 a 2 0 1 0 /* RxD1 */ |
| 1783 | 0 b 2 0 1 0 /* RxD2 */ |
| 1784 | 0 c 2 0 1 0 /* RxD3 */ |
| 1785 | 0 d 2 0 1 0 /* RxD4 */ |
| 1786 | 1 1 2 0 2 0 /* RxD5 */ |
| 1787 | 1 0 2 0 2 0 /* RxD6 */ |
| 1788 | 1 4 2 0 2 0 /* RxD7 */ |
| 1789 | 0 7 1 0 1 0 /* TX_EN */ |
| 1790 | 0 8 1 0 1 0 /* TX_ER */ |
| 1791 | 0 f 2 0 1 0 /* RX_DV */ |
| 1792 | 0 10 2 0 1 0 /* RX_ER */ |
| 1793 | 0 0 2 0 1 0 /* RX_CLK */ |
| 1794 | 2 9 1 0 3 0 /* GTX_CLK - CLK10 */ |
| 1795 | 2 8 2 0 1 0>; /* GTX125 - CLK9 */ |
| 1796 | }; |
| 1797 | |
| 1798 | vii) Multi-User RAM (MURAM) |
| 1799 | |
| 1800 | Required properties: |
Anton Vorontsov | a2dd70a | 2008-01-24 18:39:59 +0300 | [diff] [blame] | 1801 | - compatible : should be "fsl,qe-muram", "fsl,cpm-muram". |
Li Yang | 9a1ab88 | 2006-10-02 20:08:59 -0500 | [diff] [blame] | 1802 | - mode : the could be "host" or "slave". |
| 1803 | - ranges : Should be defined as specified in 1) to describe the |
| 1804 | translation of MURAM addresses. |
| 1805 | - data-only : sub-node which defines the address area under MURAM |
| 1806 | bus that can be allocated as data/parameter |
| 1807 | |
| 1808 | Example: |
| 1809 | |
| 1810 | muram@10000 { |
Anton Vorontsov | a2dd70a | 2008-01-24 18:39:59 +0300 | [diff] [blame] | 1811 | compatible = "fsl,qe-muram", "fsl,cpm-muram"; |
Li Yang | 9a1ab88 | 2006-10-02 20:08:59 -0500 | [diff] [blame] | 1812 | ranges = <0 00010000 0000c000>; |
| 1813 | |
| 1814 | data-only@0{ |
Anton Vorontsov | a2dd70a | 2008-01-24 18:39:59 +0300 | [diff] [blame] | 1815 | compatible = "fsl,qe-muram-data", |
| 1816 | "fsl,cpm-muram-data"; |
Li Yang | 9a1ab88 | 2006-10-02 20:08:59 -0500 | [diff] [blame] | 1817 | reg = <0 c000>; |
| 1818 | }; |
| 1819 | }; |
Kim Phillips | b88a0b1 | 2006-03-22 14:39:03 -0600 | [diff] [blame] | 1820 | |
Timur Tabi | bc556ba | 2008-01-08 10:30:58 -0600 | [diff] [blame] | 1821 | viii) Uploaded QE firmware |
| 1822 | |
| 1823 | If a new firwmare has been uploaded to the QE (usually by the |
| 1824 | boot loader), then a 'firmware' child node should be added to the QE |
| 1825 | node. This node provides information on the uploaded firmware that |
| 1826 | device drivers may need. |
| 1827 | |
| 1828 | Required properties: |
| 1829 | - id: The string name of the firmware. This is taken from the 'id' |
| 1830 | member of the qe_firmware structure of the uploaded firmware. |
| 1831 | Device drivers can search this string to determine if the |
| 1832 | firmware they want is already present. |
| 1833 | - extended-modes: The Extended Modes bitfield, taken from the |
| 1834 | firmware binary. It is a 64-bit number represented |
| 1835 | as an array of two 32-bit numbers. |
| 1836 | - virtual-traps: The virtual traps, taken from the firmware binary. |
| 1837 | It is an array of 8 32-bit numbers. |
| 1838 | |
| 1839 | Example: |
| 1840 | |
| 1841 | firmware { |
| 1842 | id = "Soft-UART"; |
| 1843 | extended-modes = <0 0>; |
| 1844 | virtual-traps = <0 0 0 0 0 0 0 0>; |
| 1845 | } |
| 1846 | |
David Gibson | 2099172 | 2007-09-07 13:23:53 +1000 | [diff] [blame] | 1847 | j) CFI or JEDEC memory-mapped NOR flash |
Vitaly Wool | 28f9ec3 | 2006-11-20 16:32:39 +0300 | [diff] [blame] | 1848 | |
| 1849 | Flash chips (Memory Technology Devices) are often used for solid state |
| 1850 | file systems on embedded devices. |
| 1851 | |
David Gibson | 2099172 | 2007-09-07 13:23:53 +1000 | [diff] [blame] | 1852 | - compatible : should contain the specific model of flash chip(s) |
| 1853 | used, if known, followed by either "cfi-flash" or "jedec-flash" |
| 1854 | - reg : Address range of the flash chip |
| 1855 | - bank-width : Width (in bytes) of the flash bank. Equal to the |
| 1856 | device width times the number of interleaved chips. |
| 1857 | - device-width : (optional) Width of a single flash chip. If |
| 1858 | omitted, assumed to be equal to 'bank-width'. |
| 1859 | - #address-cells, #size-cells : Must be present if the flash has |
| 1860 | sub-nodes representing partitions (see below). In this case |
| 1861 | both #address-cells and #size-cells must be equal to 1. |
Vitaly Wool | 28f9ec3 | 2006-11-20 16:32:39 +0300 | [diff] [blame] | 1862 | |
David Gibson | 2099172 | 2007-09-07 13:23:53 +1000 | [diff] [blame] | 1863 | For JEDEC compatible devices, the following additional properties |
| 1864 | are defined: |
Vitaly Wool | 28f9ec3 | 2006-11-20 16:32:39 +0300 | [diff] [blame] | 1865 | |
David Gibson | 2099172 | 2007-09-07 13:23:53 +1000 | [diff] [blame] | 1866 | - vendor-id : Contains the flash chip's vendor id (1 byte). |
| 1867 | - device-id : Contains the flash chip's device id (1 byte). |
Vitaly Wool | 28f9ec3 | 2006-11-20 16:32:39 +0300 | [diff] [blame] | 1868 | |
David Gibson | 2099172 | 2007-09-07 13:23:53 +1000 | [diff] [blame] | 1869 | In addition to the information on the flash bank itself, the |
| 1870 | device tree may optionally contain additional information |
| 1871 | describing partitions of the flash address space. This can be |
| 1872 | used on platforms which have strong conventions about which |
| 1873 | portions of the flash are used for what purposes, but which don't |
| 1874 | use an on-flash partition table such as RedBoot. |
Vitaly Wool | 28f9ec3 | 2006-11-20 16:32:39 +0300 | [diff] [blame] | 1875 | |
David Gibson | 2099172 | 2007-09-07 13:23:53 +1000 | [diff] [blame] | 1876 | Each partition is represented as a sub-node of the flash device. |
| 1877 | Each node's name represents the name of the corresponding |
| 1878 | partition of the flash device. |
Vitaly Wool | 28f9ec3 | 2006-11-20 16:32:39 +0300 | [diff] [blame] | 1879 | |
David Gibson | 2099172 | 2007-09-07 13:23:53 +1000 | [diff] [blame] | 1880 | Flash partitions |
| 1881 | - reg : The partition's offset and size within the flash bank. |
| 1882 | - label : (optional) The label / name for this flash partition. |
| 1883 | If omitted, the label is taken from the node name (excluding |
| 1884 | the unit address). |
| 1885 | - read-only : (optional) This parameter, if present, is a hint to |
| 1886 | Linux that this flash partition should only be mounted |
| 1887 | read-only. This is usually used for flash partitions |
| 1888 | containing early-boot firmware images or data which should not |
| 1889 | be clobbered. |
| 1890 | |
| 1891 | Example: |
| 1892 | |
| 1893 | flash@ff000000 { |
| 1894 | compatible = "amd,am29lv128ml", "cfi-flash"; |
| 1895 | reg = <ff000000 01000000>; |
| 1896 | bank-width = <4>; |
| 1897 | device-width = <1>; |
| 1898 | #address-cells = <1>; |
| 1899 | #size-cells = <1>; |
| 1900 | fs@0 { |
| 1901 | label = "fs"; |
| 1902 | reg = <0 f80000>; |
| 1903 | }; |
| 1904 | firmware@f80000 { |
| 1905 | label ="firmware"; |
| 1906 | reg = <f80000 80000>; |
| 1907 | read-only; |
| 1908 | }; |
| 1909 | }; |
Vitaly Wool | 28f9ec3 | 2006-11-20 16:32:39 +0300 | [diff] [blame] | 1910 | |
Roy Zang | 3b824f8 | 2007-06-19 15:19:18 +0800 | [diff] [blame] | 1911 | k) Global Utilities Block |
| 1912 | |
| 1913 | The global utilities block controls power management, I/O device |
| 1914 | enabling, power-on-reset configuration monitoring, general-purpose |
| 1915 | I/O signal configuration, alternate function selection for multiplexed |
| 1916 | signals, and clock control. |
| 1917 | |
| 1918 | Required properties: |
| 1919 | |
| 1920 | - compatible : Should define the compatible device type for |
| 1921 | global-utilities. |
| 1922 | - reg : Offset and length of the register set for the device. |
| 1923 | |
| 1924 | Recommended properties: |
| 1925 | |
| 1926 | - fsl,has-rstcr : Indicates that the global utilities register set |
| 1927 | contains a functioning "reset control register" (i.e. the board |
| 1928 | is wired to reset upon setting the HRESET_REQ bit in this register). |
| 1929 | |
| 1930 | Example: |
| 1931 | |
| 1932 | global-utilities@e0000 { /* global utilities block */ |
| 1933 | compatible = "fsl,mpc8548-guts"; |
| 1934 | reg = <e0000 1000>; |
| 1935 | fsl,has-rstcr; |
| 1936 | }; |
| 1937 | |
Scott Wood | e631ae3 | 2007-09-14 13:04:54 -0500 | [diff] [blame] | 1938 | l) Freescale Communications Processor Module |
David Gibson | 1d3bb99 | 2007-08-23 13:56:01 +1000 | [diff] [blame] | 1939 | |
Scott Wood | e631ae3 | 2007-09-14 13:04:54 -0500 | [diff] [blame] | 1940 | NOTE: This is an interim binding, and will likely change slightly, |
| 1941 | as more devices are supported. The QE bindings especially are |
| 1942 | incomplete. |
| 1943 | |
| 1944 | i) Root CPM node |
| 1945 | |
| 1946 | Properties: |
| 1947 | - compatible : "fsl,cpm1", "fsl,cpm2", or "fsl,qe". |
Scott Wood | 15f8c60 | 2007-09-28 14:06:16 -0500 | [diff] [blame] | 1948 | - reg : A 48-byte region beginning with CPCR. |
Scott Wood | e631ae3 | 2007-09-14 13:04:54 -0500 | [diff] [blame] | 1949 | |
| 1950 | Example: |
| 1951 | cpm@119c0 { |
| 1952 | #address-cells = <1>; |
| 1953 | #size-cells = <1>; |
| 1954 | #interrupt-cells = <2>; |
| 1955 | compatible = "fsl,mpc8272-cpm", "fsl,cpm2"; |
Scott Wood | 15f8c60 | 2007-09-28 14:06:16 -0500 | [diff] [blame] | 1956 | reg = <119c0 30>; |
Scott Wood | e631ae3 | 2007-09-14 13:04:54 -0500 | [diff] [blame] | 1957 | } |
| 1958 | |
| 1959 | ii) Properties common to mulitple CPM/QE devices |
| 1960 | |
| 1961 | - fsl,cpm-command : This value is ORed with the opcode and command flag |
| 1962 | to specify the device on which a CPM command operates. |
| 1963 | |
| 1964 | - fsl,cpm-brg : Indicates which baud rate generator the device |
| 1965 | is associated with. If absent, an unused BRG |
| 1966 | should be dynamically allocated. If zero, the |
| 1967 | device uses an external clock rather than a BRG. |
| 1968 | |
| 1969 | - reg : Unless otherwise specified, the first resource represents the |
| 1970 | scc/fcc/ucc registers, and the second represents the device's |
| 1971 | parameter RAM region (if it has one). |
| 1972 | |
| 1973 | iii) Serial |
| 1974 | |
| 1975 | Currently defined compatibles: |
| 1976 | - fsl,cpm1-smc-uart |
| 1977 | - fsl,cpm2-smc-uart |
| 1978 | - fsl,cpm1-scc-uart |
| 1979 | - fsl,cpm2-scc-uart |
| 1980 | - fsl,qe-uart |
| 1981 | |
| 1982 | Example: |
| 1983 | |
| 1984 | serial@11a00 { |
| 1985 | device_type = "serial"; |
| 1986 | compatible = "fsl,mpc8272-scc-uart", |
| 1987 | "fsl,cpm2-scc-uart"; |
| 1988 | reg = <11a00 20 8000 100>; |
| 1989 | interrupts = <28 8>; |
| 1990 | interrupt-parent = <&PIC>; |
| 1991 | fsl,cpm-brg = <1>; |
| 1992 | fsl,cpm-command = <00800000>; |
| 1993 | }; |
| 1994 | |
| 1995 | iii) Network |
| 1996 | |
| 1997 | Currently defined compatibles: |
| 1998 | - fsl,cpm1-scc-enet |
| 1999 | - fsl,cpm2-scc-enet |
| 2000 | - fsl,cpm1-fec-enet |
| 2001 | - fsl,cpm2-fcc-enet (third resource is GFEMR) |
| 2002 | - fsl,qe-enet |
| 2003 | |
| 2004 | Example: |
| 2005 | |
| 2006 | ethernet@11300 { |
| 2007 | device_type = "network"; |
| 2008 | compatible = "fsl,mpc8272-fcc-enet", |
| 2009 | "fsl,cpm2-fcc-enet"; |
| 2010 | reg = <11300 20 8400 100 11390 1>; |
| 2011 | local-mac-address = [ 00 00 00 00 00 00 ]; |
| 2012 | interrupts = <20 8>; |
| 2013 | interrupt-parent = <&PIC>; |
| 2014 | phy-handle = <&PHY0>; |
Scott Wood | e631ae3 | 2007-09-14 13:04:54 -0500 | [diff] [blame] | 2015 | fsl,cpm-command = <12000300>; |
| 2016 | }; |
| 2017 | |
| 2018 | iv) MDIO |
| 2019 | |
| 2020 | Currently defined compatibles: |
| 2021 | fsl,pq1-fec-mdio (reg is same as first resource of FEC device) |
| 2022 | fsl,cpm2-mdio-bitbang (reg is port C registers) |
| 2023 | |
| 2024 | Properties for fsl,cpm2-mdio-bitbang: |
| 2025 | fsl,mdio-pin : pin of port C controlling mdio data |
| 2026 | fsl,mdc-pin : pin of port C controlling mdio clock |
| 2027 | |
| 2028 | Example: |
| 2029 | |
| 2030 | mdio@10d40 { |
| 2031 | device_type = "mdio"; |
| 2032 | compatible = "fsl,mpc8272ads-mdio-bitbang", |
| 2033 | "fsl,mpc8272-mdio-bitbang", |
| 2034 | "fsl,cpm2-mdio-bitbang"; |
| 2035 | reg = <10d40 14>; |
| 2036 | #address-cells = <1>; |
| 2037 | #size-cells = <0>; |
| 2038 | fsl,mdio-pin = <12>; |
| 2039 | fsl,mdc-pin = <13>; |
| 2040 | }; |
| 2041 | |
| 2042 | v) Baud Rate Generators |
| 2043 | |
| 2044 | Currently defined compatibles: |
| 2045 | fsl,cpm-brg |
| 2046 | fsl,cpm1-brg |
| 2047 | fsl,cpm2-brg |
| 2048 | |
| 2049 | Properties: |
| 2050 | - reg : There may be an arbitrary number of reg resources; BRG |
| 2051 | numbers are assigned to these in order. |
| 2052 | - clock-frequency : Specifies the base frequency driving |
| 2053 | the BRG. |
| 2054 | |
| 2055 | Example: |
| 2056 | |
| 2057 | brg@119f0 { |
| 2058 | compatible = "fsl,mpc8272-brg", |
| 2059 | "fsl,cpm2-brg", |
| 2060 | "fsl,cpm-brg"; |
| 2061 | reg = <119f0 10 115f0 10>; |
| 2062 | clock-frequency = <d#25000000>; |
| 2063 | }; |
| 2064 | |
| 2065 | vi) Interrupt Controllers |
| 2066 | |
| 2067 | Currently defined compatibles: |
| 2068 | - fsl,cpm1-pic |
| 2069 | - only one interrupt cell |
| 2070 | - fsl,pq1-pic |
| 2071 | - fsl,cpm2-pic |
| 2072 | - second interrupt cell is level/sense: |
| 2073 | - 2 is falling edge |
| 2074 | - 8 is active low |
| 2075 | |
| 2076 | Example: |
| 2077 | |
| 2078 | interrupt-controller@10c00 { |
| 2079 | #interrupt-cells = <2>; |
| 2080 | interrupt-controller; |
| 2081 | reg = <10c00 80>; |
| 2082 | compatible = "mpc8272-pic", "fsl,cpm2-pic"; |
| 2083 | }; |
| 2084 | |
| 2085 | vii) USB (Universal Serial Bus Controller) |
| 2086 | |
| 2087 | Properties: |
| 2088 | - compatible : "fsl,cpm1-usb", "fsl,cpm2-usb", "fsl,qe-usb" |
| 2089 | |
| 2090 | Example: |
| 2091 | usb@11bc0 { |
| 2092 | #address-cells = <1>; |
| 2093 | #size-cells = <0>; |
| 2094 | compatible = "fsl,cpm2-usb"; |
| 2095 | reg = <11b60 18 8b00 100>; |
| 2096 | interrupts = <b 8>; |
| 2097 | interrupt-parent = <&PIC>; |
| 2098 | fsl,cpm-command = <2e600000>; |
| 2099 | }; |
| 2100 | |
Scott Wood | 15f8c60 | 2007-09-28 14:06:16 -0500 | [diff] [blame] | 2101 | viii) Multi-User RAM (MURAM) |
| 2102 | |
| 2103 | The multi-user/dual-ported RAM is expressed as a bus under the CPM node. |
| 2104 | |
| 2105 | Ranges must be set up subject to the following restrictions: |
| 2106 | |
| 2107 | - Children's reg nodes must be offsets from the start of all muram, even |
| 2108 | if the user-data area does not begin at zero. |
| 2109 | - If multiple range entries are used, the difference between the parent |
| 2110 | address and the child address must be the same in all, so that a single |
| 2111 | mapping can cover them all while maintaining the ability to determine |
| 2112 | CPM-side offsets with pointer subtraction. It is recommended that |
| 2113 | multiple range entries not be used. |
| 2114 | - A child address of zero must be translatable, even if no reg resources |
| 2115 | contain it. |
| 2116 | |
| 2117 | A child "data" node must exist, compatible with "fsl,cpm-muram-data", to |
| 2118 | indicate the portion of muram that is usable by the OS for arbitrary |
| 2119 | purposes. The data node may have an arbitrary number of reg resources, |
| 2120 | all of which contribute to the allocatable muram pool. |
| 2121 | |
| 2122 | Example, based on mpc8272: |
| 2123 | |
| 2124 | muram@0 { |
| 2125 | #address-cells = <1>; |
| 2126 | #size-cells = <1>; |
| 2127 | ranges = <0 0 10000>; |
| 2128 | |
| 2129 | data@0 { |
| 2130 | compatible = "fsl,cpm-muram-data"; |
| 2131 | reg = <0 2000 9800 800>; |
| 2132 | }; |
| 2133 | }; |
| 2134 | |
Scott Wood | 96fca1de | 2007-09-14 13:24:02 -0500 | [diff] [blame] | 2135 | m) Chipselect/Local Bus |
| 2136 | |
| 2137 | Properties: |
| 2138 | - name : Should be localbus |
| 2139 | - #address-cells : Should be either two or three. The first cell is the |
| 2140 | chipselect number, and the remaining cells are the |
| 2141 | offset into the chipselect. |
| 2142 | - #size-cells : Either one or two, depending on how large each chipselect |
| 2143 | can be. |
| 2144 | - ranges : Each range corresponds to a single chipselect, and cover |
| 2145 | the entire access window as configured. |
| 2146 | |
| 2147 | Example: |
| 2148 | localbus@f0010100 { |
Anton Vorontsov | 253772b | 2007-12-15 05:48:26 +1100 | [diff] [blame] | 2149 | compatible = "fsl,mpc8272-localbus", |
Scott Wood | 96fca1de | 2007-09-14 13:24:02 -0500 | [diff] [blame] | 2150 | "fsl,pq2-localbus"; |
| 2151 | #address-cells = <2>; |
| 2152 | #size-cells = <1>; |
| 2153 | reg = <f0010100 40>; |
| 2154 | |
| 2155 | ranges = <0 0 fe000000 02000000 |
| 2156 | 1 0 f4500000 00008000>; |
| 2157 | |
| 2158 | flash@0,0 { |
| 2159 | compatible = "jedec-flash"; |
| 2160 | reg = <0 0 2000000>; |
| 2161 | bank-width = <4>; |
| 2162 | device-width = <1>; |
| 2163 | }; |
| 2164 | |
| 2165 | board-control@1,0 { |
| 2166 | reg = <1 0 20>; |
| 2167 | compatible = "fsl,mpc8272ads-bcsr"; |
| 2168 | }; |
| 2169 | }; |
| 2170 | |
| 2171 | |
Linus Torvalds | e869086 | 2007-10-11 21:55:47 -0700 | [diff] [blame] | 2172 | n) 4xx/Axon EMAC ethernet nodes |
David Gibson | 1d3bb99 | 2007-08-23 13:56:01 +1000 | [diff] [blame] | 2173 | |
| 2174 | The EMAC ethernet controller in IBM and AMCC 4xx chips, and also |
| 2175 | the Axon bridge. To operate this needs to interact with a ths |
| 2176 | special McMAL DMA controller, and sometimes an RGMII or ZMII |
| 2177 | interface. In addition to the nodes and properties described |
| 2178 | below, the node for the OPB bus on which the EMAC sits must have a |
| 2179 | correct clock-frequency property. |
| 2180 | |
| 2181 | i) The EMAC node itself |
| 2182 | |
| 2183 | Required properties: |
| 2184 | - device_type : "network" |
| 2185 | |
| 2186 | - compatible : compatible list, contains 2 entries, first is |
| 2187 | "ibm,emac-CHIP" where CHIP is the host ASIC (440gx, |
| 2188 | 405gp, Axon) and second is either "ibm,emac" or |
| 2189 | "ibm,emac4". For Axon, thus, we have: "ibm,emac-axon", |
| 2190 | "ibm,emac4" |
| 2191 | - interrupts : <interrupt mapping for EMAC IRQ and WOL IRQ> |
| 2192 | - interrupt-parent : optional, if needed for interrupt mapping |
| 2193 | - reg : <registers mapping> |
| 2194 | - local-mac-address : 6 bytes, MAC address |
| 2195 | - mal-device : phandle of the associated McMAL node |
| 2196 | - mal-tx-channel : 1 cell, index of the tx channel on McMAL associated |
| 2197 | with this EMAC |
| 2198 | - mal-rx-channel : 1 cell, index of the rx channel on McMAL associated |
| 2199 | with this EMAC |
| 2200 | - cell-index : 1 cell, hardware index of the EMAC cell on a given |
| 2201 | ASIC (typically 0x0 and 0x1 for EMAC0 and EMAC1 on |
| 2202 | each Axon chip) |
| 2203 | - max-frame-size : 1 cell, maximum frame size supported in bytes |
| 2204 | - rx-fifo-size : 1 cell, Rx fifo size in bytes for 10 and 100 Mb/sec |
| 2205 | operations. |
| 2206 | For Axon, 2048 |
| 2207 | - tx-fifo-size : 1 cell, Tx fifo size in bytes for 10 and 100 Mb/sec |
| 2208 | operations. |
| 2209 | For Axon, 2048. |
| 2210 | - fifo-entry-size : 1 cell, size of a fifo entry (used to calculate |
| 2211 | thresholds). |
| 2212 | For Axon, 0x00000010 |
| 2213 | - mal-burst-size : 1 cell, MAL burst size (used to calculate thresholds) |
| 2214 | in bytes. |
| 2215 | For Axon, 0x00000100 (I think ...) |
| 2216 | - phy-mode : string, mode of operations of the PHY interface. |
| 2217 | Supported values are: "mii", "rmii", "smii", "rgmii", |
| 2218 | "tbi", "gmii", rtbi", "sgmii". |
| 2219 | For Axon on CAB, it is "rgmii" |
| 2220 | - mdio-device : 1 cell, required iff using shared MDIO registers |
| 2221 | (440EP). phandle of the EMAC to use to drive the |
| 2222 | MDIO lines for the PHY used by this EMAC. |
| 2223 | - zmii-device : 1 cell, required iff connected to a ZMII. phandle of |
| 2224 | the ZMII device node |
| 2225 | - zmii-channel : 1 cell, required iff connected to a ZMII. Which ZMII |
| 2226 | channel or 0xffffffff if ZMII is only used for MDIO. |
| 2227 | - rgmii-device : 1 cell, required iff connected to an RGMII. phandle |
| 2228 | of the RGMII device node. |
| 2229 | For Axon: phandle of plb5/plb4/opb/rgmii |
| 2230 | - rgmii-channel : 1 cell, required iff connected to an RGMII. Which |
| 2231 | RGMII channel is used by this EMAC. |
| 2232 | Fox Axon: present, whatever value is appropriate for each |
| 2233 | EMAC, that is the content of the current (bogus) "phy-port" |
| 2234 | property. |
| 2235 | |
David Gibson | 1d3bb99 | 2007-08-23 13:56:01 +1000 | [diff] [blame] | 2236 | Optional properties: |
| 2237 | - phy-address : 1 cell, optional, MDIO address of the PHY. If absent, |
| 2238 | a search is performed. |
| 2239 | - phy-map : 1 cell, optional, bitmap of addresses to probe the PHY |
| 2240 | for, used if phy-address is absent. bit 0x00000001 is |
| 2241 | MDIO address 0. |
| 2242 | For Axon it can be absent, thouugh my current driver |
| 2243 | doesn't handle phy-address yet so for now, keep |
| 2244 | 0x00ffffff in it. |
| 2245 | - rx-fifo-size-gige : 1 cell, Rx fifo size in bytes for 1000 Mb/sec |
| 2246 | operations (if absent the value is the same as |
| 2247 | rx-fifo-size). For Axon, either absent or 2048. |
| 2248 | - tx-fifo-size-gige : 1 cell, Tx fifo size in bytes for 1000 Mb/sec |
| 2249 | operations (if absent the value is the same as |
| 2250 | tx-fifo-size). For Axon, either absent or 2048. |
| 2251 | - tah-device : 1 cell, optional. If connected to a TAH engine for |
| 2252 | offload, phandle of the TAH device node. |
| 2253 | - tah-channel : 1 cell, optional. If appropriate, channel used on the |
| 2254 | TAH engine. |
| 2255 | |
| 2256 | Example: |
| 2257 | |
| 2258 | EMAC0: ethernet@40000800 { |
David Gibson | 1d3bb99 | 2007-08-23 13:56:01 +1000 | [diff] [blame] | 2259 | device_type = "network"; |
| 2260 | compatible = "ibm,emac-440gp", "ibm,emac"; |
| 2261 | interrupt-parent = <&UIC1>; |
| 2262 | interrupts = <1c 4 1d 4>; |
| 2263 | reg = <40000800 70>; |
| 2264 | local-mac-address = [00 04 AC E3 1B 1E]; |
| 2265 | mal-device = <&MAL0>; |
| 2266 | mal-tx-channel = <0 1>; |
| 2267 | mal-rx-channel = <0>; |
| 2268 | cell-index = <0>; |
| 2269 | max-frame-size = <5dc>; |
| 2270 | rx-fifo-size = <1000>; |
| 2271 | tx-fifo-size = <800>; |
| 2272 | phy-mode = "rmii"; |
| 2273 | phy-map = <00000001>; |
| 2274 | zmii-device = <&ZMII0>; |
| 2275 | zmii-channel = <0>; |
| 2276 | }; |
| 2277 | |
| 2278 | ii) McMAL node |
| 2279 | |
| 2280 | Required properties: |
| 2281 | - device_type : "dma-controller" |
| 2282 | - compatible : compatible list, containing 2 entries, first is |
| 2283 | "ibm,mcmal-CHIP" where CHIP is the host ASIC (like |
| 2284 | emac) and the second is either "ibm,mcmal" or |
| 2285 | "ibm,mcmal2". |
| 2286 | For Axon, "ibm,mcmal-axon","ibm,mcmal2" |
| 2287 | - interrupts : <interrupt mapping for the MAL interrupts sources: |
| 2288 | 5 sources: tx_eob, rx_eob, serr, txde, rxde>. |
| 2289 | For Axon: This is _different_ from the current |
| 2290 | firmware. We use the "delayed" interrupts for txeob |
| 2291 | and rxeob. Thus we end up with mapping those 5 MPIC |
| 2292 | interrupts, all level positive sensitive: 10, 11, 32, |
| 2293 | 33, 34 (in decimal) |
| 2294 | - dcr-reg : < DCR registers range > |
| 2295 | - dcr-parent : if needed for dcr-reg |
| 2296 | - num-tx-chans : 1 cell, number of Tx channels |
| 2297 | - num-rx-chans : 1 cell, number of Rx channels |
| 2298 | |
| 2299 | iii) ZMII node |
| 2300 | |
| 2301 | Required properties: |
| 2302 | - compatible : compatible list, containing 2 entries, first is |
| 2303 | "ibm,zmii-CHIP" where CHIP is the host ASIC (like |
| 2304 | EMAC) and the second is "ibm,zmii". |
| 2305 | For Axon, there is no ZMII node. |
| 2306 | - reg : <registers mapping> |
| 2307 | |
| 2308 | iv) RGMII node |
| 2309 | |
| 2310 | Required properties: |
| 2311 | - compatible : compatible list, containing 2 entries, first is |
| 2312 | "ibm,rgmii-CHIP" where CHIP is the host ASIC (like |
| 2313 | EMAC) and the second is "ibm,rgmii". |
| 2314 | For Axon, "ibm,rgmii-axon","ibm,rgmii" |
| 2315 | - reg : <registers mapping> |
| 2316 | - revision : as provided by the RGMII new version register if |
| 2317 | available. |
| 2318 | For Axon: 0x0000012a |
| 2319 | |
Timur Tabi | bc556ba | 2008-01-08 10:30:58 -0600 | [diff] [blame] | 2320 | o) Xilinx IP cores |
Grant Likely | 7ae0fa49 | 2007-10-23 14:27:41 +1000 | [diff] [blame] | 2321 | |
| 2322 | The Xilinx EDK toolchain ships with a set of IP cores (devices) for use |
| 2323 | in Xilinx Spartan and Virtex FPGAs. The devices cover the whole range |
| 2324 | of standard device types (network, serial, etc.) and miscellanious |
| 2325 | devices (gpio, LCD, spi, etc). Also, since these devices are |
| 2326 | implemented within the fpga fabric every instance of the device can be |
| 2327 | synthesised with different options that change the behaviour. |
| 2328 | |
| 2329 | Each IP-core has a set of parameters which the FPGA designer can use to |
| 2330 | control how the core is synthesized. Historically, the EDK tool would |
| 2331 | extract the device parameters relevant to device drivers and copy them |
| 2332 | into an 'xparameters.h' in the form of #define symbols. This tells the |
| 2333 | device drivers how the IP cores are configured, but it requres the kernel |
| 2334 | to be recompiled every time the FPGA bitstream is resynthesized. |
| 2335 | |
| 2336 | The new approach is to export the parameters into the device tree and |
| 2337 | generate a new device tree each time the FPGA bitstream changes. The |
| 2338 | parameters which used to be exported as #defines will now become |
| 2339 | properties of the device node. In general, device nodes for IP-cores |
| 2340 | will take the following form: |
| 2341 | |
Stephen Neuendorffer | ab99eee | 2008-01-09 06:35:07 +1100 | [diff] [blame] | 2342 | (name): (generic-name)@(base-address) { |
Grant Likely | 7ae0fa49 | 2007-10-23 14:27:41 +1000 | [diff] [blame] | 2343 | compatible = "xlnx,(ip-core-name)-(HW_VER)" |
| 2344 | [, (list of compatible devices), ...]; |
| 2345 | reg = <(baseaddr) (size)>; |
| 2346 | interrupt-parent = <&interrupt-controller-phandle>; |
| 2347 | interrupts = < ... >; |
| 2348 | xlnx,(parameter1) = "(string-value)"; |
| 2349 | xlnx,(parameter2) = <(int-value)>; |
| 2350 | }; |
| 2351 | |
Stephen Neuendorffer | ab99eee | 2008-01-09 06:35:07 +1100 | [diff] [blame] | 2352 | (generic-name): an open firmware-style name that describes the |
| 2353 | generic class of device. Preferably, this is one word, such |
| 2354 | as 'serial' or 'ethernet'. |
Grant Likely | 7ae0fa49 | 2007-10-23 14:27:41 +1000 | [diff] [blame] | 2355 | (ip-core-name): the name of the ip block (given after the BEGIN |
| 2356 | directive in system.mhs). Should be in lowercase |
| 2357 | and all underscores '_' converted to dashes '-'. |
| 2358 | (name): is derived from the "PARAMETER INSTANCE" value. |
| 2359 | (parameter#): C_* parameters from system.mhs. The C_ prefix is |
| 2360 | dropped from the parameter name, the name is converted |
| 2361 | to lowercase and all underscore '_' characters are |
| 2362 | converted to dashes '-'. |
Stephen Neuendorffer | ab99eee | 2008-01-09 06:35:07 +1100 | [diff] [blame] | 2363 | (baseaddr): the baseaddr parameter value (often named C_BASEADDR). |
Grant Likely | 7ae0fa49 | 2007-10-23 14:27:41 +1000 | [diff] [blame] | 2364 | (HW_VER): from the HW_VER parameter. |
Stephen Neuendorffer | ab99eee | 2008-01-09 06:35:07 +1100 | [diff] [blame] | 2365 | (size): the address range size (often C_HIGHADDR - C_BASEADDR + 1). |
Grant Likely | 7ae0fa49 | 2007-10-23 14:27:41 +1000 | [diff] [blame] | 2366 | |
| 2367 | Typically, the compatible list will include the exact IP core version |
| 2368 | followed by an older IP core version which implements the same |
| 2369 | interface or any other device with the same interface. |
| 2370 | |
| 2371 | 'reg', 'interrupt-parent' and 'interrupts' are all optional properties. |
| 2372 | |
| 2373 | For example, the following block from system.mhs: |
| 2374 | |
| 2375 | BEGIN opb_uartlite |
| 2376 | PARAMETER INSTANCE = opb_uartlite_0 |
| 2377 | PARAMETER HW_VER = 1.00.b |
| 2378 | PARAMETER C_BAUDRATE = 115200 |
| 2379 | PARAMETER C_DATA_BITS = 8 |
| 2380 | PARAMETER C_ODD_PARITY = 0 |
| 2381 | PARAMETER C_USE_PARITY = 0 |
| 2382 | PARAMETER C_CLK_FREQ = 50000000 |
| 2383 | PARAMETER C_BASEADDR = 0xEC100000 |
| 2384 | PARAMETER C_HIGHADDR = 0xEC10FFFF |
| 2385 | BUS_INTERFACE SOPB = opb_7 |
| 2386 | PORT OPB_Clk = CLK_50MHz |
| 2387 | PORT Interrupt = opb_uartlite_0_Interrupt |
| 2388 | PORT RX = opb_uartlite_0_RX |
| 2389 | PORT TX = opb_uartlite_0_TX |
| 2390 | PORT OPB_Rst = sys_bus_reset_0 |
| 2391 | END |
| 2392 | |
| 2393 | becomes the following device tree node: |
| 2394 | |
Stephen Neuendorffer | ab99eee | 2008-01-09 06:35:07 +1100 | [diff] [blame] | 2395 | opb_uartlite_0: serial@ec100000 { |
Grant Likely | 7ae0fa49 | 2007-10-23 14:27:41 +1000 | [diff] [blame] | 2396 | device_type = "serial"; |
| 2397 | compatible = "xlnx,opb-uartlite-1.00.b"; |
| 2398 | reg = <ec100000 10000>; |
Stephen Neuendorffer | ab99eee | 2008-01-09 06:35:07 +1100 | [diff] [blame] | 2399 | interrupt-parent = <&opb_intc_0>; |
Grant Likely | 7ae0fa49 | 2007-10-23 14:27:41 +1000 | [diff] [blame] | 2400 | interrupts = <1 0>; // got this from the opb_intc parameters |
| 2401 | current-speed = <d#115200>; // standard serial device prop |
| 2402 | clock-frequency = <d#50000000>; // standard serial device prop |
| 2403 | xlnx,data-bits = <8>; |
| 2404 | xlnx,odd-parity = <0>; |
| 2405 | xlnx,use-parity = <0>; |
| 2406 | }; |
| 2407 | |
Stephen Neuendorffer | ab99eee | 2008-01-09 06:35:07 +1100 | [diff] [blame] | 2408 | Some IP cores actually implement 2 or more logical devices. In |
| 2409 | this case, the device should still describe the whole IP core with |
| 2410 | a single node and add a child node for each logical device. The |
| 2411 | ranges property can be used to translate from parent IP-core to the |
| 2412 | registers of each device. In addition, the parent node should be |
| 2413 | compatible with the bus type 'xlnx,compound', and should contain |
| 2414 | #address-cells and #size-cells, as with any other bus. (Note: this |
| 2415 | makes the assumption that both logical devices have the same bus |
| 2416 | binding. If this is not true, then separate nodes should be used |
| 2417 | for each logical device). The 'cell-index' property can be used to |
| 2418 | enumerate logical devices within an IP core. For example, the |
| 2419 | following is the system.mhs entry for the dual ps2 controller found |
| 2420 | on the ml403 reference design. |
Grant Likely | 7ae0fa49 | 2007-10-23 14:27:41 +1000 | [diff] [blame] | 2421 | |
| 2422 | BEGIN opb_ps2_dual_ref |
| 2423 | PARAMETER INSTANCE = opb_ps2_dual_ref_0 |
| 2424 | PARAMETER HW_VER = 1.00.a |
| 2425 | PARAMETER C_BASEADDR = 0xA9000000 |
| 2426 | PARAMETER C_HIGHADDR = 0xA9001FFF |
| 2427 | BUS_INTERFACE SOPB = opb_v20_0 |
| 2428 | PORT Sys_Intr1 = ps2_1_intr |
| 2429 | PORT Sys_Intr2 = ps2_2_intr |
| 2430 | PORT Clkin1 = ps2_clk_rx_1 |
| 2431 | PORT Clkin2 = ps2_clk_rx_2 |
| 2432 | PORT Clkpd1 = ps2_clk_tx_1 |
| 2433 | PORT Clkpd2 = ps2_clk_tx_2 |
| 2434 | PORT Rx1 = ps2_d_rx_1 |
| 2435 | PORT Rx2 = ps2_d_rx_2 |
| 2436 | PORT Txpd1 = ps2_d_tx_1 |
| 2437 | PORT Txpd2 = ps2_d_tx_2 |
| 2438 | END |
| 2439 | |
| 2440 | It would result in the following device tree nodes: |
| 2441 | |
Stephen Neuendorffer | ab99eee | 2008-01-09 06:35:07 +1100 | [diff] [blame] | 2442 | opb_ps2_dual_ref_0: opb-ps2-dual-ref@a9000000 { |
| 2443 | #address-cells = <1>; |
| 2444 | #size-cells = <1>; |
| 2445 | compatible = "xlnx,compound"; |
Grant Likely | 7ae0fa49 | 2007-10-23 14:27:41 +1000 | [diff] [blame] | 2446 | ranges = <0 a9000000 2000>; |
| 2447 | // If this device had extra parameters, then they would |
| 2448 | // go here. |
| 2449 | ps2@0 { |
| 2450 | compatible = "xlnx,opb-ps2-dual-ref-1.00.a"; |
| 2451 | reg = <0 40>; |
Stephen Neuendorffer | ab99eee | 2008-01-09 06:35:07 +1100 | [diff] [blame] | 2452 | interrupt-parent = <&opb_intc_0>; |
Grant Likely | 7ae0fa49 | 2007-10-23 14:27:41 +1000 | [diff] [blame] | 2453 | interrupts = <3 0>; |
| 2454 | cell-index = <0>; |
| 2455 | }; |
| 2456 | ps2@1000 { |
| 2457 | compatible = "xlnx,opb-ps2-dual-ref-1.00.a"; |
| 2458 | reg = <1000 40>; |
Stephen Neuendorffer | ab99eee | 2008-01-09 06:35:07 +1100 | [diff] [blame] | 2459 | interrupt-parent = <&opb_intc_0>; |
Grant Likely | 7ae0fa49 | 2007-10-23 14:27:41 +1000 | [diff] [blame] | 2460 | interrupts = <3 0>; |
| 2461 | cell-index = <0>; |
| 2462 | }; |
| 2463 | }; |
| 2464 | |
| 2465 | Also, the system.mhs file defines bus attachments from the processor |
| 2466 | to the devices. The device tree structure should reflect the bus |
| 2467 | attachments. Again an example; this system.mhs fragment: |
| 2468 | |
| 2469 | BEGIN ppc405_virtex4 |
| 2470 | PARAMETER INSTANCE = ppc405_0 |
| 2471 | PARAMETER HW_VER = 1.01.a |
| 2472 | BUS_INTERFACE DPLB = plb_v34_0 |
| 2473 | BUS_INTERFACE IPLB = plb_v34_0 |
| 2474 | END |
| 2475 | |
| 2476 | BEGIN opb_intc |
| 2477 | PARAMETER INSTANCE = opb_intc_0 |
| 2478 | PARAMETER HW_VER = 1.00.c |
| 2479 | PARAMETER C_BASEADDR = 0xD1000FC0 |
| 2480 | PARAMETER C_HIGHADDR = 0xD1000FDF |
| 2481 | BUS_INTERFACE SOPB = opb_v20_0 |
| 2482 | END |
| 2483 | |
| 2484 | BEGIN opb_uart16550 |
| 2485 | PARAMETER INSTANCE = opb_uart16550_0 |
| 2486 | PARAMETER HW_VER = 1.00.d |
| 2487 | PARAMETER C_BASEADDR = 0xa0000000 |
| 2488 | PARAMETER C_HIGHADDR = 0xa0001FFF |
| 2489 | BUS_INTERFACE SOPB = opb_v20_0 |
| 2490 | END |
| 2491 | |
| 2492 | BEGIN plb_v34 |
| 2493 | PARAMETER INSTANCE = plb_v34_0 |
| 2494 | PARAMETER HW_VER = 1.02.a |
| 2495 | END |
| 2496 | |
| 2497 | BEGIN plb_bram_if_cntlr |
| 2498 | PARAMETER INSTANCE = plb_bram_if_cntlr_0 |
| 2499 | PARAMETER HW_VER = 1.00.b |
| 2500 | PARAMETER C_BASEADDR = 0xFFFF0000 |
| 2501 | PARAMETER C_HIGHADDR = 0xFFFFFFFF |
| 2502 | BUS_INTERFACE SPLB = plb_v34_0 |
| 2503 | END |
| 2504 | |
| 2505 | BEGIN plb2opb_bridge |
| 2506 | PARAMETER INSTANCE = plb2opb_bridge_0 |
| 2507 | PARAMETER HW_VER = 1.01.a |
| 2508 | PARAMETER C_RNG0_BASEADDR = 0x20000000 |
| 2509 | PARAMETER C_RNG0_HIGHADDR = 0x3FFFFFFF |
| 2510 | PARAMETER C_RNG1_BASEADDR = 0x60000000 |
| 2511 | PARAMETER C_RNG1_HIGHADDR = 0x7FFFFFFF |
| 2512 | PARAMETER C_RNG2_BASEADDR = 0x80000000 |
| 2513 | PARAMETER C_RNG2_HIGHADDR = 0xBFFFFFFF |
| 2514 | PARAMETER C_RNG3_BASEADDR = 0xC0000000 |
| 2515 | PARAMETER C_RNG3_HIGHADDR = 0xDFFFFFFF |
| 2516 | BUS_INTERFACE SPLB = plb_v34_0 |
| 2517 | BUS_INTERFACE MOPB = opb_v20_0 |
| 2518 | END |
| 2519 | |
| 2520 | Gives this device tree (some properties removed for clarity): |
| 2521 | |
Stephen Neuendorffer | ab99eee | 2008-01-09 06:35:07 +1100 | [diff] [blame] | 2522 | plb@0 { |
Grant Likely | 7ae0fa49 | 2007-10-23 14:27:41 +1000 | [diff] [blame] | 2523 | #address-cells = <1>; |
| 2524 | #size-cells = <1>; |
Stephen Neuendorffer | ab99eee | 2008-01-09 06:35:07 +1100 | [diff] [blame] | 2525 | compatible = "xlnx,plb-v34-1.02.a"; |
Grant Likely | 7ae0fa49 | 2007-10-23 14:27:41 +1000 | [diff] [blame] | 2526 | device_type = "ibm,plb"; |
| 2527 | ranges; // 1:1 translation |
| 2528 | |
Stephen Neuendorffer | ab99eee | 2008-01-09 06:35:07 +1100 | [diff] [blame] | 2529 | plb_bram_if_cntrl_0: bram@ffff0000 { |
Grant Likely | 7ae0fa49 | 2007-10-23 14:27:41 +1000 | [diff] [blame] | 2530 | reg = <ffff0000 10000>; |
| 2531 | } |
| 2532 | |
Stephen Neuendorffer | ab99eee | 2008-01-09 06:35:07 +1100 | [diff] [blame] | 2533 | opb@20000000 { |
Grant Likely | 7ae0fa49 | 2007-10-23 14:27:41 +1000 | [diff] [blame] | 2534 | #address-cells = <1>; |
| 2535 | #size-cells = <1>; |
| 2536 | ranges = <20000000 20000000 20000000 |
| 2537 | 60000000 60000000 20000000 |
| 2538 | 80000000 80000000 40000000 |
| 2539 | c0000000 c0000000 20000000>; |
| 2540 | |
Stephen Neuendorffer | ab99eee | 2008-01-09 06:35:07 +1100 | [diff] [blame] | 2541 | opb_uart16550_0: serial@a0000000 { |
Grant Likely | 7ae0fa49 | 2007-10-23 14:27:41 +1000 | [diff] [blame] | 2542 | reg = <a00000000 2000>; |
| 2543 | }; |
| 2544 | |
Stephen Neuendorffer | ab99eee | 2008-01-09 06:35:07 +1100 | [diff] [blame] | 2545 | opb_intc_0: interrupt-controller@d1000fc0 { |
Grant Likely | 7ae0fa49 | 2007-10-23 14:27:41 +1000 | [diff] [blame] | 2546 | reg = <d1000fc0 20>; |
| 2547 | }; |
| 2548 | }; |
| 2549 | }; |
| 2550 | |
| 2551 | That covers the general approach to binding xilinx IP cores into the |
| 2552 | device tree. The following are bindings for specific devices: |
| 2553 | |
| 2554 | i) Xilinx ML300 Framebuffer |
| 2555 | |
| 2556 | Simple framebuffer device from the ML300 reference design (also on the |
| 2557 | ML403 reference design as well as others). |
| 2558 | |
| 2559 | Optional properties: |
| 2560 | - resolution = <xres yres> : pixel resolution of framebuffer. Some |
| 2561 | implementations use a different resolution. |
| 2562 | Default is <d#640 d#480> |
| 2563 | - virt-resolution = <xvirt yvirt> : Size of framebuffer in memory. |
| 2564 | Default is <d#1024 d#480>. |
| 2565 | - rotate-display (empty) : rotate display 180 degrees. |
| 2566 | |
| 2567 | ii) Xilinx SystemACE |
| 2568 | |
| 2569 | The Xilinx SystemACE device is used to program FPGAs from an FPGA |
| 2570 | bitstream stored on a CF card. It can also be used as a generic CF |
| 2571 | interface device. |
| 2572 | |
| 2573 | Optional properties: |
| 2574 | - 8-bit (empty) : Set this property for SystemACE in 8 bit mode |
| 2575 | |
| 2576 | iii) Xilinx EMAC and Xilinx TEMAC |
| 2577 | |
| 2578 | Xilinx Ethernet devices. In addition to general xilinx properties |
| 2579 | listed above, nodes for these devices should include a phy-handle |
| 2580 | property, and may include other common network device properties |
| 2581 | like local-mac-address. |
| 2582 | |
| 2583 | iv) Xilinx Uartlite |
| 2584 | |
| 2585 | Xilinx uartlite devices are simple fixed speed serial ports. |
| 2586 | |
| 2587 | Requred properties: |
| 2588 | - current-speed : Baud rate of uartlite |
| 2589 | |
Stephen Neuendorffer | ef66a9d | 2008-02-06 04:24:10 +1100 | [diff] [blame] | 2590 | v) Xilinx hwicap |
| 2591 | |
| 2592 | Xilinx hwicap devices provide access to the configuration logic |
| 2593 | of the FPGA through the Internal Configuration Access Port |
| 2594 | (ICAP). The ICAP enables partial reconfiguration of the FPGA, |
| 2595 | readback of the configuration information, and some control over |
| 2596 | 'warm boots' of the FPGA fabric. |
| 2597 | |
| 2598 | Required properties: |
| 2599 | - xlnx,family : The family of the FPGA, necessary since the |
| 2600 | capabilities of the underlying ICAP hardware |
| 2601 | differ between different families. May be |
| 2602 | 'virtex2p', 'virtex4', or 'virtex5'. |
| 2603 | |
John Linn | b912b5e | 2008-04-03 10:22:19 +1100 | [diff] [blame] | 2604 | vi) Xilinx Uart 16550 |
| 2605 | |
| 2606 | Xilinx UART 16550 devices are very similar to the NS16550 but with |
| 2607 | different register spacing and an offset from the base address. |
| 2608 | |
| 2609 | Requred properties: |
| 2610 | - clock-frequency : Frequency of the clock input |
| 2611 | - reg-offset : A value of 3 is required |
| 2612 | - reg-shift : A value of 2 is required |
| 2613 | |
| 2614 | |
Timur Tabi | c7d24a2 | 2008-01-18 09:24:53 -0600 | [diff] [blame] | 2615 | p) Freescale Synchronous Serial Interface |
| 2616 | |
| 2617 | The SSI is a serial device that communicates with audio codecs. It can |
| 2618 | be programmed in AC97, I2S, left-justified, or right-justified modes. |
| 2619 | |
| 2620 | Required properties: |
| 2621 | - compatible : compatible list, containing "fsl,ssi" |
| 2622 | - cell-index : the SSI, <0> = SSI1, <1> = SSI2, and so on |
| 2623 | - reg : offset and length of the register set for the device |
| 2624 | - interrupts : <a b> where a is the interrupt number and b is a |
| 2625 | field that represents an encoding of the sense and |
| 2626 | level information for the interrupt. This should be |
| 2627 | encoded based on the information in section 2) |
| 2628 | depending on the type of interrupt controller you |
| 2629 | have. |
| 2630 | - interrupt-parent : the phandle for the interrupt controller that |
| 2631 | services interrupts for this device. |
| 2632 | - fsl,mode : the operating mode for the SSI interface |
| 2633 | "i2s-slave" - I2S mode, SSI is clock slave |
| 2634 | "i2s-master" - I2S mode, SSI is clock master |
| 2635 | "lj-slave" - left-justified mode, SSI is clock slave |
| 2636 | "lj-master" - l.j. mode, SSI is clock master |
| 2637 | "rj-slave" - right-justified mode, SSI is clock slave |
| 2638 | "rj-master" - r.j., SSI is clock master |
| 2639 | "ac97-slave" - AC97 mode, SSI is clock slave |
| 2640 | "ac97-master" - AC97 mode, SSI is clock master |
| 2641 | |
| 2642 | Optional properties: |
| 2643 | - codec-handle : phandle to a 'codec' node that defines an audio |
| 2644 | codec connected to this SSI. This node is typically |
| 2645 | a child of an I2C or other control node. |
| 2646 | |
| 2647 | Child 'codec' node required properties: |
| 2648 | - compatible : compatible list, contains the name of the codec |
| 2649 | |
| 2650 | Child 'codec' node optional properties: |
| 2651 | - clock-frequency : The frequency of the input clock, which typically |
| 2652 | comes from an on-board dedicated oscillator. |
| 2653 | |
Zhang Wei | 457aa81 | 2007-10-30 17:23:48 +0800 | [diff] [blame] | 2654 | * Freescale 83xx DMA Controller |
| 2655 | |
| 2656 | Freescale PowerPC 83xx have on chip general purpose DMA controllers. |
| 2657 | |
| 2658 | Required properties: |
| 2659 | |
| 2660 | - compatible : compatible list, contains 2 entries, first is |
| 2661 | "fsl,CHIP-dma", where CHIP is the processor |
| 2662 | (mpc8349, mpc8360, etc.) and the second is |
| 2663 | "fsl,elo-dma" |
| 2664 | - reg : <registers mapping for DMA general status reg> |
| 2665 | - ranges : Should be defined as specified in 1) to describe the |
| 2666 | DMA controller channels. |
| 2667 | - cell-index : controller index. 0 for controller @ 0x8100 |
| 2668 | - interrupts : <interrupt mapping for DMA IRQ> |
| 2669 | - interrupt-parent : optional, if needed for interrupt mapping |
| 2670 | |
| 2671 | |
| 2672 | - DMA channel nodes: |
| 2673 | - compatible : compatible list, contains 2 entries, first is |
| 2674 | "fsl,CHIP-dma-channel", where CHIP is the processor |
| 2675 | (mpc8349, mpc8350, etc.) and the second is |
| 2676 | "fsl,elo-dma-channel" |
| 2677 | - reg : <registers mapping for channel> |
| 2678 | - cell-index : dma channel index starts at 0. |
| 2679 | |
| 2680 | Optional properties: |
| 2681 | - interrupts : <interrupt mapping for DMA channel IRQ> |
| 2682 | (on 83xx this is expected to be identical to |
| 2683 | the interrupts property of the parent node) |
| 2684 | - interrupt-parent : optional, if needed for interrupt mapping |
| 2685 | |
| 2686 | Example: |
| 2687 | dma@82a8 { |
| 2688 | #address-cells = <1>; |
| 2689 | #size-cells = <1>; |
| 2690 | compatible = "fsl,mpc8349-dma", "fsl,elo-dma"; |
| 2691 | reg = <82a8 4>; |
| 2692 | ranges = <0 8100 1a4>; |
| 2693 | interrupt-parent = <&ipic>; |
| 2694 | interrupts = <47 8>; |
| 2695 | cell-index = <0>; |
| 2696 | dma-channel@0 { |
| 2697 | compatible = "fsl,mpc8349-dma-channel", "fsl,elo-dma-channel"; |
| 2698 | cell-index = <0>; |
| 2699 | reg = <0 80>; |
| 2700 | }; |
| 2701 | dma-channel@80 { |
| 2702 | compatible = "fsl,mpc8349-dma-channel", "fsl,elo-dma-channel"; |
| 2703 | cell-index = <1>; |
| 2704 | reg = <80 80>; |
| 2705 | }; |
| 2706 | dma-channel@100 { |
| 2707 | compatible = "fsl,mpc8349-dma-channel", "fsl,elo-dma-channel"; |
| 2708 | cell-index = <2>; |
| 2709 | reg = <100 80>; |
| 2710 | }; |
| 2711 | dma-channel@180 { |
| 2712 | compatible = "fsl,mpc8349-dma-channel", "fsl,elo-dma-channel"; |
| 2713 | cell-index = <3>; |
| 2714 | reg = <180 80>; |
| 2715 | }; |
| 2716 | }; |
| 2717 | |
| 2718 | * Freescale 85xx/86xx DMA Controller |
| 2719 | |
| 2720 | Freescale PowerPC 85xx/86xx have on chip general purpose DMA controllers. |
| 2721 | |
| 2722 | Required properties: |
| 2723 | |
| 2724 | - compatible : compatible list, contains 2 entries, first is |
| 2725 | "fsl,CHIP-dma", where CHIP is the processor |
| 2726 | (mpc8540, mpc8540, etc.) and the second is |
| 2727 | "fsl,eloplus-dma" |
| 2728 | - reg : <registers mapping for DMA general status reg> |
| 2729 | - cell-index : controller index. 0 for controller @ 0x21000, |
| 2730 | 1 for controller @ 0xc000 |
| 2731 | - ranges : Should be defined as specified in 1) to describe the |
| 2732 | DMA controller channels. |
| 2733 | |
| 2734 | - DMA channel nodes: |
| 2735 | - compatible : compatible list, contains 2 entries, first is |
| 2736 | "fsl,CHIP-dma-channel", where CHIP is the processor |
| 2737 | (mpc8540, mpc8560, etc.) and the second is |
| 2738 | "fsl,eloplus-dma-channel" |
| 2739 | - cell-index : dma channel index starts at 0. |
| 2740 | - reg : <registers mapping for channel> |
| 2741 | - interrupts : <interrupt mapping for DMA channel IRQ> |
| 2742 | - interrupt-parent : optional, if needed for interrupt mapping |
| 2743 | |
| 2744 | Example: |
| 2745 | dma@21300 { |
| 2746 | #address-cells = <1>; |
| 2747 | #size-cells = <1>; |
| 2748 | compatible = "fsl,mpc8540-dma", "fsl,eloplus-dma"; |
| 2749 | reg = <21300 4>; |
| 2750 | ranges = <0 21100 200>; |
| 2751 | cell-index = <0>; |
| 2752 | dma-channel@0 { |
| 2753 | compatible = "fsl,mpc8540-dma-channel", "fsl,eloplus-dma-channel"; |
| 2754 | reg = <0 80>; |
| 2755 | cell-index = <0>; |
| 2756 | interrupt-parent = <&mpic>; |
| 2757 | interrupts = <14 2>; |
| 2758 | }; |
| 2759 | dma-channel@80 { |
| 2760 | compatible = "fsl,mpc8540-dma-channel", "fsl,eloplus-dma-channel"; |
| 2761 | reg = <80 80>; |
| 2762 | cell-index = <1>; |
| 2763 | interrupt-parent = <&mpic>; |
| 2764 | interrupts = <15 2>; |
| 2765 | }; |
| 2766 | dma-channel@100 { |
| 2767 | compatible = "fsl,mpc8540-dma-channel", "fsl,eloplus-dma-channel"; |
| 2768 | reg = <100 80>; |
| 2769 | cell-index = <2>; |
| 2770 | interrupt-parent = <&mpic>; |
| 2771 | interrupts = <16 2>; |
| 2772 | }; |
| 2773 | dma-channel@180 { |
| 2774 | compatible = "fsl,mpc8540-dma-channel", "fsl,eloplus-dma-channel"; |
| 2775 | reg = <180 80>; |
| 2776 | cell-index = <3>; |
| 2777 | interrupt-parent = <&mpic>; |
| 2778 | interrupts = <17 2>; |
| 2779 | }; |
| 2780 | }; |
| 2781 | |
Li Yang | b61ad65 | 2007-10-19 19:38:46 +0800 | [diff] [blame] | 2782 | * Freescale 8xxx/3.0 Gb/s SATA nodes |
| 2783 | |
| 2784 | SATA nodes are defined to describe on-chip Serial ATA controllers. |
| 2785 | Each SATA port should have its own node. |
| 2786 | |
| 2787 | Required properties: |
| 2788 | - compatible : compatible list, contains 2 entries, first is |
| 2789 | "fsl,CHIP-sata", where CHIP is the processor |
| 2790 | (mpc8315, mpc8379, etc.) and the second is |
| 2791 | "fsl,pq-sata" |
| 2792 | - interrupts : <interrupt mapping for SATA IRQ> |
| 2793 | - cell-index : controller index. |
| 2794 | 1 for controller @ 0x18000 |
| 2795 | 2 for controller @ 0x19000 |
| 2796 | 3 for controller @ 0x1a000 |
| 2797 | 4 for controller @ 0x1b000 |
| 2798 | |
| 2799 | Optional properties: |
| 2800 | - interrupt-parent : optional, if needed for interrupt mapping |
| 2801 | - reg : <registers mapping> |
| 2802 | |
| 2803 | Example: |
| 2804 | |
| 2805 | sata@18000 { |
| 2806 | compatible = "fsl,mpc8379-sata", "fsl,pq-sata"; |
| 2807 | reg = <0x18000 0x1000>; |
| 2808 | cell-index = <1>; |
| 2809 | interrupts = <2c 8>; |
| 2810 | interrupt-parent = < &ipic >; |
| 2811 | }; |
Timur Tabi | c7d24a2 | 2008-01-18 09:24:53 -0600 | [diff] [blame] | 2812 | |
Valentine Barshak | 41abd68 | 2007-09-25 05:27:56 +1000 | [diff] [blame] | 2813 | q) USB EHCI controllers |
| 2814 | |
| 2815 | Required properties: |
| 2816 | - compatible : should be "usb-ehci". |
| 2817 | - reg : should contain at least address and length of the standard EHCI |
| 2818 | register set for the device. Optional platform-dependent registers |
| 2819 | (debug-port or other) can be also specified here, but only after |
| 2820 | definition of standard EHCI registers. |
| 2821 | - interrupts : one EHCI interrupt should be described here. |
| 2822 | If device registers are implemented in big endian mode, the device |
| 2823 | node should have "big-endian-regs" property. |
| 2824 | If controller implementation operates with big endian descriptors, |
| 2825 | "big-endian-desc" property should be specified. |
| 2826 | If both big endian registers and descriptors are used by the controller |
| 2827 | implementation, "big-endian" property can be specified instead of having |
| 2828 | both "big-endian-regs" and "big-endian-desc". |
| 2829 | |
| 2830 | Example (Sequoia 440EPx): |
| 2831 | ehci@e0000300 { |
| 2832 | compatible = "ibm,usb-ehci-440epx", "usb-ehci"; |
| 2833 | interrupt-parent = <&UIC0>; |
| 2834 | interrupts = <1a 4>; |
| 2835 | reg = <0 e0000300 90 0 e0000390 70>; |
| 2836 | big-endian; |
| 2837 | }; |
| 2838 | |
York Sun | 9b53a9e | 2008-04-28 02:15:34 -0700 | [diff] [blame] | 2839 | r) Freescale Display Interface Unit |
| 2840 | |
| 2841 | The Freescale DIU is a LCD controller, with proper hardware, it can also |
| 2842 | drive DVI monitors. |
| 2843 | |
| 2844 | Required properties: |
| 2845 | - compatible : should be "fsl-diu". |
| 2846 | - reg : should contain at least address and length of the DIU register |
| 2847 | set. |
| 2848 | - Interrupts : one DIU interrupt should be describe here. |
| 2849 | |
| 2850 | Example (MPC8610HPCD) |
| 2851 | display@2c000 { |
| 2852 | compatible = "fsl,diu"; |
| 2853 | reg = <0x2c000 100>; |
| 2854 | interrupts = <72 2>; |
| 2855 | interrupt-parent = <&mpic>; |
| 2856 | }; |
| 2857 | |
| 2858 | s) Freescale on board FPGA |
| 2859 | |
| 2860 | This is the memory-mapped registers for on board FPGA. |
| 2861 | |
| 2862 | Required properities: |
| 2863 | - compatible : should be "fsl,fpga-pixis". |
| 2864 | - reg : should contain the address and the lenght of the FPPGA register |
| 2865 | set. |
| 2866 | |
| 2867 | Example (MPC8610HPCD) |
| 2868 | board-control@e8000000 { |
| 2869 | compatible = "fsl,fpga-pixis"; |
| 2870 | reg = <0xe8000000 32>; |
| 2871 | }; |
Valentine Barshak | 41abd68 | 2007-09-25 05:27:56 +1000 | [diff] [blame] | 2872 | |
Dale Farnsworth | f5412c4 | 2008-04-08 08:12:07 +1000 | [diff] [blame] | 2873 | VII - Marvell Discovery mv64[345]6x System Controller chips |
| 2874 | =========================================================== |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 2875 | |
Dale Farnsworth | f5412c4 | 2008-04-08 08:12:07 +1000 | [diff] [blame] | 2876 | The Marvell mv64[345]60 series of system controller chips contain |
| 2877 | many of the peripherals needed to implement a complete computer |
| 2878 | system. In this section, we define device tree nodes to describe |
| 2879 | the system controller chip itself and each of the peripherals |
| 2880 | which it contains. Compatible string values for each node are |
| 2881 | prefixed with the string "marvell,", for Marvell Technology Group Ltd. |
| 2882 | |
| 2883 | 1) The /system-controller node |
| 2884 | |
| 2885 | This node is used to represent the system-controller and must be |
| 2886 | present when the system uses a system contller chip. The top-level |
| 2887 | system-controller node contains information that is global to all |
| 2888 | devices within the system controller chip. The node name begins |
| 2889 | with "system-controller" followed by the unit address, which is |
| 2890 | the base address of the memory-mapped register set for the system |
| 2891 | controller chip. |
| 2892 | |
| 2893 | Required properties: |
| 2894 | |
| 2895 | - ranges : Describes the translation of system controller addresses |
| 2896 | for memory mapped registers. |
| 2897 | - clock-frequency: Contains the main clock frequency for the system |
| 2898 | controller chip. |
| 2899 | - reg : This property defines the address and size of the |
| 2900 | memory-mapped registers contained within the system controller |
| 2901 | chip. The address specified in the "reg" property should match |
| 2902 | the unit address of the system-controller node. |
| 2903 | - #address-cells : Address representation for system controller |
| 2904 | devices. This field represents the number of cells needed to |
| 2905 | represent the address of the memory-mapped registers of devices |
| 2906 | within the system controller chip. |
| 2907 | - #size-cells : Size representation for for the memory-mapped |
| 2908 | registers within the system controller chip. |
| 2909 | - #interrupt-cells : Defines the width of cells used to represent |
| 2910 | interrupts. |
| 2911 | |
| 2912 | Optional properties: |
| 2913 | |
| 2914 | - model : The specific model of the system controller chip. Such |
| 2915 | as, "mv64360", "mv64460", or "mv64560". |
| 2916 | - compatible : A string identifying the compatibility identifiers |
| 2917 | of the system controller chip. |
| 2918 | |
| 2919 | The system-controller node contains child nodes for each system |
| 2920 | controller device that the platform uses. Nodes should not be created |
| 2921 | for devices which exist on the system controller chip but are not used |
| 2922 | |
| 2923 | Example Marvell Discovery mv64360 system-controller node: |
| 2924 | |
| 2925 | system-controller@f1000000 { /* Marvell Discovery mv64360 */ |
| 2926 | #address-cells = <1>; |
| 2927 | #size-cells = <1>; |
| 2928 | model = "mv64360"; /* Default */ |
| 2929 | compatible = "marvell,mv64360"; |
| 2930 | clock-frequency = <133333333>; |
| 2931 | reg = <0xf1000000 0x10000>; |
| 2932 | virtual-reg = <0xf1000000>; |
| 2933 | ranges = <0x88000000 0x88000000 0x1000000 /* PCI 0 I/O Space */ |
| 2934 | 0x80000000 0x80000000 0x8000000 /* PCI 0 MEM Space */ |
| 2935 | 0xa0000000 0xa0000000 0x4000000 /* User FLASH */ |
| 2936 | 0x00000000 0xf1000000 0x0010000 /* Bridge's regs */ |
| 2937 | 0xf2000000 0xf2000000 0x0040000>;/* Integrated SRAM */ |
| 2938 | |
| 2939 | [ child node definitions... ] |
| 2940 | } |
| 2941 | |
| 2942 | 2) Child nodes of /system-controller |
| 2943 | |
| 2944 | a) Marvell Discovery MDIO bus |
| 2945 | |
| 2946 | The MDIO is a bus to which the PHY devices are connected. For each |
| 2947 | device that exists on this bus, a child node should be created. See |
| 2948 | the definition of the PHY node below for an example of how to define |
| 2949 | a PHY. |
| 2950 | |
| 2951 | Required properties: |
| 2952 | - #address-cells : Should be <1> |
| 2953 | - #size-cells : Should be <0> |
| 2954 | - device_type : Should be "mdio" |
| 2955 | - compatible : Should be "marvell,mv64360-mdio" |
| 2956 | |
| 2957 | Example: |
| 2958 | |
| 2959 | mdio { |
| 2960 | #address-cells = <1>; |
| 2961 | #size-cells = <0>; |
| 2962 | device_type = "mdio"; |
| 2963 | compatible = "marvell,mv64360-mdio"; |
| 2964 | |
| 2965 | ethernet-phy@0 { |
| 2966 | ...... |
| 2967 | }; |
| 2968 | }; |
| 2969 | |
| 2970 | |
| 2971 | b) Marvell Discovery ethernet controller |
| 2972 | |
| 2973 | The Discover ethernet controller is described with two levels |
| 2974 | of nodes. The first level describes an ethernet silicon block |
| 2975 | and the second level describes up to 3 ethernet nodes within |
| 2976 | that block. The reason for the multiple levels is that the |
| 2977 | registers for the node are interleaved within a single set |
| 2978 | of registers. The "ethernet-block" level describes the |
| 2979 | shared register set, and the "ethernet" nodes describe ethernet |
| 2980 | port-specific properties. |
| 2981 | |
| 2982 | Ethernet block node |
| 2983 | |
| 2984 | Required properties: |
| 2985 | - #address-cells : <1> |
| 2986 | - #size-cells : <0> |
| 2987 | - compatible : "marvell,mv64360-eth-block" |
| 2988 | - reg : Offset and length of the register set for this block |
| 2989 | |
| 2990 | Example Discovery Ethernet block node: |
| 2991 | ethernet-block@2000 { |
| 2992 | #address-cells = <1>; |
| 2993 | #size-cells = <0>; |
| 2994 | compatible = "marvell,mv64360-eth-block"; |
| 2995 | reg = <0x2000 0x2000>; |
| 2996 | ethernet@0 { |
| 2997 | ....... |
| 2998 | }; |
| 2999 | }; |
| 3000 | |
| 3001 | Ethernet port node |
| 3002 | |
| 3003 | Required properties: |
| 3004 | - device_type : Should be "network". |
| 3005 | - compatible : Should be "marvell,mv64360-eth". |
| 3006 | - reg : Should be <0>, <1>, or <2>, according to which registers |
| 3007 | within the silicon block the device uses. |
| 3008 | - interrupts : <a> where a is the interrupt number for the port. |
| 3009 | - interrupt-parent : the phandle for the interrupt controller |
| 3010 | that services interrupts for this device. |
| 3011 | - phy : the phandle for the PHY connected to this ethernet |
| 3012 | controller. |
| 3013 | - local-mac-address : 6 bytes, MAC address |
| 3014 | |
| 3015 | Example Discovery Ethernet port node: |
| 3016 | ethernet@0 { |
| 3017 | device_type = "network"; |
| 3018 | compatible = "marvell,mv64360-eth"; |
| 3019 | reg = <0>; |
| 3020 | interrupts = <32>; |
| 3021 | interrupt-parent = <&PIC>; |
| 3022 | phy = <&PHY0>; |
| 3023 | local-mac-address = [ 00 00 00 00 00 00 ]; |
| 3024 | }; |
| 3025 | |
| 3026 | |
| 3027 | |
| 3028 | c) Marvell Discovery PHY nodes |
| 3029 | |
| 3030 | Required properties: |
| 3031 | - device_type : Should be "ethernet-phy" |
| 3032 | - interrupts : <a> where a is the interrupt number for this phy. |
| 3033 | - interrupt-parent : the phandle for the interrupt controller that |
| 3034 | services interrupts for this device. |
| 3035 | - reg : The ID number for the phy, usually a small integer |
| 3036 | |
| 3037 | Example Discovery PHY node: |
| 3038 | ethernet-phy@1 { |
| 3039 | device_type = "ethernet-phy"; |
| 3040 | compatible = "broadcom,bcm5421"; |
| 3041 | interrupts = <76>; /* GPP 12 */ |
| 3042 | interrupt-parent = <&PIC>; |
| 3043 | reg = <1>; |
| 3044 | }; |
| 3045 | |
| 3046 | |
| 3047 | d) Marvell Discovery SDMA nodes |
| 3048 | |
| 3049 | Represent DMA hardware associated with the MPSC (multiprotocol |
| 3050 | serial controllers). |
| 3051 | |
| 3052 | Required properties: |
| 3053 | - compatible : "marvell,mv64360-sdma" |
| 3054 | - reg : Offset and length of the register set for this device |
| 3055 | - interrupts : <a> where a is the interrupt number for the DMA |
| 3056 | device. |
| 3057 | - interrupt-parent : the phandle for the interrupt controller |
| 3058 | that services interrupts for this device. |
| 3059 | |
| 3060 | Example Discovery SDMA node: |
| 3061 | sdma@4000 { |
| 3062 | compatible = "marvell,mv64360-sdma"; |
| 3063 | reg = <0x4000 0xc18>; |
| 3064 | virtual-reg = <0xf1004000>; |
| 3065 | interrupts = <36>; |
| 3066 | interrupt-parent = <&PIC>; |
| 3067 | }; |
| 3068 | |
| 3069 | |
| 3070 | e) Marvell Discovery BRG nodes |
| 3071 | |
| 3072 | Represent baud rate generator hardware associated with the MPSC |
| 3073 | (multiprotocol serial controllers). |
| 3074 | |
| 3075 | Required properties: |
| 3076 | - compatible : "marvell,mv64360-brg" |
| 3077 | - reg : Offset and length of the register set for this device |
| 3078 | - clock-src : A value from 0 to 15 which selects the clock |
| 3079 | source for the baud rate generator. This value corresponds |
| 3080 | to the CLKS value in the BRGx configuration register. See |
| 3081 | the mv64x60 User's Manual. |
| 3082 | - clock-frequence : The frequency (in Hz) of the baud rate |
| 3083 | generator's input clock. |
| 3084 | - current-speed : The current speed setting (presumably by |
| 3085 | firmware) of the baud rate generator. |
| 3086 | |
| 3087 | Example Discovery BRG node: |
| 3088 | brg@b200 { |
| 3089 | compatible = "marvell,mv64360-brg"; |
| 3090 | reg = <0xb200 0x8>; |
| 3091 | clock-src = <8>; |
| 3092 | clock-frequency = <133333333>; |
| 3093 | current-speed = <9600>; |
| 3094 | }; |
| 3095 | |
| 3096 | |
| 3097 | f) Marvell Discovery CUNIT nodes |
| 3098 | |
| 3099 | Represent the Serial Communications Unit device hardware. |
| 3100 | |
| 3101 | Required properties: |
| 3102 | - reg : Offset and length of the register set for this device |
| 3103 | |
| 3104 | Example Discovery CUNIT node: |
| 3105 | cunit@f200 { |
| 3106 | reg = <0xf200 0x200>; |
| 3107 | }; |
| 3108 | |
| 3109 | |
| 3110 | g) Marvell Discovery MPSCROUTING nodes |
| 3111 | |
| 3112 | Represent the Discovery's MPSC routing hardware |
| 3113 | |
| 3114 | Required properties: |
| 3115 | - reg : Offset and length of the register set for this device |
| 3116 | |
| 3117 | Example Discovery CUNIT node: |
| 3118 | mpscrouting@b500 { |
| 3119 | reg = <0xb400 0xc>; |
| 3120 | }; |
| 3121 | |
| 3122 | |
| 3123 | h) Marvell Discovery MPSCINTR nodes |
| 3124 | |
| 3125 | Represent the Discovery's MPSC DMA interrupt hardware registers |
| 3126 | (SDMA cause and mask registers). |
| 3127 | |
| 3128 | Required properties: |
| 3129 | - reg : Offset and length of the register set for this device |
| 3130 | |
| 3131 | Example Discovery MPSCINTR node: |
| 3132 | mpsintr@b800 { |
| 3133 | reg = <0xb800 0x100>; |
| 3134 | }; |
| 3135 | |
| 3136 | |
| 3137 | i) Marvell Discovery MPSC nodes |
| 3138 | |
| 3139 | Represent the Discovery's MPSC (Multiprotocol Serial Controller) |
| 3140 | serial port. |
| 3141 | |
| 3142 | Required properties: |
| 3143 | - device_type : "serial" |
| 3144 | - compatible : "marvell,mv64360-mpsc" |
| 3145 | - reg : Offset and length of the register set for this device |
| 3146 | - sdma : the phandle for the SDMA node used by this port |
| 3147 | - brg : the phandle for the BRG node used by this port |
| 3148 | - cunit : the phandle for the CUNIT node used by this port |
| 3149 | - mpscrouting : the phandle for the MPSCROUTING node used by this port |
| 3150 | - mpscintr : the phandle for the MPSCINTR node used by this port |
| 3151 | - cell-index : the hardware index of this cell in the MPSC core |
| 3152 | - max_idle : value needed for MPSC CHR3 (Maximum Frame Length) |
| 3153 | register |
| 3154 | - interrupts : <a> where a is the interrupt number for the MPSC. |
| 3155 | - interrupt-parent : the phandle for the interrupt controller |
| 3156 | that services interrupts for this device. |
| 3157 | |
| 3158 | Example Discovery MPSCINTR node: |
| 3159 | mpsc@8000 { |
| 3160 | device_type = "serial"; |
| 3161 | compatible = "marvell,mv64360-mpsc"; |
| 3162 | reg = <0x8000 0x38>; |
| 3163 | virtual-reg = <0xf1008000>; |
| 3164 | sdma = <&SDMA0>; |
| 3165 | brg = <&BRG0>; |
| 3166 | cunit = <&CUNIT>; |
| 3167 | mpscrouting = <&MPSCROUTING>; |
| 3168 | mpscintr = <&MPSCINTR>; |
| 3169 | cell-index = <0>; |
| 3170 | max_idle = <40>; |
| 3171 | interrupts = <40>; |
| 3172 | interrupt-parent = <&PIC>; |
| 3173 | }; |
| 3174 | |
| 3175 | |
| 3176 | j) Marvell Discovery Watch Dog Timer nodes |
| 3177 | |
| 3178 | Represent the Discovery's watchdog timer hardware |
| 3179 | |
| 3180 | Required properties: |
| 3181 | - compatible : "marvell,mv64360-wdt" |
| 3182 | - reg : Offset and length of the register set for this device |
| 3183 | |
| 3184 | Example Discovery Watch Dog Timer node: |
| 3185 | wdt@b410 { |
| 3186 | compatible = "marvell,mv64360-wdt"; |
| 3187 | reg = <0xb410 0x8>; |
| 3188 | }; |
| 3189 | |
| 3190 | |
| 3191 | k) Marvell Discovery I2C nodes |
| 3192 | |
| 3193 | Represent the Discovery's I2C hardware |
| 3194 | |
| 3195 | Required properties: |
| 3196 | - device_type : "i2c" |
| 3197 | - compatible : "marvell,mv64360-i2c" |
| 3198 | - reg : Offset and length of the register set for this device |
| 3199 | - interrupts : <a> where a is the interrupt number for the I2C. |
| 3200 | - interrupt-parent : the phandle for the interrupt controller |
| 3201 | that services interrupts for this device. |
| 3202 | |
| 3203 | Example Discovery I2C node: |
| 3204 | compatible = "marvell,mv64360-i2c"; |
| 3205 | reg = <0xc000 0x20>; |
| 3206 | virtual-reg = <0xf100c000>; |
| 3207 | interrupts = <37>; |
| 3208 | interrupt-parent = <&PIC>; |
| 3209 | }; |
| 3210 | |
| 3211 | |
| 3212 | l) Marvell Discovery PIC (Programmable Interrupt Controller) nodes |
| 3213 | |
| 3214 | Represent the Discovery's PIC hardware |
| 3215 | |
| 3216 | Required properties: |
| 3217 | - #interrupt-cells : <1> |
| 3218 | - #address-cells : <0> |
| 3219 | - compatible : "marvell,mv64360-pic" |
| 3220 | - reg : Offset and length of the register set for this device |
| 3221 | - interrupt-controller |
| 3222 | |
| 3223 | Example Discovery PIC node: |
| 3224 | pic { |
| 3225 | #interrupt-cells = <1>; |
| 3226 | #address-cells = <0>; |
| 3227 | compatible = "marvell,mv64360-pic"; |
| 3228 | reg = <0x0 0x88>; |
| 3229 | interrupt-controller; |
| 3230 | }; |
| 3231 | |
| 3232 | |
| 3233 | m) Marvell Discovery MPP (Multipurpose Pins) multiplexing nodes |
| 3234 | |
| 3235 | Represent the Discovery's MPP hardware |
| 3236 | |
| 3237 | Required properties: |
| 3238 | - compatible : "marvell,mv64360-mpp" |
| 3239 | - reg : Offset and length of the register set for this device |
| 3240 | |
| 3241 | Example Discovery MPP node: |
| 3242 | mpp@f000 { |
| 3243 | compatible = "marvell,mv64360-mpp"; |
| 3244 | reg = <0xf000 0x10>; |
| 3245 | }; |
| 3246 | |
| 3247 | |
| 3248 | n) Marvell Discovery GPP (General Purpose Pins) nodes |
| 3249 | |
| 3250 | Represent the Discovery's GPP hardware |
| 3251 | |
| 3252 | Required properties: |
| 3253 | - compatible : "marvell,mv64360-gpp" |
| 3254 | - reg : Offset and length of the register set for this device |
| 3255 | |
| 3256 | Example Discovery GPP node: |
| 3257 | gpp@f000 { |
| 3258 | compatible = "marvell,mv64360-gpp"; |
| 3259 | reg = <0xf100 0x20>; |
| 3260 | }; |
| 3261 | |
| 3262 | |
| 3263 | o) Marvell Discovery PCI host bridge node |
| 3264 | |
| 3265 | Represents the Discovery's PCI host bridge device. The properties |
| 3266 | for this node conform to Rev 2.1 of the PCI Bus Binding to IEEE |
| 3267 | 1275-1994. A typical value for the compatible property is |
| 3268 | "marvell,mv64360-pci". |
| 3269 | |
| 3270 | Example Discovery PCI host bridge node |
| 3271 | pci@80000000 { |
| 3272 | #address-cells = <3>; |
| 3273 | #size-cells = <2>; |
| 3274 | #interrupt-cells = <1>; |
| 3275 | device_type = "pci"; |
| 3276 | compatible = "marvell,mv64360-pci"; |
| 3277 | reg = <0xcf8 0x8>; |
| 3278 | ranges = <0x01000000 0x0 0x0 |
| 3279 | 0x88000000 0x0 0x01000000 |
| 3280 | 0x02000000 0x0 0x80000000 |
| 3281 | 0x80000000 0x0 0x08000000>; |
| 3282 | bus-range = <0 255>; |
| 3283 | clock-frequency = <66000000>; |
| 3284 | interrupt-parent = <&PIC>; |
| 3285 | interrupt-map-mask = <0xf800 0x0 0x0 0x7>; |
| 3286 | interrupt-map = < |
| 3287 | /* IDSEL 0x0a */ |
| 3288 | 0x5000 0 0 1 &PIC 80 |
| 3289 | 0x5000 0 0 2 &PIC 81 |
| 3290 | 0x5000 0 0 3 &PIC 91 |
| 3291 | 0x5000 0 0 4 &PIC 93 |
| 3292 | |
| 3293 | /* IDSEL 0x0b */ |
| 3294 | 0x5800 0 0 1 &PIC 91 |
| 3295 | 0x5800 0 0 2 &PIC 93 |
| 3296 | 0x5800 0 0 3 &PIC 80 |
| 3297 | 0x5800 0 0 4 &PIC 81 |
| 3298 | |
| 3299 | /* IDSEL 0x0c */ |
| 3300 | 0x6000 0 0 1 &PIC 91 |
| 3301 | 0x6000 0 0 2 &PIC 93 |
| 3302 | 0x6000 0 0 3 &PIC 80 |
| 3303 | 0x6000 0 0 4 &PIC 81 |
| 3304 | |
| 3305 | /* IDSEL 0x0d */ |
| 3306 | 0x6800 0 0 1 &PIC 93 |
| 3307 | 0x6800 0 0 2 &PIC 80 |
| 3308 | 0x6800 0 0 3 &PIC 81 |
| 3309 | 0x6800 0 0 4 &PIC 91 |
| 3310 | >; |
| 3311 | }; |
| 3312 | |
| 3313 | |
| 3314 | p) Marvell Discovery CPU Error nodes |
| 3315 | |
| 3316 | Represent the Discovery's CPU error handler device. |
| 3317 | |
| 3318 | Required properties: |
| 3319 | - compatible : "marvell,mv64360-cpu-error" |
| 3320 | - reg : Offset and length of the register set for this device |
| 3321 | - interrupts : the interrupt number for this device |
| 3322 | - interrupt-parent : the phandle for the interrupt controller |
| 3323 | that services interrupts for this device. |
| 3324 | |
| 3325 | Example Discovery CPU Error node: |
| 3326 | cpu-error@0070 { |
| 3327 | compatible = "marvell,mv64360-cpu-error"; |
| 3328 | reg = <0x70 0x10 0x128 0x28>; |
| 3329 | interrupts = <3>; |
| 3330 | interrupt-parent = <&PIC>; |
| 3331 | }; |
| 3332 | |
| 3333 | |
| 3334 | q) Marvell Discovery SRAM Controller nodes |
| 3335 | |
| 3336 | Represent the Discovery's SRAM controller device. |
| 3337 | |
| 3338 | Required properties: |
| 3339 | - compatible : "marvell,mv64360-sram-ctrl" |
| 3340 | - reg : Offset and length of the register set for this device |
| 3341 | - interrupts : the interrupt number for this device |
| 3342 | - interrupt-parent : the phandle for the interrupt controller |
| 3343 | that services interrupts for this device. |
| 3344 | |
| 3345 | Example Discovery SRAM Controller node: |
| 3346 | sram-ctrl@0380 { |
| 3347 | compatible = "marvell,mv64360-sram-ctrl"; |
| 3348 | reg = <0x380 0x80>; |
| 3349 | interrupts = <13>; |
| 3350 | interrupt-parent = <&PIC>; |
| 3351 | }; |
| 3352 | |
| 3353 | |
| 3354 | r) Marvell Discovery PCI Error Handler nodes |
| 3355 | |
| 3356 | Represent the Discovery's PCI error handler device. |
| 3357 | |
| 3358 | Required properties: |
| 3359 | - compatible : "marvell,mv64360-pci-error" |
| 3360 | - reg : Offset and length of the register set for this device |
| 3361 | - interrupts : the interrupt number for this device |
| 3362 | - interrupt-parent : the phandle for the interrupt controller |
| 3363 | that services interrupts for this device. |
| 3364 | |
| 3365 | Example Discovery PCI Error Handler node: |
| 3366 | pci-error@1d40 { |
| 3367 | compatible = "marvell,mv64360-pci-error"; |
| 3368 | reg = <0x1d40 0x40 0xc28 0x4>; |
| 3369 | interrupts = <12>; |
| 3370 | interrupt-parent = <&PIC>; |
| 3371 | }; |
| 3372 | |
| 3373 | |
| 3374 | s) Marvell Discovery Memory Controller nodes |
| 3375 | |
| 3376 | Represent the Discovery's memory controller device. |
| 3377 | |
| 3378 | Required properties: |
| 3379 | - compatible : "marvell,mv64360-mem-ctrl" |
| 3380 | - reg : Offset and length of the register set for this device |
| 3381 | - interrupts : the interrupt number for this device |
| 3382 | - interrupt-parent : the phandle for the interrupt controller |
| 3383 | that services interrupts for this device. |
| 3384 | |
| 3385 | Example Discovery Memory Controller node: |
| 3386 | mem-ctrl@1400 { |
| 3387 | compatible = "marvell,mv64360-mem-ctrl"; |
| 3388 | reg = <0x1400 0x60>; |
| 3389 | interrupts = <17>; |
| 3390 | interrupt-parent = <&PIC>; |
| 3391 | }; |
| 3392 | |
| 3393 | |
| 3394 | VIII - Specifying interrupt information for devices |
Stuart Yoder | 2756590 | 2007-03-02 13:42:33 -0600 | [diff] [blame] | 3395 | =================================================== |
| 3396 | |
| 3397 | The device tree represents the busses and devices of a hardware |
| 3398 | system in a form similar to the physical bus topology of the |
| 3399 | hardware. |
| 3400 | |
| 3401 | In addition, a logical 'interrupt tree' exists which represents the |
| 3402 | hierarchy and routing of interrupts in the hardware. |
| 3403 | |
| 3404 | The interrupt tree model is fully described in the |
| 3405 | document "Open Firmware Recommended Practice: Interrupt |
| 3406 | Mapping Version 0.9". The document is available at: |
| 3407 | <http://playground.sun.com/1275/practice>. |
| 3408 | |
| 3409 | 1) interrupts property |
| 3410 | ---------------------- |
| 3411 | |
| 3412 | Devices that generate interrupts to a single interrupt controller |
| 3413 | should use the conventional OF representation described in the |
| 3414 | OF interrupt mapping documentation. |
| 3415 | |
| 3416 | Each device which generates interrupts must have an 'interrupt' |
| 3417 | property. The interrupt property value is an arbitrary number of |
| 3418 | of 'interrupt specifier' values which describe the interrupt or |
| 3419 | interrupts for the device. |
| 3420 | |
| 3421 | The encoding of an interrupt specifier is determined by the |
| 3422 | interrupt domain in which the device is located in the |
| 3423 | interrupt tree. The root of an interrupt domain specifies in |
| 3424 | its #interrupt-cells property the number of 32-bit cells |
| 3425 | required to encode an interrupt specifier. See the OF interrupt |
| 3426 | mapping documentation for a detailed description of domains. |
| 3427 | |
| 3428 | For example, the binding for the OpenPIC interrupt controller |
| 3429 | specifies an #interrupt-cells value of 2 to encode the interrupt |
| 3430 | number and level/sense information. All interrupt children in an |
| 3431 | OpenPIC interrupt domain use 2 cells per interrupt in their interrupts |
| 3432 | property. |
| 3433 | |
| 3434 | The PCI bus binding specifies a #interrupt-cell value of 1 to encode |
| 3435 | which interrupt pin (INTA,INTB,INTC,INTD) is used. |
| 3436 | |
| 3437 | 2) interrupt-parent property |
| 3438 | ---------------------------- |
| 3439 | |
| 3440 | The interrupt-parent property is specified to define an explicit |
| 3441 | link between a device node and its interrupt parent in |
| 3442 | the interrupt tree. The value of interrupt-parent is the |
| 3443 | phandle of the parent node. |
| 3444 | |
| 3445 | If the interrupt-parent property is not defined for a node, it's |
| 3446 | interrupt parent is assumed to be an ancestor in the node's |
| 3447 | _device tree_ hierarchy. |
| 3448 | |
| 3449 | 3) OpenPIC Interrupt Controllers |
| 3450 | -------------------------------- |
| 3451 | |
| 3452 | OpenPIC interrupt controllers require 2 cells to encode |
| 3453 | interrupt information. The first cell defines the interrupt |
| 3454 | number. The second cell defines the sense and level |
| 3455 | information. |
| 3456 | |
| 3457 | Sense and level information should be encoded as follows: |
| 3458 | |
| 3459 | 0 = low to high edge sensitive type enabled |
| 3460 | 1 = active low level sensitive type enabled |
| 3461 | 2 = active high level sensitive type enabled |
| 3462 | 3 = high to low edge sensitive type enabled |
| 3463 | |
| 3464 | 4) ISA Interrupt Controllers |
| 3465 | ---------------------------- |
| 3466 | |
| 3467 | ISA PIC interrupt controllers require 2 cells to encode |
| 3468 | interrupt information. The first cell defines the interrupt |
| 3469 | number. The second cell defines the sense and level |
| 3470 | information. |
| 3471 | |
| 3472 | ISA PIC interrupt controllers should adhere to the ISA PIC |
| 3473 | encodings listed below: |
| 3474 | |
| 3475 | 0 = active low level sensitive type enabled |
| 3476 | 1 = active high level sensitive type enabled |
| 3477 | 2 = high to low edge sensitive type enabled |
| 3478 | 3 = low to high edge sensitive type enabled |
| 3479 | |
Anton Vorontsov | b7ce341 | 2008-04-11 23:06:36 +1000 | [diff] [blame] | 3480 | VIII - Specifying GPIO information for devices |
| 3481 | ============================================== |
| 3482 | |
| 3483 | 1) gpios property |
| 3484 | ----------------- |
| 3485 | |
| 3486 | Nodes that makes use of GPIOs should define them using `gpios' property, |
| 3487 | format of which is: <&gpio-controller1-phandle gpio1-specifier |
| 3488 | &gpio-controller2-phandle gpio2-specifier |
| 3489 | 0 /* holes are permitted, means no GPIO 3 */ |
| 3490 | &gpio-controller4-phandle gpio4-specifier |
| 3491 | ...>; |
| 3492 | |
| 3493 | Note that gpio-specifier length is controller dependent. |
| 3494 | |
| 3495 | gpio-specifier may encode: bank, pin position inside the bank, |
| 3496 | whether pin is open-drain and whether pin is logically inverted. |
| 3497 | |
| 3498 | Example of the node using GPIOs: |
| 3499 | |
| 3500 | node { |
| 3501 | gpios = <&qe_pio_e 18 0>; |
| 3502 | }; |
| 3503 | |
| 3504 | In this example gpio-specifier is "18 0" and encodes GPIO pin number, |
| 3505 | and empty GPIO flags as accepted by the "qe_pio_e" gpio-controller. |
| 3506 | |
| 3507 | 2) gpio-controller nodes |
| 3508 | ------------------------ |
| 3509 | |
| 3510 | Every GPIO controller node must have #gpio-cells property defined, |
| 3511 | this information will be used to translate gpio-specifiers. |
| 3512 | |
| 3513 | Example of two SOC GPIO banks defined as gpio-controller nodes: |
| 3514 | |
| 3515 | qe_pio_a: gpio-controller@1400 { |
| 3516 | #gpio-cells = <2>; |
| 3517 | compatible = "fsl,qe-pario-bank-a", "fsl,qe-pario-bank"; |
| 3518 | reg = <0x1400 0x18>; |
| 3519 | gpio-controller; |
| 3520 | }; |
| 3521 | |
| 3522 | qe_pio_e: gpio-controller@1460 { |
| 3523 | #gpio-cells = <2>; |
| 3524 | compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank"; |
| 3525 | reg = <0x1460 0x18>; |
| 3526 | gpio-controller; |
| 3527 | }; |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 3528 | |
| 3529 | Appendix A - Sample SOC node for MPC8540 |
| 3530 | ======================================== |
| 3531 | |
| 3532 | Note that the #address-cells and #size-cells for the SoC node |
| 3533 | in this example have been explicitly listed; these are likely |
| 3534 | not necessary as they are usually the same as the root node. |
| 3535 | |
| 3536 | soc8540@e0000000 { |
| 3537 | #address-cells = <1>; |
| 3538 | #size-cells = <1>; |
| 3539 | #interrupt-cells = <2>; |
| 3540 | device_type = "soc"; |
| 3541 | ranges = <00000000 e0000000 00100000> |
| 3542 | reg = <e0000000 00003000>; |
Becky Bruce | 7d4b95a | 2006-02-06 14:26:31 -0600 | [diff] [blame] | 3543 | bus-frequency = <0>; |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 3544 | |
| 3545 | mdio@24520 { |
| 3546 | reg = <24520 20>; |
| 3547 | device_type = "mdio"; |
| 3548 | compatible = "gianfar"; |
| 3549 | |
| 3550 | ethernet-phy@0 { |
| 3551 | linux,phandle = <2452000> |
| 3552 | interrupt-parent = <40000>; |
| 3553 | interrupts = <35 1>; |
| 3554 | reg = <0>; |
| 3555 | device_type = "ethernet-phy"; |
| 3556 | }; |
| 3557 | |
| 3558 | ethernet-phy@1 { |
| 3559 | linux,phandle = <2452001> |
| 3560 | interrupt-parent = <40000>; |
| 3561 | interrupts = <35 1>; |
| 3562 | reg = <1>; |
| 3563 | device_type = "ethernet-phy"; |
| 3564 | }; |
| 3565 | |
| 3566 | ethernet-phy@3 { |
| 3567 | linux,phandle = <2452002> |
| 3568 | interrupt-parent = <40000>; |
| 3569 | interrupts = <35 1>; |
| 3570 | reg = <3>; |
| 3571 | device_type = "ethernet-phy"; |
| 3572 | }; |
| 3573 | |
| 3574 | }; |
| 3575 | |
| 3576 | ethernet@24000 { |
| 3577 | #size-cells = <0>; |
| 3578 | device_type = "network"; |
| 3579 | model = "TSEC"; |
| 3580 | compatible = "gianfar"; |
| 3581 | reg = <24000 1000>; |
Jon Loeliger | f583165 | 2006-08-17 08:42:35 -0500 | [diff] [blame] | 3582 | mac-address = [ 00 E0 0C 00 73 00 ]; |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 3583 | interrupts = <d 3 e 3 12 3>; |
| 3584 | interrupt-parent = <40000>; |
| 3585 | phy-handle = <2452000>; |
| 3586 | }; |
| 3587 | |
| 3588 | ethernet@25000 { |
| 3589 | #address-cells = <1>; |
| 3590 | #size-cells = <0>; |
| 3591 | device_type = "network"; |
| 3592 | model = "TSEC"; |
| 3593 | compatible = "gianfar"; |
| 3594 | reg = <25000 1000>; |
Jon Loeliger | f583165 | 2006-08-17 08:42:35 -0500 | [diff] [blame] | 3595 | mac-address = [ 00 E0 0C 00 73 01 ]; |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 3596 | interrupts = <13 3 14 3 18 3>; |
| 3597 | interrupt-parent = <40000>; |
| 3598 | phy-handle = <2452001>; |
| 3599 | }; |
| 3600 | |
| 3601 | ethernet@26000 { |
| 3602 | #address-cells = <1>; |
| 3603 | #size-cells = <0>; |
| 3604 | device_type = "network"; |
| 3605 | model = "FEC"; |
| 3606 | compatible = "gianfar"; |
| 3607 | reg = <26000 1000>; |
Jon Loeliger | f583165 | 2006-08-17 08:42:35 -0500 | [diff] [blame] | 3608 | mac-address = [ 00 E0 0C 00 73 02 ]; |
David Gibson | c125a18 | 2006-02-01 03:05:22 -0800 | [diff] [blame] | 3609 | interrupts = <19 3>; |
| 3610 | interrupt-parent = <40000>; |
| 3611 | phy-handle = <2452002>; |
| 3612 | }; |
| 3613 | |
| 3614 | serial@4500 { |
| 3615 | device_type = "serial"; |
| 3616 | compatible = "ns16550"; |
| 3617 | reg = <4500 100>; |
| 3618 | clock-frequency = <0>; |
| 3619 | interrupts = <1a 3>; |
| 3620 | interrupt-parent = <40000>; |
| 3621 | }; |
| 3622 | |
| 3623 | pic@40000 { |
| 3624 | linux,phandle = <40000>; |
| 3625 | clock-frequency = <0>; |
| 3626 | interrupt-controller; |
| 3627 | #address-cells = <0>; |
| 3628 | reg = <40000 40000>; |
| 3629 | built-in; |
| 3630 | compatible = "chrp,open-pic"; |
| 3631 | device_type = "open-pic"; |
| 3632 | big-endian; |
| 3633 | }; |
| 3634 | |
| 3635 | i2c@3000 { |
| 3636 | interrupt-parent = <40000>; |
| 3637 | interrupts = <1b 3>; |
| 3638 | reg = <3000 18>; |
| 3639 | device_type = "i2c"; |
| 3640 | compatible = "fsl-i2c"; |
| 3641 | dfsrr; |
| 3642 | }; |
| 3643 | |
| 3644 | }; |