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