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) | |
a4ecabab | 53 | j) Flash chip nodes |
3b824f85 | 54 | k) Global Utilities Block |
5e1e9ba6 SY |
55 | |
56 | VII - Specifying interrupt information for devices | |
57 | 1) interrupts property | |
58 | 2) interrupt-parent property | |
59 | 3) OpenPIC Interrupt Controllers | |
60 | 4) ISA Interrupt Controllers | |
61 | ||
62 | Appendix A - Sample SOC node for MPC8540 | |
63 | ||
64 | ||
65 | Revision Information | |
66 | ==================== | |
67 | ||
c125a183 DG |
68 | May 18, 2005: Rev 0.1 - Initial draft, no chapter III yet. |
69 | ||
70 | May 19, 2005: Rev 0.2 - Add chapter III and bits & pieces here or | |
71 | clarifies the fact that a lot of things are | |
72 | optional, the kernel only requires a very | |
73 | small device tree, though it is encouraged | |
74 | to provide an as complete one as possible. | |
75 | ||
76 | May 24, 2005: Rev 0.3 - Precise that DT block has to be in RAM | |
77 | - Misc fixes | |
78 | - Define version 3 and new format version 16 | |
79 | for the DT block (version 16 needs kernel | |
80 | patches, will be fwd separately). | |
81 | String block now has a size, and full path | |
82 | is replaced by unit name for more | |
83 | compactness. | |
84 | linux,phandle is made optional, only nodes | |
85 | that are referenced by other nodes need it. | |
86 | "name" property is now automatically | |
87 | deduced from the unit name | |
88 | ||
89 | June 1, 2005: Rev 0.4 - Correct confusion between OF_DT_END and | |
90 | OF_DT_END_NODE in structure definition. | |
91 | - Change version 16 format to always align | |
92 | property data to 4 bytes. Since tokens are | |
93 | already aligned, that means no specific | |
5d3f083d | 94 | required alignment between property size |
c125a183 DG |
95 | and property data. The old style variable |
96 | alignment would make it impossible to do | |
97 | "simple" insertion of properties using | |
5dd60166 | 98 | memmove (thanks Milton for |
c125a183 | 99 | noticing). Updated kernel patch as well |
5d3f083d | 100 | - Correct a few more alignment constraints |
c125a183 DG |
101 | - Add a chapter about the device-tree |
102 | compiler and the textural representation of | |
103 | the tree that can be "compiled" by dtc. | |
104 | ||
c125a183 DG |
105 | November 21, 2005: Rev 0.5 |
106 | - Additions/generalizations for 32-bit | |
107 | - Changed to reflect the new arch/powerpc | |
108 | structure | |
109 | - Added chapter VI | |
110 | ||
111 | ||
112 | ToDo: | |
113 | - Add some definitions of interrupt tree (simple/complex) | |
5dd60166 | 114 | - Add some definitions for PCI host bridges |
c125a183 DG |
115 | - Add some common address format examples |
116 | - Add definitions for standard properties and "compatible" | |
117 | names for cells that are not already defined by the existing | |
118 | OF spec. | |
119 | - Compare FSL SOC use of PCI to standard and make sure no new | |
120 | node definition required. | |
121 | - Add more information about node definitions for SOC devices | |
122 | that currently have no standard, like the FSL CPM. | |
123 | ||
124 | ||
125 | I - Introduction | |
126 | ================ | |
127 | ||
128 | During the recent development of the Linux/ppc64 kernel, and more | |
129 | specifically, the addition of new platform types outside of the old | |
130 | IBM pSeries/iSeries pair, it was decided to enforce some strict rules | |
131 | regarding the kernel entry and bootloader <-> kernel interfaces, in | |
132 | order to avoid the degeneration that had become the ppc32 kernel entry | |
133 | point and the way a new platform should be added to the kernel. The | |
134 | legacy iSeries platform breaks those rules as it predates this scheme, | |
135 | but no new board support will be accepted in the main tree that | |
136 | doesn't follows them properly. In addition, since the advent of the | |
137 | arch/powerpc merged architecture for ppc32 and ppc64, new 32-bit | |
138 | platforms and 32-bit platforms which move into arch/powerpc will be | |
139 | required to use these rules as well. | |
140 | ||
141 | The main requirement that will be defined in more detail below is | |
142 | the presence of a device-tree whose format is defined after Open | |
143 | Firmware specification. However, in order to make life easier | |
144 | to embedded board vendors, the kernel doesn't require the device-tree | |
145 | to represent every device in the system and only requires some nodes | |
146 | and properties to be present. This will be described in detail in | |
147 | section III, but, for example, the kernel does not require you to | |
148 | create a node for every PCI device in the system. It is a requirement | |
149 | to have a node for PCI host bridges in order to provide interrupt | |
150 | routing informations and memory/IO ranges, among others. It is also | |
151 | recommended to define nodes for on chip devices and other busses that | |
152 | don't specifically fit in an existing OF specification. This creates a | |
153 | great flexibility in the way the kernel can then probe those and match | |
154 | drivers to device, without having to hard code all sorts of tables. It | |
155 | also makes it more flexible for board vendors to do minor hardware | |
156 | upgrades without significantly impacting the kernel code or cluttering | |
157 | it with special cases. | |
158 | ||
159 | ||
160 | 1) Entry point for arch/powerpc | |
161 | ------------------------------- | |
162 | ||
163 | There is one and one single entry point to the kernel, at the start | |
164 | of the kernel image. That entry point supports two calling | |
165 | conventions: | |
166 | ||
167 | a) Boot from Open Firmware. If your firmware is compatible | |
168 | with Open Firmware (IEEE 1275) or provides an OF compatible | |
169 | client interface API (support for "interpret" callback of | |
170 | forth words isn't required), you can enter the kernel with: | |
171 | ||
172 | r5 : OF callback pointer as defined by IEEE 1275 | |
5dd60166 | 173 | bindings to powerpc. Only the 32-bit client interface |
c125a183 DG |
174 | is currently supported |
175 | ||
176 | r3, r4 : address & length of an initrd if any or 0 | |
177 | ||
178 | The MMU is either on or off; the kernel will run the | |
179 | trampoline located in arch/powerpc/kernel/prom_init.c to | |
180 | extract the device-tree and other information from open | |
181 | firmware and build a flattened device-tree as described | |
182 | in b). prom_init() will then re-enter the kernel using | |
183 | the second method. This trampoline code runs in the | |
184 | context of the firmware, which is supposed to handle all | |
185 | exceptions during that time. | |
186 | ||
187 | b) Direct entry with a flattened device-tree block. This entry | |
188 | point is called by a) after the OF trampoline and can also be | |
189 | called directly by a bootloader that does not support the Open | |
190 | Firmware client interface. It is also used by "kexec" to | |
191 | implement "hot" booting of a new kernel from a previous | |
192 | running one. This method is what I will describe in more | |
193 | details in this document, as method a) is simply standard Open | |
194 | Firmware, and thus should be implemented according to the | |
195 | various standard documents defining it and its binding to the | |
196 | PowerPC platform. The entry point definition then becomes: | |
197 | ||
198 | r3 : physical pointer to the device-tree block | |
199 | (defined in chapter II) in RAM | |
200 | ||
201 | r4 : physical pointer to the kernel itself. This is | |
202 | used by the assembly code to properly disable the MMU | |
203 | in case you are entering the kernel with MMU enabled | |
204 | and a non-1:1 mapping. | |
205 | ||
2fe0ae78 | 206 | r5 : NULL (as to differentiate with method a) |
c125a183 DG |
207 | |
208 | Note about SMP entry: Either your firmware puts your other | |
209 | CPUs in some sleep loop or spin loop in ROM where you can get | |
210 | them out via a soft reset or some other means, in which case | |
211 | you don't need to care, or you'll have to enter the kernel | |
212 | with all CPUs. The way to do that with method b) will be | |
213 | described in a later revision of this document. | |
214 | ||
215 | ||
216 | 2) Board support | |
217 | ---------------- | |
218 | ||
219 | 64-bit kernels: | |
220 | ||
221 | Board supports (platforms) are not exclusive config options. An | |
222 | arbitrary set of board supports can be built in a single kernel | |
223 | image. The kernel will "know" what set of functions to use for a | |
224 | given platform based on the content of the device-tree. Thus, you | |
225 | should: | |
226 | ||
227 | a) add your platform support as a _boolean_ option in | |
228 | arch/powerpc/Kconfig, following the example of PPC_PSERIES, | |
229 | PPC_PMAC and PPC_MAPLE. The later is probably a good | |
230 | example of a board support to start from. | |
231 | ||
232 | b) create your main platform file as | |
233 | "arch/powerpc/platforms/myplatform/myboard_setup.c" and add it | |
234 | to the Makefile under the condition of your CONFIG_ | |
235 | option. This file will define a structure of type "ppc_md" | |
236 | containing the various callbacks that the generic code will | |
237 | use to get to your platform specific code | |
238 | ||
239 | c) Add a reference to your "ppc_md" structure in the | |
240 | "machines" table in arch/powerpc/kernel/setup_64.c if you are | |
241 | a 64-bit platform. | |
242 | ||
243 | d) request and get assigned a platform number (see PLATFORM_* | |
244 | constants in include/asm-powerpc/processor.h | |
245 | ||
246 | 32-bit embedded kernels: | |
247 | ||
248 | Currently, board support is essentially an exclusive config option. | |
249 | The kernel is configured for a single platform. Part of the reason | |
250 | for this is to keep kernels on embedded systems small and efficient; | |
251 | part of this is due to the fact the code is already that way. In the | |
252 | future, a kernel may support multiple platforms, but only if the | |
5dd60166 | 253 | platforms feature the same core architecture. A single kernel build |
c125a183 DG |
254 | cannot support both configurations with Book E and configurations |
255 | with classic Powerpc architectures. | |
256 | ||
257 | 32-bit embedded platforms that are moved into arch/powerpc using a | |
258 | flattened device tree should adopt the merged tree practice of | |
259 | setting ppc_md up dynamically, even though the kernel is currently | |
260 | built with support for only a single platform at a time. This allows | |
261 | unification of the setup code, and will make it easier to go to a | |
262 | multiple-platform-support model in the future. | |
263 | ||
264 | NOTE: I believe the above will be true once Ben's done with the merge | |
265 | of the boot sequences.... someone speak up if this is wrong! | |
266 | ||
267 | To add a 32-bit embedded platform support, follow the instructions | |
268 | for 64-bit platforms above, with the exception that the Kconfig | |
269 | option should be set up such that the kernel builds exclusively for | |
270 | the platform selected. The processor type for the platform should | |
271 | enable another config option to select the specific board | |
272 | supported. | |
273 | ||
5dd60166 | 274 | NOTE: If Ben doesn't merge the setup files, may need to change this to |
c125a183 DG |
275 | point to setup_32.c |
276 | ||
277 | ||
278 | I will describe later the boot process and various callbacks that | |
279 | your platform should implement. | |
280 | ||
281 | ||
282 | II - The DT block format | |
283 | ======================== | |
284 | ||
285 | ||
286 | This chapter defines the actual format of the flattened device-tree | |
287 | passed to the kernel. The actual content of it and kernel requirements | |
288 | are described later. You can find example of code manipulating that | |
289 | format in various places, including arch/powerpc/kernel/prom_init.c | |
290 | which will generate a flattened device-tree from the Open Firmware | |
291 | representation, or the fs2dt utility which is part of the kexec tools | |
292 | which will generate one from a filesystem representation. It is | |
293 | expected that a bootloader like uboot provides a bit more support, | |
294 | that will be discussed later as well. | |
295 | ||
296 | Note: The block has to be in main memory. It has to be accessible in | |
297 | both real mode and virtual mode with no mapping other than main | |
298 | memory. If you are writing a simple flash bootloader, it should copy | |
299 | the block to RAM before passing it to the kernel. | |
300 | ||
301 | ||
302 | 1) Header | |
303 | --------- | |
304 | ||
305 | The kernel is entered with r3 pointing to an area of memory that is | |
d6bc8ac9 | 306 | roughly described in include/asm-powerpc/prom.h by the structure |
c125a183 DG |
307 | boot_param_header: |
308 | ||
309 | struct boot_param_header { | |
310 | u32 magic; /* magic word OF_DT_HEADER */ | |
311 | u32 totalsize; /* total size of DT block */ | |
312 | u32 off_dt_struct; /* offset to structure */ | |
313 | u32 off_dt_strings; /* offset to strings */ | |
314 | u32 off_mem_rsvmap; /* offset to memory reserve map | |
5dd60166 | 315 | */ |
c125a183 DG |
316 | u32 version; /* format version */ |
317 | u32 last_comp_version; /* last compatible version */ | |
318 | ||
319 | /* version 2 fields below */ | |
320 | u32 boot_cpuid_phys; /* Which physical CPU id we're | |
321 | booting on */ | |
322 | /* version 3 fields below */ | |
323 | u32 size_dt_strings; /* size of the strings block */ | |
0e0293c8 DG |
324 | |
325 | /* version 17 fields below */ | |
326 | u32 size_dt_struct; /* size of the DT structure block */ | |
c125a183 DG |
327 | }; |
328 | ||
329 | Along with the constants: | |
330 | ||
331 | /* Definitions used by the flattened device tree */ | |
332 | #define OF_DT_HEADER 0xd00dfeed /* 4: version, | |
333 | 4: total size */ | |
334 | #define OF_DT_BEGIN_NODE 0x1 /* Start node: full name | |
5dd60166 | 335 | */ |
c125a183 DG |
336 | #define OF_DT_END_NODE 0x2 /* End node */ |
337 | #define OF_DT_PROP 0x3 /* Property: name off, | |
338 | size, content */ | |
339 | #define OF_DT_END 0x9 | |
340 | ||
341 | All values in this header are in big endian format, the various | |
342 | fields in this header are defined more precisely below. All | |
343 | "offset" values are in bytes from the start of the header; that is | |
344 | from the value of r3. | |
345 | ||
346 | - magic | |
347 | ||
348 | This is a magic value that "marks" the beginning of the | |
349 | device-tree block header. It contains the value 0xd00dfeed and is | |
350 | defined by the constant OF_DT_HEADER | |
351 | ||
352 | - totalsize | |
353 | ||
354 | This is the total size of the DT block including the header. The | |
355 | "DT" block should enclose all data structures defined in this | |
356 | chapter (who are pointed to by offsets in this header). That is, | |
357 | the device-tree structure, strings, and the memory reserve map. | |
358 | ||
359 | - off_dt_struct | |
360 | ||
361 | This is an offset from the beginning of the header to the start | |
362 | of the "structure" part the device tree. (see 2) device tree) | |
363 | ||
364 | - off_dt_strings | |
365 | ||
366 | This is an offset from the beginning of the header to the start | |
367 | of the "strings" part of the device-tree | |
368 | ||
369 | - off_mem_rsvmap | |
370 | ||
371 | This is an offset from the beginning of the header to the start | |
5dd60166 | 372 | of the reserved memory map. This map is a list of pairs of 64- |
c125a183 | 373 | bit integers. Each pair is a physical address and a size. The |
c125a183 DG |
374 | list is terminated by an entry of size 0. This map provides the |
375 | kernel with a list of physical memory areas that are "reserved" | |
376 | and thus not to be used for memory allocations, especially during | |
377 | early initialization. The kernel needs to allocate memory during | |
378 | boot for things like un-flattening the device-tree, allocating an | |
379 | MMU hash table, etc... Those allocations must be done in such a | |
380 | way to avoid overriding critical things like, on Open Firmware | |
381 | capable machines, the RTAS instance, or on some pSeries, the TCE | |
382 | tables used for the iommu. Typically, the reserve map should | |
383 | contain _at least_ this DT block itself (header,total_size). If | |
384 | you are passing an initrd to the kernel, you should reserve it as | |
385 | well. You do not need to reserve the kernel image itself. The map | |
5dd60166 | 386 | should be 64-bit aligned. |
c125a183 DG |
387 | |
388 | - version | |
389 | ||
390 | This is the version of this structure. Version 1 stops | |
391 | here. Version 2 adds an additional field boot_cpuid_phys. | |
392 | Version 3 adds the size of the strings block, allowing the kernel | |
393 | to reallocate it easily at boot and free up the unused flattened | |
394 | structure after expansion. Version 16 introduces a new more | |
395 | "compact" format for the tree itself that is however not backward | |
0e0293c8 DG |
396 | compatible. Version 17 adds an additional field, size_dt_struct, |
397 | allowing it to be reallocated or moved more easily (this is | |
398 | particularly useful for bootloaders which need to make | |
399 | adjustments to a device tree based on probed information). You | |
400 | should always generate a structure of the highest version defined | |
401 | at the time of your implementation. Currently that is version 17, | |
402 | unless you explicitly aim at being backward compatible. | |
c125a183 DG |
403 | |
404 | - last_comp_version | |
405 | ||
406 | Last compatible version. This indicates down to what version of | |
407 | the DT block you are backward compatible. For example, version 2 | |
408 | is backward compatible with version 1 (that is, a kernel build | |
409 | for version 1 will be able to boot with a version 2 format). You | |
410 | should put a 1 in this field if you generate a device tree of | |
0e0293c8 | 411 | version 1 to 3, or 16 if you generate a tree of version 16 or 17 |
c125a183 DG |
412 | using the new unit name format. |
413 | ||
414 | - boot_cpuid_phys | |
415 | ||
416 | This field only exist on version 2 headers. It indicate which | |
417 | physical CPU ID is calling the kernel entry point. This is used, | |
418 | among others, by kexec. If you are on an SMP system, this value | |
419 | should match the content of the "reg" property of the CPU node in | |
420 | the device-tree corresponding to the CPU calling the kernel entry | |
421 | point (see further chapters for more informations on the required | |
422 | device-tree contents) | |
423 | ||
0e0293c8 DG |
424 | - size_dt_strings |
425 | ||
426 | This field only exists on version 3 and later headers. It | |
427 | gives the size of the "strings" section of the device tree (which | |
428 | starts at the offset given by off_dt_strings). | |
429 | ||
430 | - size_dt_struct | |
431 | ||
432 | This field only exists on version 17 and later headers. It gives | |
433 | the size of the "structure" section of the device tree (which | |
434 | starts at the offset given by off_dt_struct). | |
c125a183 DG |
435 | |
436 | So the typical layout of a DT block (though the various parts don't | |
437 | need to be in that order) looks like this (addresses go from top to | |
438 | bottom): | |
439 | ||
440 | ||
441 | ------------------------------ | |
442 | r3 -> | struct boot_param_header | | |
443 | ------------------------------ | |
444 | | (alignment gap) (*) | | |
445 | ------------------------------ | |
446 | | memory reserve map | | |
447 | ------------------------------ | |
448 | | (alignment gap) | | |
449 | ------------------------------ | |
450 | | | | |
451 | | device-tree structure | | |
452 | | | | |
453 | ------------------------------ | |
454 | | (alignment gap) | | |
455 | ------------------------------ | |
456 | | | | |
457 | | device-tree strings | | |
458 | | | | |
459 | -----> ------------------------------ | |
460 | | | |
461 | | | |
462 | --- (r3 + totalsize) | |
463 | ||
464 | (*) The alignment gaps are not necessarily present; their presence | |
465 | and size are dependent on the various alignment requirements of | |
466 | the individual data blocks. | |
467 | ||
468 | ||
469 | 2) Device tree generalities | |
470 | --------------------------- | |
471 | ||
472 | This device-tree itself is separated in two different blocks, a | |
473 | structure block and a strings block. Both need to be aligned to a 4 | |
474 | byte boundary. | |
475 | ||
476 | First, let's quickly describe the device-tree concept before detailing | |
477 | the storage format. This chapter does _not_ describe the detail of the | |
478 | required types of nodes & properties for the kernel, this is done | |
479 | later in chapter III. | |
480 | ||
481 | The device-tree layout is strongly inherited from the definition of | |
482 | the Open Firmware IEEE 1275 device-tree. It's basically a tree of | |
483 | nodes, each node having two or more named properties. A property can | |
484 | have a value or not. | |
485 | ||
486 | It is a tree, so each node has one and only one parent except for the | |
487 | root node who has no parent. | |
488 | ||
489 | A node has 2 names. The actual node name is generally contained in a | |
490 | property of type "name" in the node property list whose value is a | |
491 | zero terminated string and is mandatory for version 1 to 3 of the | |
0e0293c8 | 492 | format definition (as it is in Open Firmware). Version 16 makes it |
c125a183 DG |
493 | optional as it can generate it from the unit name defined below. |
494 | ||
2fe0ae78 | 495 | There is also a "unit name" that is used to differentiate nodes with |
c125a183 | 496 | the same name at the same level, it is usually made of the node |
2fe0ae78 | 497 | names, the "@" sign, and a "unit address", which definition is |
c125a183 DG |
498 | specific to the bus type the node sits on. |
499 | ||
500 | The unit name doesn't exist as a property per-se but is included in | |
501 | the device-tree structure. It is typically used to represent "path" in | |
502 | the device-tree. More details about the actual format of these will be | |
503 | below. | |
504 | ||
505 | The kernel powerpc generic code does not make any formal use of the | |
506 | unit address (though some board support code may do) so the only real | |
507 | requirement here for the unit address is to ensure uniqueness of | |
508 | the node unit name at a given level of the tree. Nodes with no notion | |
509 | of address and no possible sibling of the same name (like /memory or | |
510 | /cpus) may omit the unit address in the context of this specification, | |
511 | or use the "@0" default unit address. The unit name is used to define | |
512 | a node "full path", which is the concatenation of all parent node | |
513 | unit names separated with "/". | |
514 | ||
515 | The root node doesn't have a defined name, and isn't required to have | |
516 | a name property either if you are using version 3 or earlier of the | |
517 | format. It also has no unit address (no @ symbol followed by a unit | |
518 | address). The root node unit name is thus an empty string. The full | |
519 | path to the root node is "/". | |
520 | ||
521 | Every node which actually represents an actual device (that is, a node | |
522 | which isn't only a virtual "container" for more nodes, like "/cpus" | |
523 | is) is also required to have a "device_type" property indicating the | |
524 | type of node . | |
525 | ||
526 | Finally, every node that can be referenced from a property in another | |
527 | node is required to have a "linux,phandle" property. Real open | |
528 | firmware implementations provide a unique "phandle" value for every | |
529 | node that the "prom_init()" trampoline code turns into | |
530 | "linux,phandle" properties. However, this is made optional if the | |
531 | flattened device tree is used directly. An example of a node | |
532 | referencing another node via "phandle" is when laying out the | |
533 | interrupt tree which will be described in a further version of this | |
534 | document. | |
535 | ||
5dd60166 | 536 | This "linux, phandle" property is a 32-bit value that uniquely |
c125a183 DG |
537 | identifies a node. You are free to use whatever values or system of |
538 | values, internal pointers, or whatever to generate these, the only | |
539 | requirement is that every node for which you provide that property has | |
540 | a unique value for it. | |
541 | ||
542 | Here is an example of a simple device-tree. In this example, an "o" | |
543 | designates a node followed by the node unit name. Properties are | |
544 | presented with their name followed by their content. "content" | |
545 | represents an ASCII string (zero terminated) value, while <content> | |
5dd60166 | 546 | represents a 32-bit hexadecimal value. The various nodes in this |
c125a183 DG |
547 | example will be discussed in a later chapter. At this point, it is |
548 | only meant to give you a idea of what a device-tree looks like. I have | |
549 | purposefully kept the "name" and "linux,phandle" properties which | |
550 | aren't necessary in order to give you a better idea of what the tree | |
551 | looks like in practice. | |
552 | ||
553 | / o device-tree | |
554 | |- name = "device-tree" | |
555 | |- model = "MyBoardName" | |
556 | |- compatible = "MyBoardFamilyName" | |
557 | |- #address-cells = <2> | |
558 | |- #size-cells = <2> | |
559 | |- linux,phandle = <0> | |
560 | | | |
561 | o cpus | |
562 | | | - name = "cpus" | |
563 | | | - linux,phandle = <1> | |
564 | | | - #address-cells = <1> | |
565 | | | - #size-cells = <0> | |
566 | | | | |
567 | | o PowerPC,970@0 | |
568 | | |- name = "PowerPC,970" | |
569 | | |- device_type = "cpu" | |
570 | | |- reg = <0> | |
571 | | |- clock-frequency = <5f5e1000> | |
32aed2a5 | 572 | | |- 64-bit |
c125a183 DG |
573 | | |- linux,phandle = <2> |
574 | | | |
575 | o memory@0 | |
576 | | |- name = "memory" | |
577 | | |- device_type = "memory" | |
578 | | |- reg = <00000000 00000000 00000000 20000000> | |
579 | | |- linux,phandle = <3> | |
580 | | | |
581 | o chosen | |
582 | |- name = "chosen" | |
583 | |- bootargs = "root=/dev/sda2" | |
c125a183 DG |
584 | |- linux,phandle = <4> |
585 | ||
586 | This tree is almost a minimal tree. It pretty much contains the | |
587 | minimal set of required nodes and properties to boot a linux kernel; | |
588 | that is, some basic model informations at the root, the CPUs, and the | |
589 | physical memory layout. It also includes misc information passed | |
590 | through /chosen, like in this example, the platform type (mandatory) | |
591 | and the kernel command line arguments (optional). | |
592 | ||
32aed2a5 | 593 | The /cpus/PowerPC,970@0/64-bit property is an example of a |
c125a183 DG |
594 | property without a value. All other properties have a value. The |
595 | significance of the #address-cells and #size-cells properties will be | |
596 | explained in chapter IV which defines precisely the required nodes and | |
597 | properties and their content. | |
598 | ||
599 | ||
600 | 3) Device tree "structure" block | |
601 | ||
602 | The structure of the device tree is a linearized tree structure. The | |
603 | "OF_DT_BEGIN_NODE" token starts a new node, and the "OF_DT_END_NODE" | |
604 | ends that node definition. Child nodes are simply defined before | |
605 | "OF_DT_END_NODE" (that is nodes within the node). A 'token' is a 32 | |
606 | bit value. The tree has to be "finished" with a OF_DT_END token | |
607 | ||
608 | Here's the basic structure of a single node: | |
609 | ||
610 | * token OF_DT_BEGIN_NODE (that is 0x00000001) | |
611 | * for version 1 to 3, this is the node full path as a zero | |
612 | terminated string, starting with "/". For version 16 and later, | |
613 | this is the node unit name only (or an empty string for the | |
614 | root node) | |
615 | * [align gap to next 4 bytes boundary] | |
616 | * for each property: | |
617 | * token OF_DT_PROP (that is 0x00000003) | |
5dd60166 DP |
618 | * 32-bit value of property value size in bytes (or 0 if no |
619 | value) | |
620 | * 32-bit value of offset in string block of property name | |
c125a183 DG |
621 | * property value data if any |
622 | * [align gap to next 4 bytes boundary] | |
623 | * [child nodes if any] | |
624 | * token OF_DT_END_NODE (that is 0x00000002) | |
625 | ||
5dd60166 | 626 | So the node content can be summarized as a start token, a full path, |
53cb4726 | 627 | a list of properties, a list of child nodes, and an end token. Every |
c125a183 DG |
628 | child node is a full node structure itself as defined above. |
629 | ||
eff2ebd2 DG |
630 | NOTE: The above definition requires that all property definitions for |
631 | a particular node MUST precede any subnode definitions for that node. | |
632 | Although the structure would not be ambiguous if properties and | |
633 | subnodes were intermingled, the kernel parser requires that the | |
634 | properties come first (up until at least 2.6.22). Any tools | |
635 | manipulating a flattened tree must take care to preserve this | |
636 | constraint. | |
637 | ||
53cb4726 | 638 | 4) Device tree "strings" block |
c125a183 DG |
639 | |
640 | In order to save space, property names, which are generally redundant, | |
641 | are stored separately in the "strings" block. This block is simply the | |
642 | whole bunch of zero terminated strings for all property names | |
643 | concatenated together. The device-tree property definitions in the | |
644 | structure block will contain offset values from the beginning of the | |
645 | strings block. | |
646 | ||
647 | ||
648 | III - Required content of the device tree | |
649 | ========================================= | |
650 | ||
651 | WARNING: All "linux,*" properties defined in this document apply only | |
652 | to a flattened device-tree. If your platform uses a real | |
653 | implementation of Open Firmware or an implementation compatible with | |
654 | the Open Firmware client interface, those properties will be created | |
655 | by the trampoline code in the kernel's prom_init() file. For example, | |
656 | that's where you'll have to add code to detect your board model and | |
a2ffd275 | 657 | set the platform number. However, when using the flattened device-tree |
c125a183 DG |
658 | entry point, there is no prom_init() pass, and thus you have to |
659 | provide those properties yourself. | |
660 | ||
661 | ||
662 | 1) Note about cells and address representation | |
663 | ---------------------------------------------- | |
664 | ||
665 | The general rule is documented in the various Open Firmware | |
5dd60166 | 666 | documentations. If you choose to describe a bus with the device-tree |
c125a183 DG |
667 | and there exist an OF bus binding, then you should follow the |
668 | specification. However, the kernel does not require every single | |
669 | device or bus to be described by the device tree. | |
670 | ||
671 | In general, the format of an address for a device is defined by the | |
672 | parent bus type, based on the #address-cells and #size-cells | |
673 | property. In the absence of such a property, the parent's parent | |
674 | values are used, etc... The kernel requires the root node to have | |
675 | those properties defining addresses format for devices directly mapped | |
676 | on the processor bus. | |
677 | ||
678 | Those 2 properties define 'cells' for representing an address and a | |
5dd60166 | 679 | size. A "cell" is a 32-bit number. For example, if both contain 2 |
c125a183 | 680 | like the example tree given above, then an address and a size are both |
5dd60166 | 681 | composed of 2 cells, and each is a 64-bit number (cells are |
c125a183 DG |
682 | concatenated and expected to be in big endian format). Another example |
683 | is the way Apple firmware defines them, with 2 cells for an address | |
684 | and one cell for a size. Most 32-bit implementations should define | |
685 | #address-cells and #size-cells to 1, which represents a 32-bit value. | |
686 | Some 32-bit processors allow for physical addresses greater than 32 | |
687 | bits; these processors should define #address-cells as 2. | |
688 | ||
689 | "reg" properties are always a tuple of the type "address size" where | |
690 | the number of cells of address and size is specified by the bus | |
691 | #address-cells and #size-cells. When a bus supports various address | |
692 | spaces and other flags relative to a given address allocation (like | |
693 | prefetchable, etc...) those flags are usually added to the top level | |
694 | bits of the physical address. For example, a PCI physical address is | |
695 | made of 3 cells, the bottom two containing the actual address itself | |
696 | while the top cell contains address space indication, flags, and pci | |
697 | bus & device numbers. | |
698 | ||
699 | For busses that support dynamic allocation, it's the accepted practice | |
700 | to then not provide the address in "reg" (keep it 0) though while | |
701 | providing a flag indicating the address is dynamically allocated, and | |
702 | then, to provide a separate "assigned-addresses" property that | |
703 | contains the fully allocated addresses. See the PCI OF bindings for | |
704 | details. | |
705 | ||
706 | In general, a simple bus with no address space bits and no dynamic | |
707 | allocation is preferred if it reflects your hardware, as the existing | |
708 | kernel address parsing functions will work out of the box. If you | |
709 | define a bus type with a more complex address format, including things | |
710 | like address space bits, you'll have to add a bus translator to the | |
711 | prom_parse.c file of the recent kernels for your bus type. | |
712 | ||
713 | The "reg" property only defines addresses and sizes (if #size-cells | |
992caacf | 714 | is non-0) within a given bus. In order to translate addresses upward |
5dd60166 | 715 | (that is into parent bus addresses, and possibly into CPU physical |
c125a183 DG |
716 | addresses), all busses must contain a "ranges" property. If the |
717 | "ranges" property is missing at a given level, it's assumed that | |
992caacf | 718 | translation isn't possible. The format of the "ranges" property for a |
c125a183 DG |
719 | bus is a list of: |
720 | ||
721 | bus address, parent bus address, size | |
722 | ||
723 | "bus address" is in the format of the bus this bus node is defining, | |
724 | that is, for a PCI bridge, it would be a PCI address. Thus, (bus | |
725 | address, size) defines a range of addresses for child devices. "parent | |
726 | bus address" is in the format of the parent bus of this bus. For | |
727 | example, for a PCI host controller, that would be a CPU address. For a | |
728 | PCI<->ISA bridge, that would be a PCI address. It defines the base | |
729 | address in the parent bus where the beginning of that range is mapped. | |
730 | ||
5dd60166 | 731 | For a new 64-bit powerpc board, I recommend either the 2/2 format or |
c125a183 | 732 | Apple's 2/1 format which is slightly more compact since sizes usually |
5dd60166 | 733 | fit in a single 32-bit word. New 32-bit powerpc boards should use a |
c125a183 DG |
734 | 1/1 format, unless the processor supports physical addresses greater |
735 | than 32-bits, in which case a 2/1 format is recommended. | |
736 | ||
737 | ||
738 | 2) Note about "compatible" properties | |
739 | ------------------------------------- | |
740 | ||
741 | These properties are optional, but recommended in devices and the root | |
742 | node. The format of a "compatible" property is a list of concatenated | |
743 | zero terminated strings. They allow a device to express its | |
744 | compatibility with a family of similar devices, in some cases, | |
745 | allowing a single driver to match against several devices regardless | |
746 | of their actual names. | |
747 | ||
748 | 3) Note about "name" properties | |
749 | ------------------------------- | |
750 | ||
751 | While earlier users of Open Firmware like OldWorld macintoshes tended | |
752 | to use the actual device name for the "name" property, it's nowadays | |
753 | considered a good practice to use a name that is closer to the device | |
754 | class (often equal to device_type). For example, nowadays, ethernet | |
755 | controllers are named "ethernet", an additional "model" property | |
756 | defining precisely the chip type/model, and "compatible" property | |
757 | defining the family in case a single driver can driver more than one | |
758 | of these chips. However, the kernel doesn't generally put any | |
759 | restriction on the "name" property; it is simply considered good | |
760 | practice to follow the standard and its evolutions as closely as | |
761 | possible. | |
762 | ||
763 | Note also that the new format version 16 makes the "name" property | |
764 | optional. If it's absent for a node, then the node's unit name is then | |
765 | used to reconstruct the name. That is, the part of the unit name | |
766 | before the "@" sign is used (or the entire unit name if no "@" sign | |
767 | is present). | |
768 | ||
769 | 4) Note about node and property names and character set | |
770 | ------------------------------------------------------- | |
771 | ||
a2ffd275 | 772 | While open firmware provides more flexible usage of 8859-1, this |
c125a183 DG |
773 | specification enforces more strict rules. Nodes and properties should |
774 | be comprised only of ASCII characters 'a' to 'z', '0' to | |
775 | '9', ',', '.', '_', '+', '#', '?', and '-'. Node names additionally | |
776 | allow uppercase characters 'A' to 'Z' (property names should be | |
777 | lowercase. The fact that vendors like Apple don't respect this rule is | |
778 | irrelevant here). Additionally, node and property names should always | |
779 | begin with a character in the range 'a' to 'z' (or 'A' to 'Z' for node | |
780 | names). | |
781 | ||
782 | The maximum number of characters for both nodes and property names | |
783 | is 31. In the case of node names, this is only the leftmost part of | |
784 | a unit name (the pure "name" property), it doesn't include the unit | |
785 | address which can extend beyond that limit. | |
786 | ||
787 | ||
788 | 5) Required nodes and properties | |
789 | -------------------------------- | |
790 | These are all that are currently required. However, it is strongly | |
791 | recommended that you expose PCI host bridges as documented in the | |
792 | PCI binding to open firmware, and your interrupt tree as documented | |
793 | in OF interrupt tree specification. | |
794 | ||
795 | a) The root node | |
796 | ||
797 | The root node requires some properties to be present: | |
798 | ||
799 | - model : this is your board name/model | |
800 | - #address-cells : address representation for "root" devices | |
801 | - #size-cells: the size representation for "root" devices | |
e8222502 BH |
802 | - device_type : This property shouldn't be necessary. However, if |
803 | you decide to create a device_type for your root node, make sure it | |
804 | is _not_ "chrp" unless your platform is a pSeries or PAPR compliant | |
805 | one for 64-bit, or a CHRP-type machine for 32-bit as this will | |
806 | matched by the kernel this way. | |
c125a183 DG |
807 | |
808 | Additionally, some recommended properties are: | |
809 | ||
810 | - compatible : the board "family" generally finds its way here, | |
811 | for example, if you have 2 board models with a similar layout, | |
812 | that typically get driven by the same platform code in the | |
813 | kernel, you would use a different "model" property but put a | |
814 | value in "compatible". The kernel doesn't directly use that | |
143a42d1 | 815 | value but it is generally useful. |
c125a183 DG |
816 | |
817 | The root node is also generally where you add additional properties | |
818 | specific to your board like the serial number if any, that sort of | |
6c28f2c0 | 819 | thing. It is recommended that if you add any "custom" property whose |
c125a183 DG |
820 | name may clash with standard defined ones, you prefix them with your |
821 | vendor name and a comma. | |
822 | ||
823 | b) The /cpus node | |
824 | ||
825 | This node is the parent of all individual CPU nodes. It doesn't | |
826 | have any specific requirements, though it's generally good practice | |
827 | to have at least: | |
828 | ||
829 | #address-cells = <00000001> | |
830 | #size-cells = <00000000> | |
831 | ||
832 | This defines that the "address" for a CPU is a single cell, and has | |
833 | no meaningful size. This is not necessary but the kernel will assume | |
834 | that format when reading the "reg" properties of a CPU node, see | |
835 | below | |
836 | ||
837 | c) The /cpus/* nodes | |
838 | ||
839 | So under /cpus, you are supposed to create a node for every CPU on | |
840 | the machine. There is no specific restriction on the name of the | |
841 | CPU, though It's common practice to call it PowerPC,<name>. For | |
842 | example, Apple uses PowerPC,G5 while IBM uses PowerPC,970FX. | |
843 | ||
844 | Required properties: | |
845 | ||
846 | - device_type : has to be "cpu" | |
5dd60166 | 847 | - reg : This is the physical CPU number, it's a single 32-bit cell |
c125a183 DG |
848 | and is also used as-is as the unit number for constructing the |
849 | unit name in the full path. For example, with 2 CPUs, you would | |
850 | have the full path: | |
851 | /cpus/PowerPC,970FX@0 | |
852 | /cpus/PowerPC,970FX@1 | |
853 | (unit addresses do not require leading zeroes) | |
854 | - d-cache-line-size : one cell, L1 data cache line size in bytes | |
855 | - i-cache-line-size : one cell, L1 instruction cache line size in | |
856 | bytes | |
857 | - d-cache-size : one cell, size of L1 data cache in bytes | |
858 | - i-cache-size : one cell, size of L1 instruction cache in bytes | |
c125a183 DG |
859 | |
860 | Recommended properties: | |
861 | ||
862 | - timebase-frequency : a cell indicating the frequency of the | |
863 | timebase in Hz. This is not directly used by the generic code, | |
864 | but you are welcome to copy/paste the pSeries code for setting | |
865 | the kernel timebase/decrementer calibration based on this | |
866 | value. | |
867 | - clock-frequency : a cell indicating the CPU core clock frequency | |
5dd60166 | 868 | in Hz. A new property will be defined for 64-bit values, but if |
c125a183 DG |
869 | your frequency is < 4Ghz, one cell is enough. Here as well as |
870 | for the above, the common code doesn't use that property, but | |
871 | you are welcome to re-use the pSeries or Maple one. A future | |
872 | kernel version might provide a common function for this. | |
873 | ||
874 | You are welcome to add any property you find relevant to your board, | |
875 | like some information about the mechanism used to soft-reset the | |
876 | CPUs. For example, Apple puts the GPIO number for CPU soft reset | |
877 | lines in there as a "soft-reset" property since they start secondary | |
878 | CPUs by soft-resetting them. | |
879 | ||
880 | ||
881 | d) the /memory node(s) | |
882 | ||
883 | To define the physical memory layout of your board, you should | |
884 | create one or more memory node(s). You can either create a single | |
885 | node with all memory ranges in its reg property, or you can create | |
886 | several nodes, as you wish. The unit address (@ part) used for the | |
887 | full path is the address of the first range of memory defined by a | |
888 | given node. If you use a single memory node, this will typically be | |
889 | @0. | |
890 | ||
891 | Required properties: | |
892 | ||
893 | - device_type : has to be "memory" | |
894 | - reg : This property contains all the physical memory ranges of | |
895 | your board. It's a list of addresses/sizes concatenated | |
896 | together, with the number of cells of each defined by the | |
897 | #address-cells and #size-cells of the root node. For example, | |
6c28f2c0 | 898 | with both of these properties being 2 like in the example given |
c125a183 DG |
899 | earlier, a 970 based machine with 6Gb of RAM could typically |
900 | have a "reg" property here that looks like: | |
901 | ||
902 | 00000000 00000000 00000000 80000000 | |
903 | 00000001 00000000 00000001 00000000 | |
904 | ||
905 | That is a range starting at 0 of 0x80000000 bytes and a range | |
906 | starting at 0x100000000 and of 0x100000000 bytes. You can see | |
907 | that there is no memory covering the IO hole between 2Gb and | |
908 | 4Gb. Some vendors prefer splitting those ranges into smaller | |
909 | segments, but the kernel doesn't care. | |
910 | ||
911 | e) The /chosen node | |
912 | ||
913 | This node is a bit "special". Normally, that's where open firmware | |
914 | puts some variable environment information, like the arguments, or | |
d1bff9ed | 915 | the default input/output devices. |
c125a183 DG |
916 | |
917 | This specification makes a few of these mandatory, but also defines | |
918 | some linux-specific properties that would be normally constructed by | |
919 | the prom_init() trampoline when booting with an OF client interface, | |
920 | but that you have to provide yourself when using the flattened format. | |
921 | ||
c125a183 DG |
922 | Recommended properties: |
923 | ||
924 | - bootargs : This zero-terminated string is passed as the kernel | |
925 | command line | |
926 | - linux,stdout-path : This is the full path to your standard | |
927 | console device if any. Typically, if you have serial devices on | |
928 | your board, you may want to put the full path to the one set as | |
929 | the default console in the firmware here, for the kernel to pick | |
5d3f083d | 930 | it up as its own default console. If you look at the function |
c125a183 DG |
931 | set_preferred_console() in arch/ppc64/kernel/setup.c, you'll see |
932 | that the kernel tries to find out the default console and has | |
933 | knowledge of various types like 8250 serial ports. You may want | |
934 | to extend this function to add your own. | |
c125a183 DG |
935 | |
936 | Note that u-boot creates and fills in the chosen node for platforms | |
937 | that use it. | |
938 | ||
d1bff9ed SY |
939 | (Note: a practice that is now obsolete was to include a property |
940 | under /chosen called interrupt-controller which had a phandle value | |
941 | that pointed to the main interrupt controller) | |
942 | ||
c125a183 DG |
943 | f) the /soc<SOCname> node |
944 | ||
945 | This node is used to represent a system-on-a-chip (SOC) and must be | |
946 | present if the processor is a SOC. The top-level soc node contains | |
947 | information that is global to all devices on the SOC. The node name | |
948 | should contain a unit address for the SOC, which is the base address | |
949 | of the memory-mapped register set for the SOC. The name of an soc | |
950 | node should start with "soc", and the remainder of the name should | |
951 | represent the part number for the soc. For example, the MPC8540's | |
952 | soc node would be called "soc8540". | |
953 | ||
954 | Required properties: | |
955 | ||
956 | - device_type : Should be "soc" | |
957 | - ranges : Should be defined as specified in 1) to describe the | |
958 | translation of SOC addresses for memory mapped SOC registers. | |
7d4b95ae BB |
959 | - bus-frequency: Contains the bus frequency for the SOC node. |
960 | Typically, the value of this field is filled in by the boot | |
961 | loader. | |
962 | ||
c125a183 DG |
963 | |
964 | Recommended properties: | |
965 | ||
966 | - reg : This property defines the address and size of the | |
967 | memory-mapped registers that are used for the SOC node itself. | |
968 | It does not include the child device registers - these will be | |
969 | defined inside each child node. The address specified in the | |
970 | "reg" property should match the unit address of the SOC node. | |
971 | - #address-cells : Address representation for "soc" devices. The | |
972 | format of this field may vary depending on whether or not the | |
973 | device registers are memory mapped. For memory mapped | |
974 | registers, this field represents the number of cells needed to | |
975 | represent the address of the registers. For SOCs that do not | |
976 | use MMIO, a special address format should be defined that | |
977 | contains enough cells to represent the required information. | |
978 | See 1) above for more details on defining #address-cells. | |
979 | - #size-cells : Size representation for "soc" devices | |
980 | - #interrupt-cells : Defines the width of cells used to represent | |
981 | interrupts. Typically this value is <2>, which includes a | |
982 | 32-bit number that represents the interrupt number, and a | |
983 | 32-bit number that represents the interrupt sense and level. | |
984 | This field is only needed if the SOC contains an interrupt | |
985 | controller. | |
986 | ||
987 | The SOC node may contain child nodes for each SOC device that the | |
988 | platform uses. Nodes should not be created for devices which exist | |
989 | on the SOC but are not used by a particular platform. See chapter VI | |
5dd60166 | 990 | for more information on how to specify devices that are part of a SOC. |
c125a183 DG |
991 | |
992 | Example SOC node for the MPC8540: | |
993 | ||
994 | soc8540@e0000000 { | |
995 | #address-cells = <1>; | |
996 | #size-cells = <1>; | |
997 | #interrupt-cells = <2>; | |
998 | device_type = "soc"; | |
999 | ranges = <00000000 e0000000 00100000> | |
1000 | reg = <e0000000 00003000>; | |
7d4b95ae | 1001 | bus-frequency = <0>; |
c125a183 DG |
1002 | } |
1003 | ||
1004 | ||
1005 | ||
1006 | IV - "dtc", the device tree compiler | |
1007 | ==================================== | |
1008 | ||
1009 | ||
1010 | dtc source code can be found at | |
1011 | <http://ozlabs.org/~dgibson/dtc/dtc.tar.gz> | |
1012 | ||
1013 | WARNING: This version is still in early development stage; the | |
1014 | resulting device-tree "blobs" have not yet been validated with the | |
1015 | kernel. The current generated bloc lacks a useful reserve map (it will | |
1016 | be fixed to generate an empty one, it's up to the bootloader to fill | |
1017 | it up) among others. The error handling needs work, bugs are lurking, | |
1018 | etc... | |
1019 | ||
1020 | dtc basically takes a device-tree in a given format and outputs a | |
1021 | device-tree in another format. The currently supported formats are: | |
1022 | ||
1023 | Input formats: | |
1024 | ------------- | |
1025 | ||
1026 | - "dtb": "blob" format, that is a flattened device-tree block | |
1027 | with | |
1028 | header all in a binary blob. | |
1029 | - "dts": "source" format. This is a text file containing a | |
1030 | "source" for a device-tree. The format is defined later in this | |
1031 | chapter. | |
1032 | - "fs" format. This is a representation equivalent to the | |
1033 | output of /proc/device-tree, that is nodes are directories and | |
1034 | properties are files | |
1035 | ||
1036 | Output formats: | |
1037 | --------------- | |
1038 | ||
1039 | - "dtb": "blob" format | |
1040 | - "dts": "source" format | |
1041 | - "asm": assembly language file. This is a file that can be | |
1042 | sourced by gas to generate a device-tree "blob". That file can | |
1043 | then simply be added to your Makefile. Additionally, the | |
6c28f2c0 | 1044 | assembly file exports some symbols that can be used. |
c125a183 DG |
1045 | |
1046 | ||
1047 | The syntax of the dtc tool is | |
1048 | ||
1049 | dtc [-I <input-format>] [-O <output-format>] | |
1050 | [-o output-filename] [-V output_version] input_filename | |
1051 | ||
1052 | ||
5dd60166 | 1053 | The "output_version" defines what version of the "blob" format will be |
c125a183 DG |
1054 | generated. Supported versions are 1,2,3 and 16. The default is |
1055 | currently version 3 but that may change in the future to version 16. | |
1056 | ||
1057 | Additionally, dtc performs various sanity checks on the tree, like the | |
6c28f2c0 | 1058 | uniqueness of linux, phandle properties, validity of strings, etc... |
c125a183 DG |
1059 | |
1060 | The format of the .dts "source" file is "C" like, supports C and C++ | |
6c28f2c0 | 1061 | style comments. |
c125a183 DG |
1062 | |
1063 | / { | |
1064 | } | |
1065 | ||
1066 | The above is the "device-tree" definition. It's the only statement | |
1067 | supported currently at the toplevel. | |
1068 | ||
1069 | / { | |
1070 | property1 = "string_value"; /* define a property containing a 0 | |
1071 | * terminated string | |
1072 | */ | |
1073 | ||
1074 | property2 = <1234abcd>; /* define a property containing a | |
5dd60166 | 1075 | * numerical 32-bit value (hexadecimal) |
c125a183 DG |
1076 | */ |
1077 | ||
1078 | property3 = <12345678 12345678 deadbeef>; | |
1079 | /* define a property containing 3 | |
5dd60166 | 1080 | * numerical 32-bit values (cells) in |
c125a183 DG |
1081 | * hexadecimal |
1082 | */ | |
1083 | property4 = [0a 0b 0c 0d de ea ad be ef]; | |
1084 | /* define a property whose content is | |
1085 | * an arbitrary array of bytes | |
1086 | */ | |
1087 | ||
1088 | childnode@addresss { /* define a child node named "childnode" | |
1089 | * whose unit name is "childnode at | |
1090 | * address" | |
1091 | */ | |
1092 | ||
1093 | childprop = "hello\n"; /* define a property "childprop" of | |
1094 | * childnode (in this case, a string) | |
1095 | */ | |
1096 | }; | |
1097 | }; | |
1098 | ||
1099 | Nodes can contain other nodes etc... thus defining the hierarchical | |
1100 | structure of the tree. | |
1101 | ||
1102 | Strings support common escape sequences from C: "\n", "\t", "\r", | |
1103 | "\(octal value)", "\x(hex value)". | |
1104 | ||
1105 | It is also suggested that you pipe your source file through cpp (gcc | |
1106 | preprocessor) so you can use #include's, #define for constants, etc... | |
1107 | ||
1108 | Finally, various options are planned but not yet implemented, like | |
1109 | automatic generation of phandles, labels (exported to the asm file so | |
1110 | you can point to a property content and change it easily from whatever | |
1111 | you link the device-tree with), label or path instead of numeric value | |
1112 | in some cells to "point" to a node (replaced by a phandle at compile | |
1113 | time), export of reserve map address to the asm file, ability to | |
1114 | specify reserve map content at compile time, etc... | |
1115 | ||
1116 | We may provide a .h include file with common definitions of that | |
1117 | proves useful for some properties (like building PCI properties or | |
1118 | interrupt maps) though it may be better to add a notion of struct | |
1119 | definitions to the compiler... | |
1120 | ||
1121 | ||
1122 | V - Recommendations for a bootloader | |
1123 | ==================================== | |
1124 | ||
1125 | ||
1126 | Here are some various ideas/recommendations that have been proposed | |
1127 | while all this has been defined and implemented. | |
1128 | ||
1129 | - The bootloader may want to be able to use the device-tree itself | |
1130 | and may want to manipulate it (to add/edit some properties, | |
1131 | like physical memory size or kernel arguments). At this point, 2 | |
1132 | choices can be made. Either the bootloader works directly on the | |
1133 | flattened format, or the bootloader has its own internal tree | |
1134 | representation with pointers (similar to the kernel one) and | |
1135 | re-flattens the tree when booting the kernel. The former is a bit | |
1136 | more difficult to edit/modify, the later requires probably a bit | |
1137 | more code to handle the tree structure. Note that the structure | |
1138 | format has been designed so it's relatively easy to "insert" | |
1139 | properties or nodes or delete them by just memmoving things | |
1140 | around. It contains no internal offsets or pointers for this | |
1141 | purpose. | |
1142 | ||
d6bc8ac9 | 1143 | - An example of code for iterating nodes & retrieving properties |
c125a183 DG |
1144 | directly from the flattened tree format can be found in the kernel |
1145 | file arch/ppc64/kernel/prom.c, look at scan_flat_dt() function, | |
d6bc8ac9 | 1146 | its usage in early_init_devtree(), and the corresponding various |
c125a183 DG |
1147 | early_init_dt_scan_*() callbacks. That code can be re-used in a |
1148 | GPL bootloader, and as the author of that code, I would be happy | |
5dd60166 | 1149 | to discuss possible free licensing to any vendor who wishes to |
c125a183 DG |
1150 | integrate all or part of this code into a non-GPL bootloader. |
1151 | ||
1152 | ||
1153 | ||
1154 | VI - System-on-a-chip devices and nodes | |
1155 | ======================================= | |
1156 | ||
1157 | Many companies are now starting to develop system-on-a-chip | |
5dd60166 | 1158 | processors, where the processor core (CPU) and many peripheral devices |
c125a183 DG |
1159 | exist on a single piece of silicon. For these SOCs, an SOC node |
1160 | should be used that defines child nodes for the devices that make | |
1161 | up the SOC. While platforms are not required to use this model in | |
1162 | order to boot the kernel, it is highly encouraged that all SOC | |
1163 | implementations define as complete a flat-device-tree as possible to | |
1164 | describe the devices on the SOC. This will allow for the | |
1165 | genericization of much of the kernel code. | |
1166 | ||
1167 | ||
1168 | 1) Defining child nodes of an SOC | |
1169 | --------------------------------- | |
1170 | ||
1171 | Each device that is part of an SOC may have its own node entry inside | |
1172 | the SOC node. For each device that is included in the SOC, the unit | |
1173 | address property represents the address offset for this device's | |
1174 | memory-mapped registers in the parent's address space. The parent's | |
1175 | address space is defined by the "ranges" property in the top-level soc | |
1176 | node. The "reg" property for each node that exists directly under the | |
1177 | SOC node should contain the address mapping from the child address space | |
1178 | to the parent SOC address space and the size of the device's | |
1179 | memory-mapped register file. | |
1180 | ||
1181 | For many devices that may exist inside an SOC, there are predefined | |
1182 | specifications for the format of the device tree node. All SOC child | |
1183 | nodes should follow these specifications, except where noted in this | |
1184 | document. | |
1185 | ||
1186 | See appendix A for an example partial SOC node definition for the | |
1187 | MPC8540. | |
1188 | ||
1189 | ||
27565903 | 1190 | 2) Representing devices without a current OF specification |
c125a183 DG |
1191 | ---------------------------------------------------------- |
1192 | ||
1193 | Currently, there are many devices on SOCs that do not have a standard | |
1194 | representation pre-defined as part of the open firmware | |
1195 | specifications, mainly because the boards that contain these SOCs are | |
1196 | not currently booted using open firmware. This section contains | |
1197 | descriptions for the SOC devices for which new nodes have been | |
1198 | defined; this list will expand as more and more SOC-containing | |
1199 | platforms are moved over to use the flattened-device-tree model. | |
1200 | ||
1201 | a) MDIO IO device | |
1202 | ||
1203 | The MDIO is a bus to which the PHY devices are connected. For each | |
1204 | device that exists on this bus, a child node should be created. See | |
1205 | the definition of the PHY node below for an example of how to define | |
1206 | a PHY. | |
1207 | ||
1208 | Required properties: | |
1209 | - reg : Offset and length of the register set for the device | |
1210 | - device_type : Should be "mdio" | |
1211 | - compatible : Should define the compatible device type for the | |
1212 | mdio. Currently, this is most likely to be "gianfar" | |
1213 | ||
1214 | Example: | |
1215 | ||
1216 | mdio@24520 { | |
1217 | reg = <24520 20>; | |
7d4b95ae BB |
1218 | device_type = "mdio"; |
1219 | compatible = "gianfar"; | |
c125a183 DG |
1220 | |
1221 | ethernet-phy@0 { | |
1222 | ...... | |
1223 | }; | |
1224 | }; | |
1225 | ||
1226 | ||
1227 | b) Gianfar-compatible ethernet nodes | |
1228 | ||
1229 | Required properties: | |
1230 | ||
1231 | - device_type : Should be "network" | |
1232 | - model : Model of the device. Can be "TSEC", "eTSEC", or "FEC" | |
1233 | - compatible : Should be "gianfar" | |
1234 | - reg : Offset and length of the register set for the device | |
f583165f | 1235 | - mac-address : List of bytes representing the ethernet address of |
c125a183 DG |
1236 | this controller |
1237 | - interrupts : <a b> where a is the interrupt number and b is a | |
1238 | field that represents an encoding of the sense and level | |
1239 | information for the interrupt. This should be encoded based on | |
1240 | the information in section 2) depending on the type of interrupt | |
1241 | controller you have. | |
1242 | - interrupt-parent : the phandle for the interrupt controller that | |
1243 | services interrupts for this device. | |
1244 | - phy-handle : The phandle for the PHY connected to this ethernet | |
1245 | controller. | |
1246 | ||
e0a2f28b SW |
1247 | Recommended properties: |
1248 | ||
1249 | - linux,network-index : This is the intended "index" of this | |
1250 | network device. This is used by the bootwrapper to interpret | |
1251 | MAC addresses passed by the firmware when no information other | |
1252 | than indices is available to associate an address with a device. | |
cc65185d AF |
1253 | - phy-connection-type : a string naming the controller/PHY interface type, |
1254 | i.e., "mii" (default), "rmii", "gmii", "rgmii", "rgmii-id", "sgmii", | |
1255 | "tbi", or "rtbi". This property is only really needed if the connection | |
1256 | is of type "rgmii-id", as all other connection types are detected by | |
1257 | hardware. | |
1258 | ||
e0a2f28b | 1259 | |
c125a183 DG |
1260 | Example: |
1261 | ||
1262 | ethernet@24000 { | |
1263 | #size-cells = <0>; | |
1264 | device_type = "network"; | |
1265 | model = "TSEC"; | |
1266 | compatible = "gianfar"; | |
1267 | reg = <24000 1000>; | |
f583165f | 1268 | mac-address = [ 00 E0 0C 00 73 00 ]; |
c125a183 DG |
1269 | interrupts = <d 3 e 3 12 3>; |
1270 | interrupt-parent = <40000>; | |
1271 | phy-handle = <2452000> | |
1272 | }; | |
1273 | ||
1274 | ||
1275 | ||
1276 | c) PHY nodes | |
1277 | ||
1278 | Required properties: | |
1279 | ||
1280 | - device_type : Should be "ethernet-phy" | |
1281 | - interrupts : <a b> where a is the interrupt number and b is a | |
1282 | field that represents an encoding of the sense and level | |
1283 | information for the interrupt. This should be encoded based on | |
1284 | the information in section 2) depending on the type of interrupt | |
1285 | controller you have. | |
1286 | - interrupt-parent : the phandle for the interrupt controller that | |
1287 | services interrupts for this device. | |
1288 | - reg : The ID number for the phy, usually a small integer | |
1289 | - linux,phandle : phandle for this node; likely referenced by an | |
1290 | ethernet controller node. | |
1291 | ||
1292 | ||
1293 | Example: | |
1294 | ||
1295 | ethernet-phy@0 { | |
1296 | linux,phandle = <2452000> | |
1297 | interrupt-parent = <40000>; | |
1298 | interrupts = <35 1>; | |
1299 | reg = <0>; | |
1300 | device_type = "ethernet-phy"; | |
1301 | }; | |
1302 | ||
1303 | ||
1304 | d) Interrupt controllers | |
1305 | ||
1306 | Some SOC devices contain interrupt controllers that are different | |
1307 | from the standard Open PIC specification. The SOC device nodes for | |
1308 | these types of controllers should be specified just like a standard | |
1309 | OpenPIC controller. Sense and level information should be encoded | |
1310 | as specified in section 2) of this chapter for each device that | |
1311 | specifies an interrupt. | |
1312 | ||
1313 | Example : | |
1314 | ||
1315 | pic@40000 { | |
1316 | linux,phandle = <40000>; | |
1317 | clock-frequency = <0>; | |
1318 | interrupt-controller; | |
1319 | #address-cells = <0>; | |
1320 | reg = <40000 40000>; | |
1321 | built-in; | |
1322 | compatible = "chrp,open-pic"; | |
1323 | device_type = "open-pic"; | |
1324 | big-endian; | |
1325 | }; | |
1326 | ||
1327 | ||
1328 | e) I2C | |
1329 | ||
1330 | Required properties : | |
1331 | ||
1332 | - device_type : Should be "i2c" | |
1333 | - reg : Offset and length of the register set for the device | |
1334 | ||
1335 | Recommended properties : | |
1336 | ||
1337 | - compatible : Should be "fsl-i2c" for parts compatible with | |
1338 | Freescale I2C specifications. | |
1339 | - interrupts : <a b> where a is the interrupt number and b is a | |
1340 | field that represents an encoding of the sense and level | |
1341 | information for the interrupt. This should be encoded based on | |
1342 | the information in section 2) depending on the type of interrupt | |
1343 | controller you have. | |
1344 | - interrupt-parent : the phandle for the interrupt controller that | |
1345 | services interrupts for this device. | |
1346 | - dfsrr : boolean; if defined, indicates that this I2C device has | |
1347 | a digital filter sampling rate register | |
1348 | - fsl5200-clocking : boolean; if defined, indicated that this device | |
1349 | uses the FSL 5200 clocking mechanism. | |
1350 | ||
1351 | Example : | |
1352 | ||
1353 | i2c@3000 { | |
1354 | interrupt-parent = <40000>; | |
1355 | interrupts = <1b 3>; | |
1356 | reg = <3000 18>; | |
1357 | device_type = "i2c"; | |
1358 | compatible = "fsl-i2c"; | |
1359 | dfsrr; | |
1360 | }; | |
1361 | ||
1362 | ||
ad71f123 BB |
1363 | f) Freescale SOC USB controllers |
1364 | ||
1365 | The device node for a USB controller that is part of a Freescale | |
1366 | SOC is as described in the document "Open Firmware Recommended | |
1367 | Practice : Universal Serial Bus" with the following modifications | |
1368 | and additions : | |
1369 | ||
1370 | Required properties : | |
5dd60166 DP |
1371 | - compatible : Should be "fsl-usb2-mph" for multi port host USB |
1372 | controllers, or "fsl-usb2-dr" for dual role USB controllers | |
1373 | - phy_type : For multi port host USB controllers, should be one of | |
1374 | "ulpi", or "serial". For dual role USB controllers, should be | |
ad71f123 BB |
1375 | one of "ulpi", "utmi", "utmi_wide", or "serial". |
1376 | - reg : Offset and length of the register set for the device | |
1377 | - port0 : boolean; if defined, indicates port0 is connected for | |
1378 | fsl-usb2-mph compatible controllers. Either this property or | |
1379 | "port1" (or both) must be defined for "fsl-usb2-mph" compatible | |
1380 | controllers. | |
1381 | - port1 : boolean; if defined, indicates port1 is connected for | |
1382 | fsl-usb2-mph compatible controllers. Either this property or | |
1383 | "port0" (or both) must be defined for "fsl-usb2-mph" compatible | |
1384 | controllers. | |
ea5b7a61 LY |
1385 | - dr_mode : indicates the working mode for "fsl-usb2-dr" compatible |
1386 | controllers. Can be "host", "peripheral", or "otg". Default to | |
1387 | "host" if not defined for backward compatibility. | |
ad71f123 BB |
1388 | |
1389 | Recommended properties : | |
1390 | - interrupts : <a b> where a is the interrupt number and b is a | |
1391 | field that represents an encoding of the sense and level | |
1392 | information for the interrupt. This should be encoded based on | |
1393 | the information in section 2) depending on the type of interrupt | |
1394 | controller you have. | |
1395 | - interrupt-parent : the phandle for the interrupt controller that | |
1396 | services interrupts for this device. | |
1397 | ||
5dd60166 | 1398 | Example multi port host USB controller device node : |
ad71f123 BB |
1399 | usb@22000 { |
1400 | device_type = "usb"; | |
1401 | compatible = "fsl-usb2-mph"; | |
1402 | reg = <22000 1000>; | |
1403 | #address-cells = <1>; | |
1404 | #size-cells = <0>; | |
1405 | interrupt-parent = <700>; | |
1406 | interrupts = <27 1>; | |
1407 | phy_type = "ulpi"; | |
1408 | port0; | |
1409 | port1; | |
1410 | }; | |
1411 | ||
5dd60166 | 1412 | Example dual role USB controller device node : |
ad71f123 BB |
1413 | usb@23000 { |
1414 | device_type = "usb"; | |
1415 | compatible = "fsl-usb2-dr"; | |
1416 | reg = <23000 1000>; | |
1417 | #address-cells = <1>; | |
1418 | #size-cells = <0>; | |
1419 | interrupt-parent = <700>; | |
1420 | interrupts = <26 1>; | |
ea5b7a61 | 1421 | dr_mode = "otg"; |
ad71f123 BB |
1422 | phy = "ulpi"; |
1423 | }; | |
1424 | ||
1425 | ||
b88a0b1d KP |
1426 | g) Freescale SOC SEC Security Engines |
1427 | ||
1428 | Required properties: | |
1429 | ||
1430 | - device_type : Should be "crypto" | |
1431 | - model : Model of the device. Should be "SEC1" or "SEC2" | |
1432 | - compatible : Should be "talitos" | |
1433 | - reg : Offset and length of the register set for the device | |
1434 | - interrupts : <a b> where a is the interrupt number and b is a | |
1435 | field that represents an encoding of the sense and level | |
1436 | information for the interrupt. This should be encoded based on | |
1437 | the information in section 2) depending on the type of interrupt | |
1438 | controller you have. | |
1439 | - interrupt-parent : the phandle for the interrupt controller that | |
1440 | services interrupts for this device. | |
1441 | - num-channels : An integer representing the number of channels | |
1442 | available. | |
1443 | - channel-fifo-len : An integer representing the number of | |
1444 | descriptor pointers each channel fetch fifo can hold. | |
1445 | - exec-units-mask : The bitmask representing what execution units | |
5dd60166 | 1446 | (EUs) are available. It's a single 32-bit cell. EU information |
b88a0b1d KP |
1447 | should be encoded following the SEC's Descriptor Header Dword |
1448 | EU_SEL0 field documentation, i.e. as follows: | |
1449 | ||
1450 | bit 0 = reserved - should be 0 | |
1451 | bit 1 = set if SEC has the ARC4 EU (AFEU) | |
1452 | bit 2 = set if SEC has the DES/3DES EU (DEU) | |
1453 | bit 3 = set if SEC has the message digest EU (MDEU) | |
1454 | bit 4 = set if SEC has the random number generator EU (RNG) | |
1455 | bit 5 = set if SEC has the public key EU (PKEU) | |
1456 | bit 6 = set if SEC has the AES EU (AESU) | |
1457 | bit 7 = set if SEC has the Kasumi EU (KEU) | |
1458 | ||
1459 | bits 8 through 31 are reserved for future SEC EUs. | |
1460 | ||
1461 | - descriptor-types-mask : The bitmask representing what descriptors | |
5dd60166 | 1462 | are available. It's a single 32-bit cell. Descriptor type |
b88a0b1d KP |
1463 | information should be encoded following the SEC's Descriptor |
1464 | Header Dword DESC_TYPE field documentation, i.e. as follows: | |
1465 | ||
1466 | bit 0 = set if SEC supports the aesu_ctr_nonsnoop desc. type | |
1467 | bit 1 = set if SEC supports the ipsec_esp descriptor type | |
1468 | bit 2 = set if SEC supports the common_nonsnoop desc. type | |
1469 | bit 3 = set if SEC supports the 802.11i AES ccmp desc. type | |
1470 | bit 4 = set if SEC supports the hmac_snoop_no_afeu desc. type | |
1471 | bit 5 = set if SEC supports the srtp descriptor type | |
1472 | bit 6 = set if SEC supports the non_hmac_snoop_no_afeu desc.type | |
1473 | bit 7 = set if SEC supports the pkeu_assemble descriptor type | |
1474 | bit 8 = set if SEC supports the aesu_key_expand_output desc.type | |
1475 | bit 9 = set if SEC supports the pkeu_ptmul descriptor type | |
1476 | bit 10 = set if SEC supports the common_nonsnoop_afeu desc. type | |
1477 | bit 11 = set if SEC supports the pkeu_ptadd_dbl descriptor type | |
1478 | ||
1479 | ..and so on and so forth. | |
1480 | ||
1481 | Example: | |
1482 | ||
1483 | /* MPC8548E */ | |
1484 | crypto@30000 { | |
1485 | device_type = "crypto"; | |
1486 | model = "SEC2"; | |
1487 | compatible = "talitos"; | |
1488 | reg = <30000 10000>; | |
1489 | interrupts = <1d 3>; | |
1490 | interrupt-parent = <40000>; | |
1491 | num-channels = <4>; | |
cbdb54d3 | 1492 | channel-fifo-len = <18>; |
b88a0b1d | 1493 | exec-units-mask = <000000fe>; |
cbdb54d3 | 1494 | descriptor-types-mask = <012b0ebf>; |
b88a0b1d KP |
1495 | }; |
1496 | ||
9a1ab883 LY |
1497 | h) Board Control and Status (BCSR) |
1498 | ||
1499 | Required properties: | |
1500 | ||
1501 | - device_type : Should be "board-control" | |
1502 | - reg : Offset and length of the register set for the device | |
1503 | ||
1504 | Example: | |
1505 | ||
1506 | bcsr@f8000000 { | |
1507 | device_type = "board-control"; | |
1508 | reg = <f8000000 8000>; | |
1509 | }; | |
1510 | ||
1511 | i) Freescale QUICC Engine module (QE) | |
1512 | This represents qe module that is installed on PowerQUICC II Pro. | |
1513 | Hopefully it will merge backward compatibility with CPM/CPM2. | |
1514 | Basically, it is a bus of devices, that could act more or less | |
1515 | as a complete entity (UCC, USB etc ). All of them should be siblings on | |
1516 | the "root" qe node, using the common properties from there. | |
59c51591 | 1517 | The description below applies to the qe of MPC8360 and |
9a1ab883 LY |
1518 | more nodes and properties would be extended in the future. |
1519 | ||
1520 | i) Root QE device | |
1521 | ||
1522 | Required properties: | |
1523 | - device_type : should be "qe"; | |
1524 | - model : precise model of the QE, Can be "QE", "CPM", or "CPM2" | |
1525 | - reg : offset and length of the device registers. | |
1526 | - bus-frequency : the clock frequency for QUICC Engine. | |
1527 | ||
1528 | Recommended properties | |
1529 | - brg-frequency : the internal clock source frequency for baud-rate | |
1530 | generators in Hz. | |
1531 | ||
1532 | Example: | |
1533 | qe@e0100000 { | |
1534 | #address-cells = <1>; | |
1535 | #size-cells = <1>; | |
1536 | #interrupt-cells = <2>; | |
1537 | device_type = "qe"; | |
1538 | model = "QE"; | |
1539 | ranges = <0 e0100000 00100000>; | |
1540 | reg = <e0100000 480>; | |
1541 | brg-frequency = <0>; | |
1542 | bus-frequency = <179A7B00>; | |
1543 | } | |
1544 | ||
1545 | ||
1546 | ii) SPI (Serial Peripheral Interface) | |
1547 | ||
1548 | Required properties: | |
1549 | - device_type : should be "spi". | |
1550 | - compatible : should be "fsl_spi". | |
5dd60166 | 1551 | - mode : the SPI operation mode, it can be "cpu" or "qe". |
9a1ab883 LY |
1552 | - reg : Offset and length of the register set for the device |
1553 | - interrupts : <a b> where a is the interrupt number and b is a | |
1554 | field that represents an encoding of the sense and level | |
1555 | information for the interrupt. This should be encoded based on | |
1556 | the information in section 2) depending on the type of interrupt | |
1557 | controller you have. | |
1558 | - interrupt-parent : the phandle for the interrupt controller that | |
1559 | services interrupts for this device. | |
1560 | ||
1561 | Example: | |
1562 | spi@4c0 { | |
1563 | device_type = "spi"; | |
1564 | compatible = "fsl_spi"; | |
1565 | reg = <4c0 40>; | |
1566 | interrupts = <82 0>; | |
1567 | interrupt-parent = <700>; | |
1568 | mode = "cpu"; | |
1569 | }; | |
1570 | ||
1571 | ||
1572 | iii) USB (Universal Serial Bus Controller) | |
1573 | ||
1574 | Required properties: | |
1575 | - device_type : should be "usb". | |
1576 | - compatible : could be "qe_udc" or "fhci-hcd". | |
1577 | - mode : the could be "host" or "slave". | |
1578 | - reg : Offset and length of the register set for the device | |
1579 | - interrupts : <a b> where a is the interrupt number and b is a | |
1580 | field that represents an encoding of the sense and level | |
1581 | information for the interrupt. This should be encoded based on | |
1582 | the information in section 2) depending on the type of interrupt | |
1583 | controller you have. | |
1584 | - interrupt-parent : the phandle for the interrupt controller that | |
1585 | services interrupts for this device. | |
1586 | ||
1587 | Example(slave): | |
1588 | usb@6c0 { | |
1589 | device_type = "usb"; | |
1590 | compatible = "qe_udc"; | |
1591 | reg = <6c0 40>; | |
1592 | interrupts = <8b 0>; | |
1593 | interrupt-parent = <700>; | |
1594 | mode = "slave"; | |
1595 | }; | |
1596 | ||
1597 | ||
1598 | iv) UCC (Unified Communications Controllers) | |
1599 | ||
1600 | Required properties: | |
1601 | - device_type : should be "network", "hldc", "uart", "transparent" | |
1602 | "bisync" or "atm". | |
1603 | - compatible : could be "ucc_geth" or "fsl_atm" and so on. | |
1604 | - model : should be "UCC". | |
1605 | - device-id : the ucc number(1-8), corresponding to UCCx in UM. | |
1606 | - reg : Offset and length of the register set for the device | |
1607 | - interrupts : <a b> where a is the interrupt number and b is a | |
1608 | field that represents an encoding of the sense and level | |
1609 | information for the interrupt. This should be encoded based on | |
1610 | the information in section 2) depending on the type of interrupt | |
1611 | controller you have. | |
1612 | - interrupt-parent : the phandle for the interrupt controller that | |
1613 | services interrupts for this device. | |
1614 | - pio-handle : The phandle for the Parallel I/O port configuration. | |
1615 | - rx-clock : represents the UCC receive clock source. | |
1616 | 0x00 : clock source is disabled; | |
1617 | 0x1~0x10 : clock source is BRG1~BRG16 respectively; | |
1618 | 0x11~0x28: clock source is QE_CLK1~QE_CLK24 respectively. | |
1619 | - tx-clock: represents the UCC transmit clock source; | |
1620 | 0x00 : clock source is disabled; | |
1621 | 0x1~0x10 : clock source is BRG1~BRG16 respectively; | |
1622 | 0x11~0x28: clock source is QE_CLK1~QE_CLK24 respectively. | |
1623 | ||
1624 | Required properties for network device_type: | |
1625 | - mac-address : list of bytes representing the ethernet address. | |
1626 | - phy-handle : The phandle for the PHY connected to this controller. | |
1627 | ||
e0a2f28b SW |
1628 | Recommended properties: |
1629 | - linux,network-index : This is the intended "index" of this | |
1630 | network device. This is used by the bootwrapper to interpret | |
1631 | MAC addresses passed by the firmware when no information other | |
1632 | than indices is available to associate an address with a device. | |
60c1922c KP |
1633 | - phy-connection-type : a string naming the controller/PHY interface type, |
1634 | i.e., "mii" (default), "rmii", "gmii", "rgmii", "rgmii-id", "tbi", | |
1635 | or "rtbi". | |
e0a2f28b | 1636 | |
9a1ab883 LY |
1637 | Example: |
1638 | ucc@2000 { | |
1639 | device_type = "network"; | |
1640 | compatible = "ucc_geth"; | |
1641 | model = "UCC"; | |
1642 | device-id = <1>; | |
1643 | reg = <2000 200>; | |
1644 | interrupts = <a0 0>; | |
1645 | interrupt-parent = <700>; | |
1646 | mac-address = [ 00 04 9f 00 23 23 ]; | |
1647 | rx-clock = "none"; | |
1648 | tx-clock = "clk9"; | |
1649 | phy-handle = <212000>; | |
60c1922c | 1650 | phy-connection-type = "gmii"; |
9a1ab883 LY |
1651 | pio-handle = <140001>; |
1652 | }; | |
1653 | ||
1654 | ||
1655 | v) Parallel I/O Ports | |
1656 | ||
1657 | This node configures Parallel I/O ports for CPUs with QE support. | |
1658 | The node should reside in the "soc" node of the tree. For each | |
1659 | device that using parallel I/O ports, a child node should be created. | |
1660 | See the definition of the Pin configuration nodes below for more | |
1661 | information. | |
1662 | ||
1663 | Required properties: | |
1664 | - device_type : should be "par_io". | |
1665 | - reg : offset to the register set and its length. | |
1666 | - num-ports : number of Parallel I/O ports | |
1667 | ||
1668 | Example: | |
1669 | par_io@1400 { | |
1670 | reg = <1400 100>; | |
1671 | #address-cells = <1>; | |
1672 | #size-cells = <0>; | |
1673 | device_type = "par_io"; | |
1674 | num-ports = <7>; | |
1675 | ucc_pin@01 { | |
1676 | ...... | |
1677 | }; | |
1678 | ||
1679 | ||
1680 | vi) Pin configuration nodes | |
1681 | ||
1682 | Required properties: | |
1683 | - linux,phandle : phandle of this node; likely referenced by a QE | |
1684 | device. | |
1685 | - pio-map : array of pin configurations. Each pin is defined by 6 | |
1686 | integers. The six numbers are respectively: port, pin, dir, | |
1687 | open_drain, assignment, has_irq. | |
1688 | - port : port number of the pin; 0-6 represent port A-G in UM. | |
1689 | - pin : pin number in the port. | |
1690 | - dir : direction of the pin, should encode as follows: | |
1691 | ||
1692 | 0 = The pin is disabled | |
1693 | 1 = The pin is an output | |
1694 | 2 = The pin is an input | |
1695 | 3 = The pin is I/O | |
1696 | ||
1697 | - open_drain : indicates the pin is normal or wired-OR: | |
1698 | ||
1699 | 0 = The pin is actively driven as an output | |
1700 | 1 = The pin is an open-drain driver. As an output, the pin is | |
1701 | driven active-low, otherwise it is three-stated. | |
1702 | ||
1703 | - assignment : function number of the pin according to the Pin Assignment | |
1704 | tables in User Manual. Each pin can have up to 4 possible functions in | |
1705 | QE and two options for CPM. | |
a982ac06 | 1706 | - has_irq : indicates if the pin is used as source of external |
9a1ab883 LY |
1707 | interrupts. |
1708 | ||
1709 | Example: | |
1710 | ucc_pin@01 { | |
1711 | linux,phandle = <140001>; | |
1712 | pio-map = < | |
1713 | /* port pin dir open_drain assignment has_irq */ | |
1714 | 0 3 1 0 1 0 /* TxD0 */ | |
1715 | 0 4 1 0 1 0 /* TxD1 */ | |
1716 | 0 5 1 0 1 0 /* TxD2 */ | |
1717 | 0 6 1 0 1 0 /* TxD3 */ | |
1718 | 1 6 1 0 3 0 /* TxD4 */ | |
1719 | 1 7 1 0 1 0 /* TxD5 */ | |
1720 | 1 9 1 0 2 0 /* TxD6 */ | |
1721 | 1 a 1 0 2 0 /* TxD7 */ | |
1722 | 0 9 2 0 1 0 /* RxD0 */ | |
1723 | 0 a 2 0 1 0 /* RxD1 */ | |
1724 | 0 b 2 0 1 0 /* RxD2 */ | |
1725 | 0 c 2 0 1 0 /* RxD3 */ | |
1726 | 0 d 2 0 1 0 /* RxD4 */ | |
1727 | 1 1 2 0 2 0 /* RxD5 */ | |
1728 | 1 0 2 0 2 0 /* RxD6 */ | |
1729 | 1 4 2 0 2 0 /* RxD7 */ | |
1730 | 0 7 1 0 1 0 /* TX_EN */ | |
1731 | 0 8 1 0 1 0 /* TX_ER */ | |
1732 | 0 f 2 0 1 0 /* RX_DV */ | |
1733 | 0 10 2 0 1 0 /* RX_ER */ | |
1734 | 0 0 2 0 1 0 /* RX_CLK */ | |
1735 | 2 9 1 0 3 0 /* GTX_CLK - CLK10 */ | |
1736 | 2 8 2 0 1 0>; /* GTX125 - CLK9 */ | |
1737 | }; | |
1738 | ||
1739 | vii) Multi-User RAM (MURAM) | |
1740 | ||
1741 | Required properties: | |
1742 | - device_type : should be "muram". | |
1743 | - mode : the could be "host" or "slave". | |
1744 | - ranges : Should be defined as specified in 1) to describe the | |
1745 | translation of MURAM addresses. | |
1746 | - data-only : sub-node which defines the address area under MURAM | |
1747 | bus that can be allocated as data/parameter | |
1748 | ||
1749 | Example: | |
1750 | ||
1751 | muram@10000 { | |
1752 | device_type = "muram"; | |
1753 | ranges = <0 00010000 0000c000>; | |
1754 | ||
1755 | data-only@0{ | |
1756 | reg = <0 c000>; | |
1757 | }; | |
1758 | }; | |
b88a0b1d | 1759 | |
d30ac124 | 1760 | j) Flash chip nodes |
28f9ec34 VW |
1761 | |
1762 | Flash chips (Memory Technology Devices) are often used for solid state | |
1763 | file systems on embedded devices. | |
1764 | ||
1765 | Required properties: | |
1766 | ||
1767 | - device_type : has to be "rom" | |
173935f3 VW |
1768 | - compatible : Should specify what this flash device is compatible with. |
1769 | Currently, this is most likely to be "direct-mapped" (which | |
1770 | corresponds to the MTD physmap mapping driver). | |
1771 | - reg : Offset and length of the register set (or memory mapping) for | |
28f9ec34 | 1772 | the device. |
173935f3 VW |
1773 | - bank-width : Width of the flash data bus in bytes. Required |
1774 | for the NOR flashes (compatible == "direct-mapped" and others) ONLY. | |
28f9ec34 VW |
1775 | |
1776 | Recommended properties : | |
1777 | ||
28f9ec34 VW |
1778 | - partitions : Several pairs of 32-bit values where the first value is |
1779 | partition's offset from the start of the device and the second one is | |
1780 | partition size in bytes with LSB used to signify a read only | |
5dd60166 | 1781 | partition (so, the partition size should always be an even number). |
28f9ec34 VW |
1782 | - partition-names : The list of concatenated zero terminated strings |
1783 | representing the partition names. | |
173935f3 VW |
1784 | - probe-type : The type of probe which should be done for the chip |
1785 | (JEDEC vs CFI actually). Valid ONLY for NOR flashes. | |
28f9ec34 VW |
1786 | |
1787 | Example: | |
1788 | ||
1789 | flash@ff000000 { | |
1790 | device_type = "rom"; | |
1791 | compatible = "direct-mapped"; | |
173935f3 VW |
1792 | probe-type = "CFI"; |
1793 | reg = <ff000000 01000000>; | |
28f9ec34 VW |
1794 | bank-width = <4>; |
1795 | partitions = <00000000 00f80000 | |
1796 | 00f80000 00080001>; | |
1797 | partition-names = "fs\0firmware"; | |
1798 | }; | |
1799 | ||
3b824f85 RZ |
1800 | k) Global Utilities Block |
1801 | ||
1802 | The global utilities block controls power management, I/O device | |
1803 | enabling, power-on-reset configuration monitoring, general-purpose | |
1804 | I/O signal configuration, alternate function selection for multiplexed | |
1805 | signals, and clock control. | |
1806 | ||
1807 | Required properties: | |
1808 | ||
1809 | - compatible : Should define the compatible device type for | |
1810 | global-utilities. | |
1811 | - reg : Offset and length of the register set for the device. | |
1812 | ||
1813 | Recommended properties: | |
1814 | ||
1815 | - fsl,has-rstcr : Indicates that the global utilities register set | |
1816 | contains a functioning "reset control register" (i.e. the board | |
1817 | is wired to reset upon setting the HRESET_REQ bit in this register). | |
1818 | ||
1819 | Example: | |
1820 | ||
1821 | global-utilities@e0000 { /* global utilities block */ | |
1822 | compatible = "fsl,mpc8548-guts"; | |
1823 | reg = <e0000 1000>; | |
1824 | fsl,has-rstcr; | |
1825 | }; | |
1826 | ||
c125a183 DG |
1827 | More devices will be defined as this spec matures. |
1828 | ||
27565903 SY |
1829 | VII - Specifying interrupt information for devices |
1830 | =================================================== | |
1831 | ||
1832 | The device tree represents the busses and devices of a hardware | |
1833 | system in a form similar to the physical bus topology of the | |
1834 | hardware. | |
1835 | ||
1836 | In addition, a logical 'interrupt tree' exists which represents the | |
1837 | hierarchy and routing of interrupts in the hardware. | |
1838 | ||
1839 | The interrupt tree model is fully described in the | |
1840 | document "Open Firmware Recommended Practice: Interrupt | |
1841 | Mapping Version 0.9". The document is available at: | |
1842 | <http://playground.sun.com/1275/practice>. | |
1843 | ||
1844 | 1) interrupts property | |
1845 | ---------------------- | |
1846 | ||
1847 | Devices that generate interrupts to a single interrupt controller | |
1848 | should use the conventional OF representation described in the | |
1849 | OF interrupt mapping documentation. | |
1850 | ||
1851 | Each device which generates interrupts must have an 'interrupt' | |
1852 | property. The interrupt property value is an arbitrary number of | |
1853 | of 'interrupt specifier' values which describe the interrupt or | |
1854 | interrupts for the device. | |
1855 | ||
1856 | The encoding of an interrupt specifier is determined by the | |
1857 | interrupt domain in which the device is located in the | |
1858 | interrupt tree. The root of an interrupt domain specifies in | |
1859 | its #interrupt-cells property the number of 32-bit cells | |
1860 | required to encode an interrupt specifier. See the OF interrupt | |
1861 | mapping documentation for a detailed description of domains. | |
1862 | ||
1863 | For example, the binding for the OpenPIC interrupt controller | |
1864 | specifies an #interrupt-cells value of 2 to encode the interrupt | |
1865 | number and level/sense information. All interrupt children in an | |
1866 | OpenPIC interrupt domain use 2 cells per interrupt in their interrupts | |
1867 | property. | |
1868 | ||
1869 | The PCI bus binding specifies a #interrupt-cell value of 1 to encode | |
1870 | which interrupt pin (INTA,INTB,INTC,INTD) is used. | |
1871 | ||
1872 | 2) interrupt-parent property | |
1873 | ---------------------------- | |
1874 | ||
1875 | The interrupt-parent property is specified to define an explicit | |
1876 | link between a device node and its interrupt parent in | |
1877 | the interrupt tree. The value of interrupt-parent is the | |
1878 | phandle of the parent node. | |
1879 | ||
1880 | If the interrupt-parent property is not defined for a node, it's | |
1881 | interrupt parent is assumed to be an ancestor in the node's | |
1882 | _device tree_ hierarchy. | |
1883 | ||
1884 | 3) OpenPIC Interrupt Controllers | |
1885 | -------------------------------- | |
1886 | ||
1887 | OpenPIC interrupt controllers require 2 cells to encode | |
1888 | interrupt information. The first cell defines the interrupt | |
1889 | number. The second cell defines the sense and level | |
1890 | information. | |
1891 | ||
1892 | Sense and level information should be encoded as follows: | |
1893 | ||
1894 | 0 = low to high edge sensitive type enabled | |
1895 | 1 = active low level sensitive type enabled | |
1896 | 2 = active high level sensitive type enabled | |
1897 | 3 = high to low edge sensitive type enabled | |
1898 | ||
1899 | 4) ISA Interrupt Controllers | |
1900 | ---------------------------- | |
1901 | ||
1902 | ISA PIC interrupt controllers require 2 cells to encode | |
1903 | interrupt information. The first cell defines the interrupt | |
1904 | number. The second cell defines the sense and level | |
1905 | information. | |
1906 | ||
1907 | ISA PIC interrupt controllers should adhere to the ISA PIC | |
1908 | encodings listed below: | |
1909 | ||
1910 | 0 = active low level sensitive type enabled | |
1911 | 1 = active high level sensitive type enabled | |
1912 | 2 = high to low edge sensitive type enabled | |
1913 | 3 = low to high edge sensitive type enabled | |
1914 | ||
c125a183 DG |
1915 | |
1916 | Appendix A - Sample SOC node for MPC8540 | |
1917 | ======================================== | |
1918 | ||
1919 | Note that the #address-cells and #size-cells for the SoC node | |
1920 | in this example have been explicitly listed; these are likely | |
1921 | not necessary as they are usually the same as the root node. | |
1922 | ||
1923 | soc8540@e0000000 { | |
1924 | #address-cells = <1>; | |
1925 | #size-cells = <1>; | |
1926 | #interrupt-cells = <2>; | |
1927 | device_type = "soc"; | |
1928 | ranges = <00000000 e0000000 00100000> | |
1929 | reg = <e0000000 00003000>; | |
7d4b95ae | 1930 | bus-frequency = <0>; |
c125a183 DG |
1931 | |
1932 | mdio@24520 { | |
1933 | reg = <24520 20>; | |
1934 | device_type = "mdio"; | |
1935 | compatible = "gianfar"; | |
1936 | ||
1937 | ethernet-phy@0 { | |
1938 | linux,phandle = <2452000> | |
1939 | interrupt-parent = <40000>; | |
1940 | interrupts = <35 1>; | |
1941 | reg = <0>; | |
1942 | device_type = "ethernet-phy"; | |
1943 | }; | |
1944 | ||
1945 | ethernet-phy@1 { | |
1946 | linux,phandle = <2452001> | |
1947 | interrupt-parent = <40000>; | |
1948 | interrupts = <35 1>; | |
1949 | reg = <1>; | |
1950 | device_type = "ethernet-phy"; | |
1951 | }; | |
1952 | ||
1953 | ethernet-phy@3 { | |
1954 | linux,phandle = <2452002> | |
1955 | interrupt-parent = <40000>; | |
1956 | interrupts = <35 1>; | |
1957 | reg = <3>; | |
1958 | device_type = "ethernet-phy"; | |
1959 | }; | |
1960 | ||
1961 | }; | |
1962 | ||
1963 | ethernet@24000 { | |
1964 | #size-cells = <0>; | |
1965 | device_type = "network"; | |
1966 | model = "TSEC"; | |
1967 | compatible = "gianfar"; | |
1968 | reg = <24000 1000>; | |
f583165f | 1969 | mac-address = [ 00 E0 0C 00 73 00 ]; |
c125a183 DG |
1970 | interrupts = <d 3 e 3 12 3>; |
1971 | interrupt-parent = <40000>; | |
1972 | phy-handle = <2452000>; | |
1973 | }; | |
1974 | ||
1975 | ethernet@25000 { | |
1976 | #address-cells = <1>; | |
1977 | #size-cells = <0>; | |
1978 | device_type = "network"; | |
1979 | model = "TSEC"; | |
1980 | compatible = "gianfar"; | |
1981 | reg = <25000 1000>; | |
f583165f | 1982 | mac-address = [ 00 E0 0C 00 73 01 ]; |
c125a183 DG |
1983 | interrupts = <13 3 14 3 18 3>; |
1984 | interrupt-parent = <40000>; | |
1985 | phy-handle = <2452001>; | |
1986 | }; | |
1987 | ||
1988 | ethernet@26000 { | |
1989 | #address-cells = <1>; | |
1990 | #size-cells = <0>; | |
1991 | device_type = "network"; | |
1992 | model = "FEC"; | |
1993 | compatible = "gianfar"; | |
1994 | reg = <26000 1000>; | |
f583165f | 1995 | mac-address = [ 00 E0 0C 00 73 02 ]; |
c125a183 DG |
1996 | interrupts = <19 3>; |
1997 | interrupt-parent = <40000>; | |
1998 | phy-handle = <2452002>; | |
1999 | }; | |
2000 | ||
2001 | serial@4500 { | |
2002 | device_type = "serial"; | |
2003 | compatible = "ns16550"; | |
2004 | reg = <4500 100>; | |
2005 | clock-frequency = <0>; | |
2006 | interrupts = <1a 3>; | |
2007 | interrupt-parent = <40000>; | |
2008 | }; | |
2009 | ||
2010 | pic@40000 { | |
2011 | linux,phandle = <40000>; | |
2012 | clock-frequency = <0>; | |
2013 | interrupt-controller; | |
2014 | #address-cells = <0>; | |
2015 | reg = <40000 40000>; | |
2016 | built-in; | |
2017 | compatible = "chrp,open-pic"; | |
2018 | device_type = "open-pic"; | |
2019 | big-endian; | |
2020 | }; | |
2021 | ||
2022 | i2c@3000 { | |
2023 | interrupt-parent = <40000>; | |
2024 | interrupts = <1b 3>; | |
2025 | reg = <3000 18>; | |
2026 | device_type = "i2c"; | |
2027 | compatible = "fsl-i2c"; | |
2028 | dfsrr; | |
2029 | }; | |
2030 | ||
2031 | }; |