Commit | Line | Data |
---|---|---|
44184828 RH |
1 | .. SPDX-License-Identifier: GPL-2.0 |
2 | ||
3 | DeviceTree Booting | |
4 | ------------------ | |
5 | ||
6 | During the development of the Linux/ppc64 kernel, and more specifically, the | |
7 | addition of new platform types outside of the old IBM pSeries/iSeries pair, it | |
8 | was decided to enforce some strict rules regarding the kernel entry and | |
9 | bootloader <-> kernel interfaces, in order to avoid the degeneration that had | |
10 | become the ppc32 kernel entry point and the way a new platform should be added | |
11 | to the kernel. The legacy iSeries platform breaks those rules as it predates | |
12 | this scheme, but no new board support will be accepted in the main tree that | |
13 | doesn't follow them properly. In addition, since the advent of the arch/powerpc | |
14 | merged architecture for ppc32 and ppc64, new 32-bit platforms and 32-bit | |
15 | platforms which move into arch/powerpc will be required to use these rules as | |
16 | well. | |
17 | ||
18 | The main requirement that will be defined in more detail below is the presence | |
19 | of a device-tree whose format is defined after Open Firmware specification. | |
20 | However, in order to make life easier to embedded board vendors, the kernel | |
21 | doesn't require the device-tree to represent every device in the system and only | |
22 | requires some nodes and properties to be present. For example, the kernel does | |
23 | not require you to create a node for every PCI device in the system. It is a | |
24 | requirement to have a node for PCI host bridges in order to provide interrupt | |
25 | routing information and memory/IO ranges, among others. It is also recommended | |
26 | to define nodes for on chip devices and other buses that don't specifically fit | |
27 | in an existing OF specification. This creates a great flexibility in the way the | |
28 | kernel can then probe those and match drivers to device, without having to hard | |
29 | code all sorts of tables. It also makes it more flexible for board vendors to do | |
30 | minor hardware upgrades without significantly impacting the kernel code or | |
31 | cluttering it with special cases. | |
32 | ||
33 | ||
34 | Entry point | |
35 | ~~~~~~~~~~~ | |
36 | ||
37 | There is one single entry point to the kernel, at the start | |
38 | of the kernel image. That entry point supports two calling | |
39 | conventions: | |
40 | ||
41 | a) Boot from Open Firmware. If your firmware is compatible | |
42 | with Open Firmware (IEEE 1275) or provides an OF compatible | |
43 | client interface API (support for "interpret" callback of | |
44 | forth words isn't required), you can enter the kernel with: | |
45 | ||
46 | r5 : OF callback pointer as defined by IEEE 1275 | |
47 | bindings to powerpc. Only the 32-bit client interface | |
48 | is currently supported | |
49 | ||
50 | r3, r4 : address & length of an initrd if any or 0 | |
51 | ||
52 | The MMU is either on or off; the kernel will run the | |
53 | trampoline located in arch/powerpc/kernel/prom_init.c to | |
54 | extract the device-tree and other information from open | |
55 | firmware and build a flattened device-tree as described | |
56 | in b). prom_init() will then re-enter the kernel using | |
57 | the second method. This trampoline code runs in the | |
58 | context of the firmware, which is supposed to handle all | |
59 | exceptions during that time. | |
60 | ||
61 | b) Direct entry with a flattened device-tree block. This entry | |
62 | point is called by a) after the OF trampoline and can also be | |
63 | called directly by a bootloader that does not support the Open | |
64 | Firmware client interface. It is also used by "kexec" to | |
65 | implement "hot" booting of a new kernel from a previous | |
66 | running one. This method is what I will describe in more | |
67 | details in this document, as method a) is simply standard Open | |
68 | Firmware, and thus should be implemented according to the | |
69 | various standard documents defining it and its binding to the | |
70 | PowerPC platform. The entry point definition then becomes: | |
71 | ||
72 | r3 : physical pointer to the device-tree block | |
73 | (defined in chapter II) in RAM | |
74 | ||
75 | r4 : physical pointer to the kernel itself. This is | |
76 | used by the assembly code to properly disable the MMU | |
77 | in case you are entering the kernel with MMU enabled | |
78 | and a non-1:1 mapping. | |
79 | ||
80 | r5 : NULL (as to differentiate with method a) | |
81 | ||
82 | Note about SMP entry: Either your firmware puts your other | |
83 | CPUs in some sleep loop or spin loop in ROM where you can get | |
84 | them out via a soft reset or some other means, in which case | |
85 | you don't need to care, or you'll have to enter the kernel | |
86 | with all CPUs. The way to do that with method b) will be | |
87 | described in a later revision of this document. | |
88 | ||
89 | Board supports (platforms) are not exclusive config options. An | |
90 | arbitrary set of board supports can be built in a single kernel | |
91 | image. The kernel will "know" what set of functions to use for a | |
92 | given platform based on the content of the device-tree. Thus, you | |
93 | should: | |
94 | ||
95 | a) add your platform support as a _boolean_ option in | |
96 | arch/powerpc/Kconfig, following the example of PPC_PSERIES, | |
f8b42777 | 97 | PPC_PMAC and PPC_MAPLE. The latter is probably a good |
44184828 RH |
98 | example of a board support to start from. |
99 | ||
100 | b) create your main platform file as | |
101 | "arch/powerpc/platforms/myplatform/myboard_setup.c" and add it | |
102 | to the Makefile under the condition of your ``CONFIG_`` | |
103 | option. This file will define a structure of type "ppc_md" | |
104 | containing the various callbacks that the generic code will | |
105 | use to get to your platform specific code | |
106 | ||
107 | A kernel image may support multiple platforms, but only if the | |
108 | platforms feature the same core architecture. A single kernel build | |
109 | cannot support both configurations with Book E and configurations | |
110 | with classic Powerpc architectures. |