Rob Herring | 4418482 | 2020-10-08 09:24:20 -0500 | [diff] [blame] | 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, |
He Ying | f8b4277 | 2021-03-26 06:08:53 -0400 | [diff] [blame] | 97 | PPC_PMAC and PPC_MAPLE. The latter is probably a good |
Rob Herring | 4418482 | 2020-10-08 09:24:20 -0500 | [diff] [blame] | 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. |