0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 DeviceTree Booting
0004 ------------------
0005
0006 During the development of the Linux/ppc64 kernel, and more specifically, the
0007 addition of new platform types outside of the old IBM pSeries/iSeries pair, it
0008 was decided to enforce some strict rules regarding the kernel entry and
0009 bootloader <-> kernel interfaces, in order to avoid the degeneration that had
0010 become the ppc32 kernel entry point and the way a new platform should be added
0011 to the kernel. The legacy iSeries platform breaks those rules as it predates
0012 this scheme, but no new board support will be accepted in the main tree that
0013 doesn't follow them properly. In addition, since the advent of the arch/powerpc
0014 merged architecture for ppc32 and ppc64, new 32-bit platforms and 32-bit
0015 platforms which move into arch/powerpc will be required to use these rules as
0016 well.
0017
0018 The main requirement that will be defined in more detail below is the presence
0019 of a device-tree whose format is defined after Open Firmware specification.
0020 However, in order to make life easier to embedded board vendors, the kernel
0021 doesn't require the device-tree to represent every device in the system and only
0022 requires some nodes and properties to be present. For example, the kernel does
0023 not require you to create a node for every PCI device in the system. It is a
0024 requirement to have a node for PCI host bridges in order to provide interrupt
0025 routing information and memory/IO ranges, among others. It is also recommended
0026 to define nodes for on chip devices and other buses that don't specifically fit
0027 in an existing OF specification. This creates a great flexibility in the way the
0028 kernel can then probe those and match drivers to device, without having to hard
0029 code all sorts of tables. It also makes it more flexible for board vendors to do
0030 minor hardware upgrades without significantly impacting the kernel code or
0031 cluttering it with special cases.
0032
0033
0034 Entry point
0035 ~~~~~~~~~~~
0036
0037 There is one single entry point to the kernel, at the start
0038 of the kernel image. That entry point supports two calling
0039 conventions:
0040
0041 a) Boot from Open Firmware. If your firmware is compatible
0042 with Open Firmware (IEEE 1275) or provides an OF compatible
0043 client interface API (support for "interpret" callback of
0044 forth words isn't required), you can enter the kernel with:
0045
0046 r5 : OF callback pointer as defined by IEEE 1275
0047 bindings to powerpc. Only the 32-bit client interface
0048 is currently supported
0049
0050 r3, r4 : address & length of an initrd if any or 0
0051
0052 The MMU is either on or off; the kernel will run the
0053 trampoline located in arch/powerpc/kernel/prom_init.c to
0054 extract the device-tree and other information from open
0055 firmware and build a flattened device-tree as described
0056 in b). prom_init() will then re-enter the kernel using
0057 the second method. This trampoline code runs in the
0058 context of the firmware, which is supposed to handle all
0059 exceptions during that time.
0060
0061 b) Direct entry with a flattened device-tree block. This entry
0062 point is called by a) after the OF trampoline and can also be
0063 called directly by a bootloader that does not support the Open
0064 Firmware client interface. It is also used by "kexec" to
0065 implement "hot" booting of a new kernel from a previous
0066 running one. This method is what I will describe in more
0067 details in this document, as method a) is simply standard Open
0068 Firmware, and thus should be implemented according to the
0069 various standard documents defining it and its binding to the
0070 PowerPC platform. The entry point definition then becomes:
0071
0072 r3 : physical pointer to the device-tree block
0073 (defined in chapter II) in RAM
0074
0075 r4 : physical pointer to the kernel itself. This is
0076 used by the assembly code to properly disable the MMU
0077 in case you are entering the kernel with MMU enabled
0078 and a non-1:1 mapping.
0079
0080 r5 : NULL (as to differentiate with method a)
0081
0082 Note about SMP entry: Either your firmware puts your other
0083 CPUs in some sleep loop or spin loop in ROM where you can get
0084 them out via a soft reset or some other means, in which case
0085 you don't need to care, or you'll have to enter the kernel
0086 with all CPUs. The way to do that with method b) will be
0087 described in a later revision of this document.
0088
0089 Board supports (platforms) are not exclusive config options. An
0090 arbitrary set of board supports can be built in a single kernel
0091 image. The kernel will "know" what set of functions to use for a
0092 given platform based on the content of the device-tree. Thus, you
0093 should:
0094
0095 a) add your platform support as a _boolean_ option in
0096 arch/powerpc/Kconfig, following the example of PPC_PSERIES,
0097 PPC_PMAC and PPC_MAPLE. The latter is probably a good
0098 example of a board support to start from.
0099
0100 b) create your main platform file as
0101 "arch/powerpc/platforms/myplatform/myboard_setup.c" and add it
0102 to the Makefile under the condition of your ``CONFIG_``
0103 option. This file will define a structure of type "ppc_md"
0104 containing the various callbacks that the generic code will
0105 use to get to your platform specific code
0106
0107 A kernel image may support multiple platforms, but only if the
0108 platforms feature the same core architecture. A single kernel build
0109 cannot support both configurations with Book E and configurations
0110 with classic Powerpc architectures.
