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