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