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 | |
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 | |
5e1e9ba6 | 45 | b) Gianfar-compatible ethernet nodes |
a4ecabab | 46 | c) PHY nodes |
5e1e9ba6 SY |
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) | |
2099172d | 53 | j) CFI or JEDEC memory-mapped NOR flash |
3b824f85 | 54 | k) Global Utilities Block |
bc556ba9 TT |
55 | l) Freescale Communications Processor Module |
56 | m) Chipselect/Local Bus | |
57 | n) 4xx/Axon EMAC ethernet nodes | |
58 | o) Xilinx IP cores | |
c7d24a2d | 59 | p) Freescale Synchronous Serial Interface |
41abd68e | 60 | q) USB EHCI controllers |
5e1e9ba6 | 61 | |
f5412c49 DF |
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 | |
5e1e9ba6 SY |
86 | 1) interrupts property |
87 | 2) interrupt-parent property | |
88 | 3) OpenPIC Interrupt Controllers | |
89 | 4) ISA Interrupt Controllers | |
90 | ||
b7ce3415 AV |
91 | VIII - Specifying GPIO information for devices |
92 | 1) gpios property | |
93 | 2) gpio-controller nodes | |
94 | ||
5e1e9ba6 SY |
95 | Appendix A - Sample SOC node for MPC8540 |
96 | ||
97 | ||
98 | Revision Information | |
99 | ==================== | |
100 | ||
c125a183 DG |
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 | |
5d3f083d | 127 | required alignment between property size |
c125a183 DG |
128 | and property data. The old style variable |
129 | alignment would make it impossible to do | |
130 | "simple" insertion of properties using | |
5dd60166 | 131 | memmove (thanks Milton for |
c125a183 | 132 | noticing). Updated kernel patch as well |
5d3f083d | 133 | - Correct a few more alignment constraints |
c125a183 DG |
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 | ||
c125a183 DG |
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) | |
5dd60166 | 147 | - Add some definitions for PCI host bridges |
c125a183 DG |
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 | |
5dd60166 | 206 | bindings to powerpc. Only the 32-bit client interface |
c125a183 DG |
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 | ||
2fe0ae78 | 239 | r5 : NULL (as to differentiate with method a) |
c125a183 DG |
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 | |
5dd60166 | 286 | platforms feature the same core architecture. A single kernel build |
c125a183 DG |
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 | ||
5dd60166 | 307 | NOTE: If Ben doesn't merge the setup files, may need to change this to |
c125a183 DG |
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 | |
d6bc8ac9 | 339 | roughly described in include/asm-powerpc/prom.h by the structure |
c125a183 DG |
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 | |
5dd60166 | 348 | */ |
c125a183 DG |
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 */ | |
0e0293c8 DG |
357 | |
358 | /* version 17 fields below */ | |
359 | u32 size_dt_struct; /* size of the DT structure block */ | |
c125a183 DG |
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 | |
5dd60166 | 368 | */ |
c125a183 DG |
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 | |
5dd60166 | 405 | of the reserved memory map. This map is a list of pairs of 64- |
c125a183 | 406 | bit integers. Each pair is a physical address and a size. The |
c125a183 DG |
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 | |
5dd60166 | 419 | should be 64-bit aligned. |
c125a183 DG |
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 | |
0e0293c8 DG |
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. | |
c125a183 DG |
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 | |
0e0293c8 | 444 | version 1 to 3, or 16 if you generate a tree of version 16 or 17 |
c125a183 DG |
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 | ||
0e0293c8 DG |
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). | |
c125a183 DG |
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 | |
0e0293c8 | 525 | format definition (as it is in Open Firmware). Version 16 makes it |
c125a183 DG |
526 | optional as it can generate it from the unit name defined below. |
527 | ||
2fe0ae78 | 528 | There is also a "unit name" that is used to differentiate nodes with |
c125a183 | 529 | the same name at the same level, it is usually made of the node |
2fe0ae78 | 530 | names, the "@" sign, and a "unit address", which definition is |
c125a183 DG |
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 | ||
5dd60166 | 569 | This "linux, phandle" property is a 32-bit value that uniquely |
c125a183 DG |
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> | |
5dd60166 | 579 | represents a 32-bit hexadecimal value. The various nodes in this |
c125a183 DG |
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> | |
32aed2a5 | 605 | | |- 64-bit |
c125a183 DG |
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" | |
c125a183 DG |
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 | ||
32aed2a5 | 626 | The /cpus/PowerPC,970@0/64-bit property is an example of a |
c125a183 DG |
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) | |
5dd60166 DP |
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 | |
c125a183 DG |
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 | ||
5dd60166 | 659 | So the node content can be summarized as a start token, a full path, |
53cb4726 | 660 | a list of properties, a list of child nodes, and an end token. Every |
c125a183 DG |
661 | child node is a full node structure itself as defined above. |
662 | ||
eff2ebd2 DG |
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 | ||
53cb4726 | 671 | 4) Device tree "strings" block |
c125a183 DG |
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 | |
a2ffd275 | 690 | set the platform number. However, when using the flattened device-tree |
c125a183 DG |
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 | |
5dd60166 | 699 | documentations. If you choose to describe a bus with the device-tree |
c125a183 DG |
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 | |
5b14e5f9 MG |
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. | |
c125a183 DG |
710 | |
711 | Those 2 properties define 'cells' for representing an address and a | |
5dd60166 | 712 | size. A "cell" is a 32-bit number. For example, if both contain 2 |
c125a183 | 713 | like the example tree given above, then an address and a size are both |
5dd60166 | 714 | composed of 2 cells, and each is a 64-bit number (cells are |
c125a183 DG |
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 | ||
e1fd1865 SN |
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 | |
5dd60166 | 748 | (that is into parent bus addresses, and possibly into CPU physical |
c125a183 DG |
749 | addresses), all busses must contain a "ranges" property. If the |
750 | "ranges" property is missing at a given level, it's assumed that | |
e1fd1865 SN |
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: | |
c125a183 DG |
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 | ||
5dd60166 | 765 | For a new 64-bit powerpc board, I recommend either the 2/2 format or |
c125a183 | 766 | Apple's 2/1 format which is slightly more compact since sizes usually |
5dd60166 | 767 | fit in a single 32-bit word. New 32-bit powerpc boards should use a |
c125a183 DG |
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 | ||
e1fd1865 SN |
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. | |
c125a183 DG |
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 | ||
a2ffd275 | 810 | While open firmware provides more flexible usage of 8859-1, this |
c125a183 DG |
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 | |
e8222502 BH |
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. | |
c125a183 DG |
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 | |
143a42d1 | 853 | value but it is generally useful. |
c125a183 DG |
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 | |
6c28f2c0 | 857 | thing. It is recommended that if you add any "custom" property whose |
c125a183 DG |
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" | |
5dd60166 | 885 | - reg : This is the physical CPU number, it's a single 32-bit cell |
c125a183 DG |
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) | |
20474abd BH |
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 | |
c125a183 DG |
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 | |
c125a183 | 897 | |
20474abd BH |
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 | ||
c125a183 DG |
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 | |
5dd60166 | 912 | in Hz. A new property will be defined for 64-bit values, but if |
c125a183 DG |
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. | |
20474abd BH |
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 | |
c125a183 DG |
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, | |
6c28f2c0 | 946 | with both of these properties being 2 like in the example given |
c125a183 DG |
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 | |
d1bff9ed | 963 | the default input/output devices. |
c125a183 DG |
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 | ||
c125a183 DG |
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 | |
5d3f083d | 978 | it up as its own default console. If you look at the function |
c125a183 DG |
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. | |
c125a183 DG |
983 | |
984 | Note that u-boot creates and fills in the chosen node for platforms | |
985 | that use it. | |
986 | ||
d1bff9ed SY |
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 | ||
c125a183 DG |
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. | |
7d4b95ae BB |
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 | ||
c125a183 DG |
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 | |
5dd60166 | 1038 | for more information on how to specify devices that are part of a SOC. |
c125a183 DG |
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>; | |
7d4b95ae | 1049 | bus-frequency = <0>; |
c125a183 DG |
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 | |
6c28f2c0 | 1092 | assembly file exports some symbols that can be used. |
c125a183 DG |
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 | ||
5dd60166 | 1101 | The "output_version" defines what version of the "blob" format will be |
c125a183 DG |
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 | |
6c28f2c0 | 1106 | uniqueness of linux, phandle properties, validity of strings, etc... |
c125a183 DG |
1107 | |
1108 | The format of the .dts "source" file is "C" like, supports C and C++ | |
6c28f2c0 | 1109 | style comments. |
c125a183 DG |
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 | |
5dd60166 | 1123 | * numerical 32-bit value (hexadecimal) |
c125a183 DG |
1124 | */ |
1125 | ||
1126 | property3 = <12345678 12345678 deadbeef>; | |
1127 | /* define a property containing 3 | |
5dd60166 | 1128 | * numerical 32-bit values (cells) in |
c125a183 DG |
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 | ||
d6bc8ac9 | 1191 | - An example of code for iterating nodes & retrieving properties |
c125a183 DG |
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, | |
d6bc8ac9 | 1194 | its usage in early_init_devtree(), and the corresponding various |
c125a183 DG |
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 | |
5dd60166 | 1197 | to discuss possible free licensing to any vendor who wishes to |
c125a183 DG |
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 | |
5dd60166 | 1206 | processors, where the processor core (CPU) and many peripheral devices |
c125a183 DG |
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 | ||
27565903 | 1238 | 2) Representing devices without a current OF specification |
c125a183 DG |
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 | |
c125a183 | 1258 | - compatible : Should define the compatible device type for the |
e77b28eb | 1259 | mdio. Currently, this is most likely to be "fsl,gianfar-mdio" |
c125a183 DG |
1260 | |
1261 | Example: | |
1262 | ||
1263 | mdio@24520 { | |
1264 | reg = <24520 20>; | |
e77b28eb | 1265 | compatible = "fsl,gianfar-mdio"; |
c125a183 DG |
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 | |
f583165f | 1281 | - mac-address : List of bytes representing the ethernet address of |
c125a183 DG |
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. | |
a21e282a VB |
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. | |
c125a183 | 1296 | |
e0a2f28b SW |
1297 | Recommended properties: |
1298 | ||
cc65185d AF |
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 | ||
e0a2f28b | 1305 | |
c125a183 DG |
1306 | Example: |
1307 | ||
1308 | ethernet@24000 { | |
1309 | #size-cells = <0>; | |
1310 | device_type = "network"; | |
1311 | model = "TSEC"; | |
1312 | compatible = "gianfar"; | |
1313 | reg = <24000 1000>; | |
f583165f | 1314 | mac-address = [ 00 E0 0C 00 73 00 ]; |
c125a183 DG |
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 | ||
ad71f123 BB |
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 : | |
5dd60166 DP |
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 | |
ad71f123 BB |
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. | |
ea5b7a61 LY |
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. | |
ad71f123 BB |
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 | ||
5dd60166 | 1444 | Example multi port host USB controller device node : |
ad71f123 | 1445 | usb@22000 { |
ad71f123 BB |
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 | ||
5dd60166 | 1457 | Example dual role USB controller device node : |
ad71f123 | 1458 | usb@23000 { |
ad71f123 BB |
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>; | |
ea5b7a61 | 1465 | dr_mode = "otg"; |
ad71f123 BB |
1466 | phy = "ulpi"; |
1467 | }; | |
1468 | ||
1469 | ||
b88a0b1d KP |
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 | |
5dd60166 | 1490 | (EUs) are available. It's a single 32-bit cell. EU information |
b88a0b1d KP |
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 | |
5dd60166 | 1506 | are available. It's a single 32-bit cell. Descriptor type |
b88a0b1d KP |
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>; | |
cbdb54d3 | 1536 | channel-fifo-len = <18>; |
b88a0b1d | 1537 | exec-units-mask = <000000fe>; |
cbdb54d3 | 1538 | descriptor-types-mask = <012b0ebf>; |
b88a0b1d KP |
1539 | }; |
1540 | ||
9a1ab883 LY |
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. | |
e631ae3b SW |
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 | ||
9a1ab883 LY |
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. | |
59c51591 | 1564 | The description below applies to the qe of MPC8360 and |
9a1ab883 LY |
1565 | more nodes and properties would be extended in the future. |
1566 | ||
1567 | i) Root QE device | |
1568 | ||
1569 | Required properties: | |
a2dd70a1 | 1570 | - compatible : should be "fsl,qe"; |
9a1ab883 LY |
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>; | |
a2dd70a1 | 1584 | compatible = "fsl,qe"; |
9a1ab883 LY |
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: | |
f3a2b29d AV |
1595 | - cell-index : SPI controller index. |
1596 | - compatible : should be "fsl,spi". | |
f023dc76 | 1597 | - mode : the SPI operation mode, it can be "cpu" or "cpu-qe". |
9a1ab883 LY |
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 { | |
f3a2b29d AV |
1609 | cell-index = <0>; |
1610 | compatible = "fsl,spi"; | |
9a1ab883 LY |
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: | |
9a1ab883 LY |
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 { | |
9a1ab883 LY |
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" | |
845cf505 | 1646 | "bisync", "atm", or "serial". |
9a1ab883 | 1647 | - compatible : could be "ucc_geth" or "fsl_atm" and so on. |
56626f33 | 1648 | - cell-index : the ucc number(1-8), corresponding to UCCx in UM. |
9a1ab883 LY |
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. | |
845cf505 TT |
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. | |
174b0da2 TT |
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. | |
9a1ab883 LY |
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 | ||
e0a2f28b | 1691 | Recommended properties: |
60c1922c | 1692 | - phy-connection-type : a string naming the controller/PHY interface type, |
34be4561 KP |
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". | |
e0a2f28b | 1696 | |
9a1ab883 LY |
1697 | Example: |
1698 | ucc@2000 { | |
1699 | device_type = "network"; | |
1700 | compatible = "ucc_geth"; | |
56626f33 | 1701 | cell-index = <1>; |
9a1ab883 LY |
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>; | |
60c1922c | 1709 | phy-connection-type = "gmii"; |
9a1ab883 LY |
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. | |
a982ac06 | 1765 | - has_irq : indicates if the pin is used as source of external |
9a1ab883 LY |
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: | |
a2dd70a1 | 1801 | - compatible : should be "fsl,qe-muram", "fsl,cpm-muram". |
9a1ab883 LY |
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 { | |
a2dd70a1 | 1811 | compatible = "fsl,qe-muram", "fsl,cpm-muram"; |
9a1ab883 LY |
1812 | ranges = <0 00010000 0000c000>; |
1813 | ||
1814 | data-only@0{ | |
a2dd70a1 AV |
1815 | compatible = "fsl,qe-muram-data", |
1816 | "fsl,cpm-muram-data"; | |
9a1ab883 LY |
1817 | reg = <0 c000>; |
1818 | }; | |
1819 | }; | |
b88a0b1d | 1820 | |
bc556ba9 TT |
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 | ||
2099172d | 1847 | j) CFI or JEDEC memory-mapped NOR flash |
28f9ec34 VW |
1848 | |
1849 | Flash chips (Memory Technology Devices) are often used for solid state | |
1850 | file systems on embedded devices. | |
1851 | ||
2099172d DG |
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. | |
1862 | ||
1863 | For JEDEC compatible devices, the following additional properties | |
1864 | are defined: | |
1865 | ||
1866 | - vendor-id : Contains the flash chip's vendor id (1 byte). | |
1867 | - device-id : Contains the flash chip's device id (1 byte). | |
1868 | ||
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. | |
1875 | ||
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. | |
1879 | ||
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. | |
28f9ec34 | 1890 | |
2099172d | 1891 | Example: |
28f9ec34 | 1892 | |
2099172d DG |
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 | }; | |
28f9ec34 | 1910 | |
3b824f85 RZ |
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 | ||
e631ae3b SW |
1938 | l) Freescale Communications Processor Module |
1939 | ||
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". | |
15f8c604 | 1948 | - reg : A 48-byte region beginning with CPCR. |
e631ae3b SW |
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"; | |
15f8c604 | 1956 | reg = <119c0 30>; |
e631ae3b SW |
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>; | |
e631ae3b SW |
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 | ||
15f8c604 SW |
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 | ||
96fca1de SW |
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 { | |
253772b1 | 2149 | compatible = "fsl,mpc8272-localbus", |
96fca1de SW |
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 | ||
1d3bb996 | 2171 | |
e8690861 | 2172 | n) 4xx/Axon EMAC ethernet nodes |
1d3bb996 DG |
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 | ||
1d3bb996 DG |
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 { | |
1d3bb996 DG |
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 | ||
bc556ba9 | 2320 | o) Xilinx IP cores |
7ae0fa49 GL |
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 | ||
ab99eee8 | 2342 | (name): (generic-name)@(base-address) { |
7ae0fa49 GL |
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 | ||
ab99eee8 SN |
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'. | |
7ae0fa49 GL |
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 '-'. | |
ab99eee8 | 2363 | (baseaddr): the baseaddr parameter value (often named C_BASEADDR). |
7ae0fa49 | 2364 | (HW_VER): from the HW_VER parameter. |
ab99eee8 | 2365 | (size): the address range size (often C_HIGHADDR - C_BASEADDR + 1). |
7ae0fa49 GL |
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 | ||
ab99eee8 | 2395 | opb_uartlite_0: serial@ec100000 { |
7ae0fa49 GL |
2396 | device_type = "serial"; |
2397 | compatible = "xlnx,opb-uartlite-1.00.b"; | |
2398 | reg = <ec100000 10000>; | |
ab99eee8 | 2399 | interrupt-parent = <&opb_intc_0>; |
7ae0fa49 GL |
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 | ||
ab99eee8 SN |
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. | |
7ae0fa49 GL |
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 | ||
ab99eee8 SN |
2442 | opb_ps2_dual_ref_0: opb-ps2-dual-ref@a9000000 { |
2443 | #address-cells = <1>; | |
2444 | #size-cells = <1>; | |
2445 | compatible = "xlnx,compound"; | |
7ae0fa49 GL |
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>; | |
ab99eee8 | 2452 | interrupt-parent = <&opb_intc_0>; |
7ae0fa49 GL |
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>; | |
ab99eee8 | 2459 | interrupt-parent = <&opb_intc_0>; |
7ae0fa49 GL |
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 | ||
ab99eee8 | 2522 | plb@0 { |
7ae0fa49 GL |
2523 | #address-cells = <1>; |
2524 | #size-cells = <1>; | |
ab99eee8 | 2525 | compatible = "xlnx,plb-v34-1.02.a"; |
7ae0fa49 GL |
2526 | device_type = "ibm,plb"; |
2527 | ranges; // 1:1 translation | |
2528 | ||
ab99eee8 | 2529 | plb_bram_if_cntrl_0: bram@ffff0000 { |
7ae0fa49 GL |
2530 | reg = <ffff0000 10000>; |
2531 | } | |
2532 | ||
ab99eee8 | 2533 | opb@20000000 { |
7ae0fa49 GL |
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 | ||
ab99eee8 | 2541 | opb_uart16550_0: serial@a0000000 { |
7ae0fa49 GL |
2542 | reg = <a00000000 2000>; |
2543 | }; | |
2544 | ||
ab99eee8 | 2545 | opb_intc_0: interrupt-controller@d1000fc0 { |
7ae0fa49 GL |
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 | ||
ef66a9d2 SN |
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 | ||
c7d24a2d TT |
2604 | p) Freescale Synchronous Serial Interface |
2605 | ||
2606 | The SSI is a serial device that communicates with audio codecs. It can | |
2607 | be programmed in AC97, I2S, left-justified, or right-justified modes. | |
2608 | ||
2609 | Required properties: | |
2610 | - compatible : compatible list, containing "fsl,ssi" | |
2611 | - cell-index : the SSI, <0> = SSI1, <1> = SSI2, and so on | |
2612 | - reg : offset and length of the register set for the device | |
2613 | - interrupts : <a b> where a is the interrupt number and b is a | |
2614 | field that represents an encoding of the sense and | |
2615 | level information for the interrupt. This should be | |
2616 | encoded based on the information in section 2) | |
2617 | depending on the type of interrupt controller you | |
2618 | have. | |
2619 | - interrupt-parent : the phandle for the interrupt controller that | |
2620 | services interrupts for this device. | |
2621 | - fsl,mode : the operating mode for the SSI interface | |
2622 | "i2s-slave" - I2S mode, SSI is clock slave | |
2623 | "i2s-master" - I2S mode, SSI is clock master | |
2624 | "lj-slave" - left-justified mode, SSI is clock slave | |
2625 | "lj-master" - l.j. mode, SSI is clock master | |
2626 | "rj-slave" - right-justified mode, SSI is clock slave | |
2627 | "rj-master" - r.j., SSI is clock master | |
2628 | "ac97-slave" - AC97 mode, SSI is clock slave | |
2629 | "ac97-master" - AC97 mode, SSI is clock master | |
2630 | ||
2631 | Optional properties: | |
2632 | - codec-handle : phandle to a 'codec' node that defines an audio | |
2633 | codec connected to this SSI. This node is typically | |
2634 | a child of an I2C or other control node. | |
2635 | ||
2636 | Child 'codec' node required properties: | |
2637 | - compatible : compatible list, contains the name of the codec | |
2638 | ||
2639 | Child 'codec' node optional properties: | |
2640 | - clock-frequency : The frequency of the input clock, which typically | |
2641 | comes from an on-board dedicated oscillator. | |
2642 | ||
457aa81a ZW |
2643 | * Freescale 83xx DMA Controller |
2644 | ||
2645 | Freescale PowerPC 83xx have on chip general purpose DMA controllers. | |
2646 | ||
2647 | Required properties: | |
2648 | ||
2649 | - compatible : compatible list, contains 2 entries, first is | |
2650 | "fsl,CHIP-dma", where CHIP is the processor | |
2651 | (mpc8349, mpc8360, etc.) and the second is | |
2652 | "fsl,elo-dma" | |
2653 | - reg : <registers mapping for DMA general status reg> | |
2654 | - ranges : Should be defined as specified in 1) to describe the | |
2655 | DMA controller channels. | |
2656 | - cell-index : controller index. 0 for controller @ 0x8100 | |
2657 | - interrupts : <interrupt mapping for DMA IRQ> | |
2658 | - interrupt-parent : optional, if needed for interrupt mapping | |
2659 | ||
2660 | ||
2661 | - DMA channel nodes: | |
2662 | - compatible : compatible list, contains 2 entries, first is | |
2663 | "fsl,CHIP-dma-channel", where CHIP is the processor | |
2664 | (mpc8349, mpc8350, etc.) and the second is | |
2665 | "fsl,elo-dma-channel" | |
2666 | - reg : <registers mapping for channel> | |
2667 | - cell-index : dma channel index starts at 0. | |
2668 | ||
2669 | Optional properties: | |
2670 | - interrupts : <interrupt mapping for DMA channel IRQ> | |
2671 | (on 83xx this is expected to be identical to | |
2672 | the interrupts property of the parent node) | |
2673 | - interrupt-parent : optional, if needed for interrupt mapping | |
2674 | ||
2675 | Example: | |
2676 | dma@82a8 { | |
2677 | #address-cells = <1>; | |
2678 | #size-cells = <1>; | |
2679 | compatible = "fsl,mpc8349-dma", "fsl,elo-dma"; | |
2680 | reg = <82a8 4>; | |
2681 | ranges = <0 8100 1a4>; | |
2682 | interrupt-parent = <&ipic>; | |
2683 | interrupts = <47 8>; | |
2684 | cell-index = <0>; | |
2685 | dma-channel@0 { | |
2686 | compatible = "fsl,mpc8349-dma-channel", "fsl,elo-dma-channel"; | |
2687 | cell-index = <0>; | |
2688 | reg = <0 80>; | |
2689 | }; | |
2690 | dma-channel@80 { | |
2691 | compatible = "fsl,mpc8349-dma-channel", "fsl,elo-dma-channel"; | |
2692 | cell-index = <1>; | |
2693 | reg = <80 80>; | |
2694 | }; | |
2695 | dma-channel@100 { | |
2696 | compatible = "fsl,mpc8349-dma-channel", "fsl,elo-dma-channel"; | |
2697 | cell-index = <2>; | |
2698 | reg = <100 80>; | |
2699 | }; | |
2700 | dma-channel@180 { | |
2701 | compatible = "fsl,mpc8349-dma-channel", "fsl,elo-dma-channel"; | |
2702 | cell-index = <3>; | |
2703 | reg = <180 80>; | |
2704 | }; | |
2705 | }; | |
2706 | ||
2707 | * Freescale 85xx/86xx DMA Controller | |
2708 | ||
2709 | Freescale PowerPC 85xx/86xx have on chip general purpose DMA controllers. | |
2710 | ||
2711 | Required properties: | |
2712 | ||
2713 | - compatible : compatible list, contains 2 entries, first is | |
2714 | "fsl,CHIP-dma", where CHIP is the processor | |
2715 | (mpc8540, mpc8540, etc.) and the second is | |
2716 | "fsl,eloplus-dma" | |
2717 | - reg : <registers mapping for DMA general status reg> | |
2718 | - cell-index : controller index. 0 for controller @ 0x21000, | |
2719 | 1 for controller @ 0xc000 | |
2720 | - ranges : Should be defined as specified in 1) to describe the | |
2721 | DMA controller channels. | |
2722 | ||
2723 | - DMA channel nodes: | |
2724 | - compatible : compatible list, contains 2 entries, first is | |
2725 | "fsl,CHIP-dma-channel", where CHIP is the processor | |
2726 | (mpc8540, mpc8560, etc.) and the second is | |
2727 | "fsl,eloplus-dma-channel" | |
2728 | - cell-index : dma channel index starts at 0. | |
2729 | - reg : <registers mapping for channel> | |
2730 | - interrupts : <interrupt mapping for DMA channel IRQ> | |
2731 | - interrupt-parent : optional, if needed for interrupt mapping | |
2732 | ||
2733 | Example: | |
2734 | dma@21300 { | |
2735 | #address-cells = <1>; | |
2736 | #size-cells = <1>; | |
2737 | compatible = "fsl,mpc8540-dma", "fsl,eloplus-dma"; | |
2738 | reg = <21300 4>; | |
2739 | ranges = <0 21100 200>; | |
2740 | cell-index = <0>; | |
2741 | dma-channel@0 { | |
2742 | compatible = "fsl,mpc8540-dma-channel", "fsl,eloplus-dma-channel"; | |
2743 | reg = <0 80>; | |
2744 | cell-index = <0>; | |
2745 | interrupt-parent = <&mpic>; | |
2746 | interrupts = <14 2>; | |
2747 | }; | |
2748 | dma-channel@80 { | |
2749 | compatible = "fsl,mpc8540-dma-channel", "fsl,eloplus-dma-channel"; | |
2750 | reg = <80 80>; | |
2751 | cell-index = <1>; | |
2752 | interrupt-parent = <&mpic>; | |
2753 | interrupts = <15 2>; | |
2754 | }; | |
2755 | dma-channel@100 { | |
2756 | compatible = "fsl,mpc8540-dma-channel", "fsl,eloplus-dma-channel"; | |
2757 | reg = <100 80>; | |
2758 | cell-index = <2>; | |
2759 | interrupt-parent = <&mpic>; | |
2760 | interrupts = <16 2>; | |
2761 | }; | |
2762 | dma-channel@180 { | |
2763 | compatible = "fsl,mpc8540-dma-channel", "fsl,eloplus-dma-channel"; | |
2764 | reg = <180 80>; | |
2765 | cell-index = <3>; | |
2766 | interrupt-parent = <&mpic>; | |
2767 | interrupts = <17 2>; | |
2768 | }; | |
2769 | }; | |
2770 | ||
b61ad653 LY |
2771 | * Freescale 8xxx/3.0 Gb/s SATA nodes |
2772 | ||
2773 | SATA nodes are defined to describe on-chip Serial ATA controllers. | |
2774 | Each SATA port should have its own node. | |
2775 | ||
2776 | Required properties: | |
2777 | - compatible : compatible list, contains 2 entries, first is | |
2778 | "fsl,CHIP-sata", where CHIP is the processor | |
2779 | (mpc8315, mpc8379, etc.) and the second is | |
2780 | "fsl,pq-sata" | |
2781 | - interrupts : <interrupt mapping for SATA IRQ> | |
2782 | - cell-index : controller index. | |
2783 | 1 for controller @ 0x18000 | |
2784 | 2 for controller @ 0x19000 | |
2785 | 3 for controller @ 0x1a000 | |
2786 | 4 for controller @ 0x1b000 | |
2787 | ||
2788 | Optional properties: | |
2789 | - interrupt-parent : optional, if needed for interrupt mapping | |
2790 | - reg : <registers mapping> | |
2791 | ||
2792 | Example: | |
2793 | ||
2794 | sata@18000 { | |
2795 | compatible = "fsl,mpc8379-sata", "fsl,pq-sata"; | |
2796 | reg = <0x18000 0x1000>; | |
2797 | cell-index = <1>; | |
2798 | interrupts = <2c 8>; | |
2799 | interrupt-parent = < &ipic >; | |
2800 | }; | |
c7d24a2d | 2801 | |
41abd68e VB |
2802 | q) USB EHCI controllers |
2803 | ||
2804 | Required properties: | |
2805 | - compatible : should be "usb-ehci". | |
2806 | - reg : should contain at least address and length of the standard EHCI | |
2807 | register set for the device. Optional platform-dependent registers | |
2808 | (debug-port or other) can be also specified here, but only after | |
2809 | definition of standard EHCI registers. | |
2810 | - interrupts : one EHCI interrupt should be described here. | |
2811 | If device registers are implemented in big endian mode, the device | |
2812 | node should have "big-endian-regs" property. | |
2813 | If controller implementation operates with big endian descriptors, | |
2814 | "big-endian-desc" property should be specified. | |
2815 | If both big endian registers and descriptors are used by the controller | |
2816 | implementation, "big-endian" property can be specified instead of having | |
2817 | both "big-endian-regs" and "big-endian-desc". | |
2818 | ||
2819 | Example (Sequoia 440EPx): | |
2820 | ehci@e0000300 { | |
2821 | compatible = "ibm,usb-ehci-440epx", "usb-ehci"; | |
2822 | interrupt-parent = <&UIC0>; | |
2823 | interrupts = <1a 4>; | |
2824 | reg = <0 e0000300 90 0 e0000390 70>; | |
2825 | big-endian; | |
2826 | }; | |
2827 | ||
2828 | ||
f5412c49 DF |
2829 | VII - Marvell Discovery mv64[345]6x System Controller chips |
2830 | =========================================================== | |
c125a183 | 2831 | |
f5412c49 DF |
2832 | The Marvell mv64[345]60 series of system controller chips contain |
2833 | many of the peripherals needed to implement a complete computer | |
2834 | system. In this section, we define device tree nodes to describe | |
2835 | the system controller chip itself and each of the peripherals | |
2836 | which it contains. Compatible string values for each node are | |
2837 | prefixed with the string "marvell,", for Marvell Technology Group Ltd. | |
2838 | ||
2839 | 1) The /system-controller node | |
2840 | ||
2841 | This node is used to represent the system-controller and must be | |
2842 | present when the system uses a system contller chip. The top-level | |
2843 | system-controller node contains information that is global to all | |
2844 | devices within the system controller chip. The node name begins | |
2845 | with "system-controller" followed by the unit address, which is | |
2846 | the base address of the memory-mapped register set for the system | |
2847 | controller chip. | |
2848 | ||
2849 | Required properties: | |
2850 | ||
2851 | - ranges : Describes the translation of system controller addresses | |
2852 | for memory mapped registers. | |
2853 | - clock-frequency: Contains the main clock frequency for the system | |
2854 | controller chip. | |
2855 | - reg : This property defines the address and size of the | |
2856 | memory-mapped registers contained within the system controller | |
2857 | chip. The address specified in the "reg" property should match | |
2858 | the unit address of the system-controller node. | |
2859 | - #address-cells : Address representation for system controller | |
2860 | devices. This field represents the number of cells needed to | |
2861 | represent the address of the memory-mapped registers of devices | |
2862 | within the system controller chip. | |
2863 | - #size-cells : Size representation for for the memory-mapped | |
2864 | registers within the system controller chip. | |
2865 | - #interrupt-cells : Defines the width of cells used to represent | |
2866 | interrupts. | |
2867 | ||
2868 | Optional properties: | |
2869 | ||
2870 | - model : The specific model of the system controller chip. Such | |
2871 | as, "mv64360", "mv64460", or "mv64560". | |
2872 | - compatible : A string identifying the compatibility identifiers | |
2873 | of the system controller chip. | |
2874 | ||
2875 | The system-controller node contains child nodes for each system | |
2876 | controller device that the platform uses. Nodes should not be created | |
2877 | for devices which exist on the system controller chip but are not used | |
2878 | ||
2879 | Example Marvell Discovery mv64360 system-controller node: | |
2880 | ||
2881 | system-controller@f1000000 { /* Marvell Discovery mv64360 */ | |
2882 | #address-cells = <1>; | |
2883 | #size-cells = <1>; | |
2884 | model = "mv64360"; /* Default */ | |
2885 | compatible = "marvell,mv64360"; | |
2886 | clock-frequency = <133333333>; | |
2887 | reg = <0xf1000000 0x10000>; | |
2888 | virtual-reg = <0xf1000000>; | |
2889 | ranges = <0x88000000 0x88000000 0x1000000 /* PCI 0 I/O Space */ | |
2890 | 0x80000000 0x80000000 0x8000000 /* PCI 0 MEM Space */ | |
2891 | 0xa0000000 0xa0000000 0x4000000 /* User FLASH */ | |
2892 | 0x00000000 0xf1000000 0x0010000 /* Bridge's regs */ | |
2893 | 0xf2000000 0xf2000000 0x0040000>;/* Integrated SRAM */ | |
2894 | ||
2895 | [ child node definitions... ] | |
2896 | } | |
2897 | ||
2898 | 2) Child nodes of /system-controller | |
2899 | ||
2900 | a) Marvell Discovery MDIO bus | |
2901 | ||
2902 | The MDIO is a bus to which the PHY devices are connected. For each | |
2903 | device that exists on this bus, a child node should be created. See | |
2904 | the definition of the PHY node below for an example of how to define | |
2905 | a PHY. | |
2906 | ||
2907 | Required properties: | |
2908 | - #address-cells : Should be <1> | |
2909 | - #size-cells : Should be <0> | |
2910 | - device_type : Should be "mdio" | |
2911 | - compatible : Should be "marvell,mv64360-mdio" | |
2912 | ||
2913 | Example: | |
2914 | ||
2915 | mdio { | |
2916 | #address-cells = <1>; | |
2917 | #size-cells = <0>; | |
2918 | device_type = "mdio"; | |
2919 | compatible = "marvell,mv64360-mdio"; | |
2920 | ||
2921 | ethernet-phy@0 { | |
2922 | ...... | |
2923 | }; | |
2924 | }; | |
2925 | ||
2926 | ||
2927 | b) Marvell Discovery ethernet controller | |
2928 | ||
2929 | The Discover ethernet controller is described with two levels | |
2930 | of nodes. The first level describes an ethernet silicon block | |
2931 | and the second level describes up to 3 ethernet nodes within | |
2932 | that block. The reason for the multiple levels is that the | |
2933 | registers for the node are interleaved within a single set | |
2934 | of registers. The "ethernet-block" level describes the | |
2935 | shared register set, and the "ethernet" nodes describe ethernet | |
2936 | port-specific properties. | |
2937 | ||
2938 | Ethernet block node | |
2939 | ||
2940 | Required properties: | |
2941 | - #address-cells : <1> | |
2942 | - #size-cells : <0> | |
2943 | - compatible : "marvell,mv64360-eth-block" | |
2944 | - reg : Offset and length of the register set for this block | |
2945 | ||
2946 | Example Discovery Ethernet block node: | |
2947 | ethernet-block@2000 { | |
2948 | #address-cells = <1>; | |
2949 | #size-cells = <0>; | |
2950 | compatible = "marvell,mv64360-eth-block"; | |
2951 | reg = <0x2000 0x2000>; | |
2952 | ethernet@0 { | |
2953 | ....... | |
2954 | }; | |
2955 | }; | |
2956 | ||
2957 | Ethernet port node | |
2958 | ||
2959 | Required properties: | |
2960 | - device_type : Should be "network". | |
2961 | - compatible : Should be "marvell,mv64360-eth". | |
2962 | - reg : Should be <0>, <1>, or <2>, according to which registers | |
2963 | within the silicon block the device uses. | |
2964 | - interrupts : <a> where a is the interrupt number for the port. | |
2965 | - interrupt-parent : the phandle for the interrupt controller | |
2966 | that services interrupts for this device. | |
2967 | - phy : the phandle for the PHY connected to this ethernet | |
2968 | controller. | |
2969 | - local-mac-address : 6 bytes, MAC address | |
2970 | ||
2971 | Example Discovery Ethernet port node: | |
2972 | ethernet@0 { | |
2973 | device_type = "network"; | |
2974 | compatible = "marvell,mv64360-eth"; | |
2975 | reg = <0>; | |
2976 | interrupts = <32>; | |
2977 | interrupt-parent = <&PIC>; | |
2978 | phy = <&PHY0>; | |
2979 | local-mac-address = [ 00 00 00 00 00 00 ]; | |
2980 | }; | |
2981 | ||
2982 | ||
2983 | ||
2984 | c) Marvell Discovery PHY nodes | |
2985 | ||
2986 | Required properties: | |
2987 | - device_type : Should be "ethernet-phy" | |
2988 | - interrupts : <a> where a is the interrupt number for this phy. | |
2989 | - interrupt-parent : the phandle for the interrupt controller that | |
2990 | services interrupts for this device. | |
2991 | - reg : The ID number for the phy, usually a small integer | |
2992 | ||
2993 | Example Discovery PHY node: | |
2994 | ethernet-phy@1 { | |
2995 | device_type = "ethernet-phy"; | |
2996 | compatible = "broadcom,bcm5421"; | |
2997 | interrupts = <76>; /* GPP 12 */ | |
2998 | interrupt-parent = <&PIC>; | |
2999 | reg = <1>; | |
3000 | }; | |
3001 | ||
3002 | ||
3003 | d) Marvell Discovery SDMA nodes | |
3004 | ||
3005 | Represent DMA hardware associated with the MPSC (multiprotocol | |
3006 | serial controllers). | |
3007 | ||
3008 | Required properties: | |
3009 | - compatible : "marvell,mv64360-sdma" | |
3010 | - reg : Offset and length of the register set for this device | |
3011 | - interrupts : <a> where a is the interrupt number for the DMA | |
3012 | device. | |
3013 | - interrupt-parent : the phandle for the interrupt controller | |
3014 | that services interrupts for this device. | |
3015 | ||
3016 | Example Discovery SDMA node: | |
3017 | sdma@4000 { | |
3018 | compatible = "marvell,mv64360-sdma"; | |
3019 | reg = <0x4000 0xc18>; | |
3020 | virtual-reg = <0xf1004000>; | |
3021 | interrupts = <36>; | |
3022 | interrupt-parent = <&PIC>; | |
3023 | }; | |
3024 | ||
3025 | ||
3026 | e) Marvell Discovery BRG nodes | |
3027 | ||
3028 | Represent baud rate generator hardware associated with the MPSC | |
3029 | (multiprotocol serial controllers). | |
3030 | ||
3031 | Required properties: | |
3032 | - compatible : "marvell,mv64360-brg" | |
3033 | - reg : Offset and length of the register set for this device | |
3034 | - clock-src : A value from 0 to 15 which selects the clock | |
3035 | source for the baud rate generator. This value corresponds | |
3036 | to the CLKS value in the BRGx configuration register. See | |
3037 | the mv64x60 User's Manual. | |
3038 | - clock-frequence : The frequency (in Hz) of the baud rate | |
3039 | generator's input clock. | |
3040 | - current-speed : The current speed setting (presumably by | |
3041 | firmware) of the baud rate generator. | |
3042 | ||
3043 | Example Discovery BRG node: | |
3044 | brg@b200 { | |
3045 | compatible = "marvell,mv64360-brg"; | |
3046 | reg = <0xb200 0x8>; | |
3047 | clock-src = <8>; | |
3048 | clock-frequency = <133333333>; | |
3049 | current-speed = <9600>; | |
3050 | }; | |
3051 | ||
3052 | ||
3053 | f) Marvell Discovery CUNIT nodes | |
3054 | ||
3055 | Represent the Serial Communications Unit device hardware. | |
3056 | ||
3057 | Required properties: | |
3058 | - reg : Offset and length of the register set for this device | |
3059 | ||
3060 | Example Discovery CUNIT node: | |
3061 | cunit@f200 { | |
3062 | reg = <0xf200 0x200>; | |
3063 | }; | |
3064 | ||
3065 | ||
3066 | g) Marvell Discovery MPSCROUTING nodes | |
3067 | ||
3068 | Represent the Discovery's MPSC routing hardware | |
3069 | ||
3070 | Required properties: | |
3071 | - reg : Offset and length of the register set for this device | |
3072 | ||
3073 | Example Discovery CUNIT node: | |
3074 | mpscrouting@b500 { | |
3075 | reg = <0xb400 0xc>; | |
3076 | }; | |
3077 | ||
3078 | ||
3079 | h) Marvell Discovery MPSCINTR nodes | |
3080 | ||
3081 | Represent the Discovery's MPSC DMA interrupt hardware registers | |
3082 | (SDMA cause and mask registers). | |
3083 | ||
3084 | Required properties: | |
3085 | - reg : Offset and length of the register set for this device | |
3086 | ||
3087 | Example Discovery MPSCINTR node: | |
3088 | mpsintr@b800 { | |
3089 | reg = <0xb800 0x100>; | |
3090 | }; | |
3091 | ||
3092 | ||
3093 | i) Marvell Discovery MPSC nodes | |
3094 | ||
3095 | Represent the Discovery's MPSC (Multiprotocol Serial Controller) | |
3096 | serial port. | |
3097 | ||
3098 | Required properties: | |
3099 | - device_type : "serial" | |
3100 | - compatible : "marvell,mv64360-mpsc" | |
3101 | - reg : Offset and length of the register set for this device | |
3102 | - sdma : the phandle for the SDMA node used by this port | |
3103 | - brg : the phandle for the BRG node used by this port | |
3104 | - cunit : the phandle for the CUNIT node used by this port | |
3105 | - mpscrouting : the phandle for the MPSCROUTING node used by this port | |
3106 | - mpscintr : the phandle for the MPSCINTR node used by this port | |
3107 | - cell-index : the hardware index of this cell in the MPSC core | |
3108 | - max_idle : value needed for MPSC CHR3 (Maximum Frame Length) | |
3109 | register | |
3110 | - interrupts : <a> where a is the interrupt number for the MPSC. | |
3111 | - interrupt-parent : the phandle for the interrupt controller | |
3112 | that services interrupts for this device. | |
3113 | ||
3114 | Example Discovery MPSCINTR node: | |
3115 | mpsc@8000 { | |
3116 | device_type = "serial"; | |
3117 | compatible = "marvell,mv64360-mpsc"; | |
3118 | reg = <0x8000 0x38>; | |
3119 | virtual-reg = <0xf1008000>; | |
3120 | sdma = <&SDMA0>; | |
3121 | brg = <&BRG0>; | |
3122 | cunit = <&CUNIT>; | |
3123 | mpscrouting = <&MPSCROUTING>; | |
3124 | mpscintr = <&MPSCINTR>; | |
3125 | cell-index = <0>; | |
3126 | max_idle = <40>; | |
3127 | interrupts = <40>; | |
3128 | interrupt-parent = <&PIC>; | |
3129 | }; | |
3130 | ||
3131 | ||
3132 | j) Marvell Discovery Watch Dog Timer nodes | |
3133 | ||
3134 | Represent the Discovery's watchdog timer hardware | |
3135 | ||
3136 | Required properties: | |
3137 | - compatible : "marvell,mv64360-wdt" | |
3138 | - reg : Offset and length of the register set for this device | |
3139 | ||
3140 | Example Discovery Watch Dog Timer node: | |
3141 | wdt@b410 { | |
3142 | compatible = "marvell,mv64360-wdt"; | |
3143 | reg = <0xb410 0x8>; | |
3144 | }; | |
3145 | ||
3146 | ||
3147 | k) Marvell Discovery I2C nodes | |
3148 | ||
3149 | Represent the Discovery's I2C hardware | |
3150 | ||
3151 | Required properties: | |
3152 | - device_type : "i2c" | |
3153 | - compatible : "marvell,mv64360-i2c" | |
3154 | - reg : Offset and length of the register set for this device | |
3155 | - interrupts : <a> where a is the interrupt number for the I2C. | |
3156 | - interrupt-parent : the phandle for the interrupt controller | |
3157 | that services interrupts for this device. | |
3158 | ||
3159 | Example Discovery I2C node: | |
3160 | compatible = "marvell,mv64360-i2c"; | |
3161 | reg = <0xc000 0x20>; | |
3162 | virtual-reg = <0xf100c000>; | |
3163 | interrupts = <37>; | |
3164 | interrupt-parent = <&PIC>; | |
3165 | }; | |
3166 | ||
3167 | ||
3168 | l) Marvell Discovery PIC (Programmable Interrupt Controller) nodes | |
3169 | ||
3170 | Represent the Discovery's PIC hardware | |
3171 | ||
3172 | Required properties: | |
3173 | - #interrupt-cells : <1> | |
3174 | - #address-cells : <0> | |
3175 | - compatible : "marvell,mv64360-pic" | |
3176 | - reg : Offset and length of the register set for this device | |
3177 | - interrupt-controller | |
3178 | ||
3179 | Example Discovery PIC node: | |
3180 | pic { | |
3181 | #interrupt-cells = <1>; | |
3182 | #address-cells = <0>; | |
3183 | compatible = "marvell,mv64360-pic"; | |
3184 | reg = <0x0 0x88>; | |
3185 | interrupt-controller; | |
3186 | }; | |
3187 | ||
3188 | ||
3189 | m) Marvell Discovery MPP (Multipurpose Pins) multiplexing nodes | |
3190 | ||
3191 | Represent the Discovery's MPP hardware | |
3192 | ||
3193 | Required properties: | |
3194 | - compatible : "marvell,mv64360-mpp" | |
3195 | - reg : Offset and length of the register set for this device | |
3196 | ||
3197 | Example Discovery MPP node: | |
3198 | mpp@f000 { | |
3199 | compatible = "marvell,mv64360-mpp"; | |
3200 | reg = <0xf000 0x10>; | |
3201 | }; | |
3202 | ||
3203 | ||
3204 | n) Marvell Discovery GPP (General Purpose Pins) nodes | |
3205 | ||
3206 | Represent the Discovery's GPP hardware | |
3207 | ||
3208 | Required properties: | |
3209 | - compatible : "marvell,mv64360-gpp" | |
3210 | - reg : Offset and length of the register set for this device | |
3211 | ||
3212 | Example Discovery GPP node: | |
3213 | gpp@f000 { | |
3214 | compatible = "marvell,mv64360-gpp"; | |
3215 | reg = <0xf100 0x20>; | |
3216 | }; | |
3217 | ||
3218 | ||
3219 | o) Marvell Discovery PCI host bridge node | |
3220 | ||
3221 | Represents the Discovery's PCI host bridge device. The properties | |
3222 | for this node conform to Rev 2.1 of the PCI Bus Binding to IEEE | |
3223 | 1275-1994. A typical value for the compatible property is | |
3224 | "marvell,mv64360-pci". | |
3225 | ||
3226 | Example Discovery PCI host bridge node | |
3227 | pci@80000000 { | |
3228 | #address-cells = <3>; | |
3229 | #size-cells = <2>; | |
3230 | #interrupt-cells = <1>; | |
3231 | device_type = "pci"; | |
3232 | compatible = "marvell,mv64360-pci"; | |
3233 | reg = <0xcf8 0x8>; | |
3234 | ranges = <0x01000000 0x0 0x0 | |
3235 | 0x88000000 0x0 0x01000000 | |
3236 | 0x02000000 0x0 0x80000000 | |
3237 | 0x80000000 0x0 0x08000000>; | |
3238 | bus-range = <0 255>; | |
3239 | clock-frequency = <66000000>; | |
3240 | interrupt-parent = <&PIC>; | |
3241 | interrupt-map-mask = <0xf800 0x0 0x0 0x7>; | |
3242 | interrupt-map = < | |
3243 | /* IDSEL 0x0a */ | |
3244 | 0x5000 0 0 1 &PIC 80 | |
3245 | 0x5000 0 0 2 &PIC 81 | |
3246 | 0x5000 0 0 3 &PIC 91 | |
3247 | 0x5000 0 0 4 &PIC 93 | |
3248 | ||
3249 | /* IDSEL 0x0b */ | |
3250 | 0x5800 0 0 1 &PIC 91 | |
3251 | 0x5800 0 0 2 &PIC 93 | |
3252 | 0x5800 0 0 3 &PIC 80 | |
3253 | 0x5800 0 0 4 &PIC 81 | |
3254 | ||
3255 | /* IDSEL 0x0c */ | |
3256 | 0x6000 0 0 1 &PIC 91 | |
3257 | 0x6000 0 0 2 &PIC 93 | |
3258 | 0x6000 0 0 3 &PIC 80 | |
3259 | 0x6000 0 0 4 &PIC 81 | |
3260 | ||
3261 | /* IDSEL 0x0d */ | |
3262 | 0x6800 0 0 1 &PIC 93 | |
3263 | 0x6800 0 0 2 &PIC 80 | |
3264 | 0x6800 0 0 3 &PIC 81 | |
3265 | 0x6800 0 0 4 &PIC 91 | |
3266 | >; | |
3267 | }; | |
3268 | ||
3269 | ||
3270 | p) Marvell Discovery CPU Error nodes | |
3271 | ||
3272 | Represent the Discovery's CPU error handler device. | |
3273 | ||
3274 | Required properties: | |
3275 | - compatible : "marvell,mv64360-cpu-error" | |
3276 | - reg : Offset and length of the register set for this device | |
3277 | - interrupts : the interrupt number for this device | |
3278 | - interrupt-parent : the phandle for the interrupt controller | |
3279 | that services interrupts for this device. | |
3280 | ||
3281 | Example Discovery CPU Error node: | |
3282 | cpu-error@0070 { | |
3283 | compatible = "marvell,mv64360-cpu-error"; | |
3284 | reg = <0x70 0x10 0x128 0x28>; | |
3285 | interrupts = <3>; | |
3286 | interrupt-parent = <&PIC>; | |
3287 | }; | |
3288 | ||
3289 | ||
3290 | q) Marvell Discovery SRAM Controller nodes | |
3291 | ||
3292 | Represent the Discovery's SRAM controller device. | |
3293 | ||
3294 | Required properties: | |
3295 | - compatible : "marvell,mv64360-sram-ctrl" | |
3296 | - reg : Offset and length of the register set for this device | |
3297 | - interrupts : the interrupt number for this device | |
3298 | - interrupt-parent : the phandle for the interrupt controller | |
3299 | that services interrupts for this device. | |
3300 | ||
3301 | Example Discovery SRAM Controller node: | |
3302 | sram-ctrl@0380 { | |
3303 | compatible = "marvell,mv64360-sram-ctrl"; | |
3304 | reg = <0x380 0x80>; | |
3305 | interrupts = <13>; | |
3306 | interrupt-parent = <&PIC>; | |
3307 | }; | |
3308 | ||
3309 | ||
3310 | r) Marvell Discovery PCI Error Handler nodes | |
3311 | ||
3312 | Represent the Discovery's PCI error handler device. | |
3313 | ||
3314 | Required properties: | |
3315 | - compatible : "marvell,mv64360-pci-error" | |
3316 | - reg : Offset and length of the register set for this device | |
3317 | - interrupts : the interrupt number for this device | |
3318 | - interrupt-parent : the phandle for the interrupt controller | |
3319 | that services interrupts for this device. | |
3320 | ||
3321 | Example Discovery PCI Error Handler node: | |
3322 | pci-error@1d40 { | |
3323 | compatible = "marvell,mv64360-pci-error"; | |
3324 | reg = <0x1d40 0x40 0xc28 0x4>; | |
3325 | interrupts = <12>; | |
3326 | interrupt-parent = <&PIC>; | |
3327 | }; | |
3328 | ||
3329 | ||
3330 | s) Marvell Discovery Memory Controller nodes | |
3331 | ||
3332 | Represent the Discovery's memory controller device. | |
3333 | ||
3334 | Required properties: | |
3335 | - compatible : "marvell,mv64360-mem-ctrl" | |
3336 | - reg : Offset and length of the register set for this device | |
3337 | - interrupts : the interrupt number for this device | |
3338 | - interrupt-parent : the phandle for the interrupt controller | |
3339 | that services interrupts for this device. | |
3340 | ||
3341 | Example Discovery Memory Controller node: | |
3342 | mem-ctrl@1400 { | |
3343 | compatible = "marvell,mv64360-mem-ctrl"; | |
3344 | reg = <0x1400 0x60>; | |
3345 | interrupts = <17>; | |
3346 | interrupt-parent = <&PIC>; | |
3347 | }; | |
3348 | ||
3349 | ||
3350 | VIII - Specifying interrupt information for devices | |
27565903 SY |
3351 | =================================================== |
3352 | ||
3353 | The device tree represents the busses and devices of a hardware | |
3354 | system in a form similar to the physical bus topology of the | |
3355 | hardware. | |
3356 | ||
3357 | In addition, a logical 'interrupt tree' exists which represents the | |
3358 | hierarchy and routing of interrupts in the hardware. | |
3359 | ||
3360 | The interrupt tree model is fully described in the | |
3361 | document "Open Firmware Recommended Practice: Interrupt | |
3362 | Mapping Version 0.9". The document is available at: | |
3363 | <http://playground.sun.com/1275/practice>. | |
3364 | ||
3365 | 1) interrupts property | |
3366 | ---------------------- | |
3367 | ||
3368 | Devices that generate interrupts to a single interrupt controller | |
3369 | should use the conventional OF representation described in the | |
3370 | OF interrupt mapping documentation. | |
3371 | ||
3372 | Each device which generates interrupts must have an 'interrupt' | |
3373 | property. The interrupt property value is an arbitrary number of | |
3374 | of 'interrupt specifier' values which describe the interrupt or | |
3375 | interrupts for the device. | |
3376 | ||
3377 | The encoding of an interrupt specifier is determined by the | |
3378 | interrupt domain in which the device is located in the | |
3379 | interrupt tree. The root of an interrupt domain specifies in | |
3380 | its #interrupt-cells property the number of 32-bit cells | |
3381 | required to encode an interrupt specifier. See the OF interrupt | |
3382 | mapping documentation for a detailed description of domains. | |
3383 | ||
3384 | For example, the binding for the OpenPIC interrupt controller | |
3385 | specifies an #interrupt-cells value of 2 to encode the interrupt | |
3386 | number and level/sense information. All interrupt children in an | |
3387 | OpenPIC interrupt domain use 2 cells per interrupt in their interrupts | |
3388 | property. | |
3389 | ||
3390 | The PCI bus binding specifies a #interrupt-cell value of 1 to encode | |
3391 | which interrupt pin (INTA,INTB,INTC,INTD) is used. | |
3392 | ||
3393 | 2) interrupt-parent property | |
3394 | ---------------------------- | |
3395 | ||
3396 | The interrupt-parent property is specified to define an explicit | |
3397 | link between a device node and its interrupt parent in | |
3398 | the interrupt tree. The value of interrupt-parent is the | |
3399 | phandle of the parent node. | |
3400 | ||
3401 | If the interrupt-parent property is not defined for a node, it's | |
3402 | interrupt parent is assumed to be an ancestor in the node's | |
3403 | _device tree_ hierarchy. | |
3404 | ||
3405 | 3) OpenPIC Interrupt Controllers | |
3406 | -------------------------------- | |
3407 | ||
3408 | OpenPIC interrupt controllers require 2 cells to encode | |
3409 | interrupt information. The first cell defines the interrupt | |
3410 | number. The second cell defines the sense and level | |
3411 | information. | |
3412 | ||
3413 | Sense and level information should be encoded as follows: | |
3414 | ||
3415 | 0 = low to high edge sensitive type enabled | |
3416 | 1 = active low level sensitive type enabled | |
3417 | 2 = active high level sensitive type enabled | |
3418 | 3 = high to low edge sensitive type enabled | |
3419 | ||
3420 | 4) ISA Interrupt Controllers | |
3421 | ---------------------------- | |
3422 | ||
3423 | ISA PIC interrupt controllers require 2 cells to encode | |
3424 | interrupt information. The first cell defines the interrupt | |
3425 | number. The second cell defines the sense and level | |
3426 | information. | |
3427 | ||
3428 | ISA PIC interrupt controllers should adhere to the ISA PIC | |
3429 | encodings listed below: | |
3430 | ||
3431 | 0 = active low level sensitive type enabled | |
3432 | 1 = active high level sensitive type enabled | |
3433 | 2 = high to low edge sensitive type enabled | |
3434 | 3 = low to high edge sensitive type enabled | |
3435 | ||
b7ce3415 AV |
3436 | VIII - Specifying GPIO information for devices |
3437 | ============================================== | |
3438 | ||
3439 | 1) gpios property | |
3440 | ----------------- | |
3441 | ||
3442 | Nodes that makes use of GPIOs should define them using `gpios' property, | |
3443 | format of which is: <&gpio-controller1-phandle gpio1-specifier | |
3444 | &gpio-controller2-phandle gpio2-specifier | |
3445 | 0 /* holes are permitted, means no GPIO 3 */ | |
3446 | &gpio-controller4-phandle gpio4-specifier | |
3447 | ...>; | |
3448 | ||
3449 | Note that gpio-specifier length is controller dependent. | |
3450 | ||
3451 | gpio-specifier may encode: bank, pin position inside the bank, | |
3452 | whether pin is open-drain and whether pin is logically inverted. | |
3453 | ||
3454 | Example of the node using GPIOs: | |
3455 | ||
3456 | node { | |
3457 | gpios = <&qe_pio_e 18 0>; | |
3458 | }; | |
3459 | ||
3460 | In this example gpio-specifier is "18 0" and encodes GPIO pin number, | |
3461 | and empty GPIO flags as accepted by the "qe_pio_e" gpio-controller. | |
3462 | ||
3463 | 2) gpio-controller nodes | |
3464 | ------------------------ | |
3465 | ||
3466 | Every GPIO controller node must have #gpio-cells property defined, | |
3467 | this information will be used to translate gpio-specifiers. | |
3468 | ||
3469 | Example of two SOC GPIO banks defined as gpio-controller nodes: | |
3470 | ||
3471 | qe_pio_a: gpio-controller@1400 { | |
3472 | #gpio-cells = <2>; | |
3473 | compatible = "fsl,qe-pario-bank-a", "fsl,qe-pario-bank"; | |
3474 | reg = <0x1400 0x18>; | |
3475 | gpio-controller; | |
3476 | }; | |
3477 | ||
3478 | qe_pio_e: gpio-controller@1460 { | |
3479 | #gpio-cells = <2>; | |
3480 | compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank"; | |
3481 | reg = <0x1460 0x18>; | |
3482 | gpio-controller; | |
3483 | }; | |
c125a183 DG |
3484 | |
3485 | Appendix A - Sample SOC node for MPC8540 | |
3486 | ======================================== | |
3487 | ||
3488 | Note that the #address-cells and #size-cells for the SoC node | |
3489 | in this example have been explicitly listed; these are likely | |
3490 | not necessary as they are usually the same as the root node. | |
3491 | ||
3492 | soc8540@e0000000 { | |
3493 | #address-cells = <1>; | |
3494 | #size-cells = <1>; | |
3495 | #interrupt-cells = <2>; | |
3496 | device_type = "soc"; | |
3497 | ranges = <00000000 e0000000 00100000> | |
3498 | reg = <e0000000 00003000>; | |
7d4b95ae | 3499 | bus-frequency = <0>; |
c125a183 DG |
3500 | |
3501 | mdio@24520 { | |
3502 | reg = <24520 20>; | |
3503 | device_type = "mdio"; | |
3504 | compatible = "gianfar"; | |
3505 | ||
3506 | ethernet-phy@0 { | |
3507 | linux,phandle = <2452000> | |
3508 | interrupt-parent = <40000>; | |
3509 | interrupts = <35 1>; | |
3510 | reg = <0>; | |
3511 | device_type = "ethernet-phy"; | |
3512 | }; | |
3513 | ||
3514 | ethernet-phy@1 { | |
3515 | linux,phandle = <2452001> | |
3516 | interrupt-parent = <40000>; | |
3517 | interrupts = <35 1>; | |
3518 | reg = <1>; | |
3519 | device_type = "ethernet-phy"; | |
3520 | }; | |
3521 | ||
3522 | ethernet-phy@3 { | |
3523 | linux,phandle = <2452002> | |
3524 | interrupt-parent = <40000>; | |
3525 | interrupts = <35 1>; | |
3526 | reg = <3>; | |
3527 | device_type = "ethernet-phy"; | |
3528 | }; | |
3529 | ||
3530 | }; | |
3531 | ||
3532 | ethernet@24000 { | |
3533 | #size-cells = <0>; | |
3534 | device_type = "network"; | |
3535 | model = "TSEC"; | |
3536 | compatible = "gianfar"; | |
3537 | reg = <24000 1000>; | |
f583165f | 3538 | mac-address = [ 00 E0 0C 00 73 00 ]; |
c125a183 DG |
3539 | interrupts = <d 3 e 3 12 3>; |
3540 | interrupt-parent = <40000>; | |
3541 | phy-handle = <2452000>; | |
3542 | }; | |
3543 | ||
3544 | ethernet@25000 { | |
3545 | #address-cells = <1>; | |
3546 | #size-cells = <0>; | |
3547 | device_type = "network"; | |
3548 | model = "TSEC"; | |
3549 | compatible = "gianfar"; | |
3550 | reg = <25000 1000>; | |
f583165f | 3551 | mac-address = [ 00 E0 0C 00 73 01 ]; |
c125a183 DG |
3552 | interrupts = <13 3 14 3 18 3>; |
3553 | interrupt-parent = <40000>; | |
3554 | phy-handle = <2452001>; | |
3555 | }; | |
3556 | ||
3557 | ethernet@26000 { | |
3558 | #address-cells = <1>; | |
3559 | #size-cells = <0>; | |
3560 | device_type = "network"; | |
3561 | model = "FEC"; | |
3562 | compatible = "gianfar"; | |
3563 | reg = <26000 1000>; | |
f583165f | 3564 | mac-address = [ 00 E0 0C 00 73 02 ]; |
c125a183 DG |
3565 | interrupts = <19 3>; |
3566 | interrupt-parent = <40000>; | |
3567 | phy-handle = <2452002>; | |
3568 | }; | |
3569 | ||
3570 | serial@4500 { | |
3571 | device_type = "serial"; | |
3572 | compatible = "ns16550"; | |
3573 | reg = <4500 100>; | |
3574 | clock-frequency = <0>; | |
3575 | interrupts = <1a 3>; | |
3576 | interrupt-parent = <40000>; | |
3577 | }; | |
3578 | ||
3579 | pic@40000 { | |
3580 | linux,phandle = <40000>; | |
3581 | clock-frequency = <0>; | |
3582 | interrupt-controller; | |
3583 | #address-cells = <0>; | |
3584 | reg = <40000 40000>; | |
3585 | built-in; | |
3586 | compatible = "chrp,open-pic"; | |
3587 | device_type = "open-pic"; | |
3588 | big-endian; | |
3589 | }; | |
3590 | ||
3591 | i2c@3000 { | |
3592 | interrupt-parent = <40000>; | |
3593 | interrupts = <1b 3>; | |
3594 | reg = <3000 18>; | |
3595 | device_type = "i2c"; | |
3596 | compatible = "fsl-i2c"; | |
3597 | dfsrr; | |
3598 | }; | |
3599 | ||
3600 | }; |