111 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3DeviceTree Booting4------------------5 6During the development of the Linux/ppc64 kernel, and more specifically, the7addition of new platform types outside of the old IBM pSeries/iSeries pair, it8was decided to enforce some strict rules regarding the kernel entry and9bootloader <-> kernel interfaces, in order to avoid the degeneration that had10become the ppc32 kernel entry point and the way a new platform should be added11to the kernel. The legacy iSeries platform breaks those rules as it predates12this scheme, but no new board support will be accepted in the main tree that13doesn't follow them properly. In addition, since the advent of the arch/powerpc14merged architecture for ppc32 and ppc64, new 32-bit platforms and 32-bit15platforms which move into arch/powerpc will be required to use these rules as16well.17 18The main requirement that will be defined in more detail below is the presence19of a device-tree whose format is defined after Open Firmware specification.20However, in order to make life easier to embedded board vendors, the kernel21doesn't require the device-tree to represent every device in the system and only22requires some nodes and properties to be present. For example, the kernel does23not require you to create a node for every PCI device in the system. It is a24requirement to have a node for PCI host bridges in order to provide interrupt25routing information and memory/IO ranges, among others. It is also recommended26to define nodes for on chip devices and other buses that don't specifically fit27in an existing OF specification. This creates a great flexibility in the way the28kernel can then probe those and match drivers to device, without having to hard29code all sorts of tables. It also makes it more flexible for board vendors to do30minor hardware upgrades without significantly impacting the kernel code or31cluttering it with special cases.32 33 34Entry point35~~~~~~~~~~~36 37There is one single entry point to the kernel, at the start38of the kernel image. That entry point supports two calling39conventions:40 41 a) Boot from Open Firmware. If your firmware is compatible42 with Open Firmware (IEEE 1275) or provides an OF compatible43 client interface API (support for "interpret" callback of44 forth words isn't required), you can enter the kernel with:45 46 r5 : OF callback pointer as defined by IEEE 127547 bindings to powerpc. Only the 32-bit client interface48 is currently supported49 50 r3, r4 : address & length of an initrd if any or 051 52 The MMU is either on or off; the kernel will run the53 trampoline located in arch/powerpc/kernel/prom_init.c to54 extract the device-tree and other information from open55 firmware and build a flattened device-tree as described56 in b). prom_init() will then re-enter the kernel using57 the second method. This trampoline code runs in the58 context of the firmware, which is supposed to handle all59 exceptions during that time.60 61 b) Direct entry with a flattened device-tree block. This entry62 point is called by a) after the OF trampoline and can also be63 called directly by a bootloader that does not support the Open64 Firmware client interface. It is also used by "kexec" to65 implement "hot" booting of a new kernel from a previous66 running one. This method is what I will describe in more67 details in this document, as method a) is simply standard Open68 Firmware, and thus should be implemented according to the69 various standard documents defining it and its binding to the70 PowerPC platform. The entry point definition then becomes:71 72 r3 : physical pointer to the device-tree block73 (defined in chapter II) in RAM74 75 r4 : physical pointer to the kernel itself. This is76 used by the assembly code to properly disable the MMU77 in case you are entering the kernel with MMU enabled78 and a non-1:1 mapping.79 80 r5 : NULL (as to differentiate with method a)81 82Note about SMP entry: Either your firmware puts your other83CPUs in some sleep loop or spin loop in ROM where you can get84them out via a soft reset or some other means, in which case85you don't need to care, or you'll have to enter the kernel86with all CPUs. The way to do that with method b) will be87described in a later revision of this document.88 89Board supports (platforms) are not exclusive config options. An90arbitrary set of board supports can be built in a single kernel91image. The kernel will "know" what set of functions to use for a92given platform based on the content of the device-tree. Thus, you93should:94 95 a) add your platform support as a _boolean_ option in96 arch/powerpc/Kconfig, following the example of PPC_PSERIES,97 PPC_PMAC and PPC_MAPLE. The latter is probably a good98 example of a board support to start from.99 100 b) create your main platform file as101 "arch/powerpc/platforms/myplatform/myboard_setup.c" and add it102 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 will105 use to get to your platform specific code106 107A kernel image may support multiple platforms, but only if the108platforms feature the same core architecture. A single kernel build109cannot support both configurations with Book E and configurations110with classic Powerpc architectures.111