booting.rst

  1.. SPDX-License-Identifier: GPL-2.0
  2
  3DeviceTree Booting
  4------------------
  5
  6During the development of the Linux/ppc64 kernel, and more specifically, the
  7addition of new platform types outside of the old IBM pSeries/iSeries pair, it
  8was decided to enforce some strict rules regarding the kernel entry and
  9bootloader <-> kernel interfaces, in order to avoid the degeneration that had
 10become the ppc32 kernel entry point and the way a new platform should be added
 11to the kernel. The legacy iSeries platform breaks those rules as it predates
 12this scheme, but no new board support will be accepted in the main tree that
 13doesn't follow them properly.  In addition, since the advent of the arch/powerpc
 14merged architecture for ppc32 and ppc64, new 32-bit platforms and 32-bit
 15platforms which move into arch/powerpc will be required to use these rules as
 16well.
 17
 18The main requirement that will be defined in more detail below is the presence
 19of a device-tree whose format is defined after Open Firmware specification.
 20However, in order to make life easier to embedded board vendors, the kernel
 21doesn't require the device-tree to represent every device in the system and only
 22requires some nodes and properties to be present. For example, the kernel does
 23not require you to create a node for every PCI device in the system. It is a
 24requirement to have a node for PCI host bridges in order to provide interrupt
 25routing information and memory/IO ranges, among others. It is also recommended
 26to define nodes for on chip devices and other buses that don't specifically fit
 27in an existing OF specification. This creates a great flexibility in the way the
 28kernel can then probe those and match drivers to device, without having to hard
 29code all sorts of tables. It also makes it more flexible for board vendors to do
 30minor hardware upgrades without significantly impacting the kernel code or
 31cluttering it with special cases.
 32
 33
 34Entry point
 35~~~~~~~~~~~
 36
 37There is one single entry point to the kernel, at the start
 38of the kernel image. That entry point supports two calling
 39conventions:
 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
 82Note about SMP entry: Either your firmware puts your other
 83CPUs in some sleep loop or spin loop in ROM where you can get
 84them out via a soft reset or some other means, in which case
 85you don't need to care, or you'll have to enter the kernel
 86with all CPUs. The way to do that with method b) will be
 87described in a later revision of this document.
 88
 89Board supports (platforms) are not exclusive config options. An
 90arbitrary set of board supports can be built in a single kernel
 91image. The kernel will "know" what set of functions to use for a
 92given platform based on the content of the device-tree. Thus, you
 93should:
 94
 95        a) add your platform support as a _boolean_ option in
 96        arch/powerpc/Kconfig, following the example of PPC_PSERIES
 97        and PPC_PMAC. The latter is probably a good
 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
107A kernel image may support multiple platforms, but only if the
108platforms feature the same core architecture.  A single kernel build
109cannot support both configurations with Book E and configurations
110with classic Powerpc architectures.