booting.rst 5.5 KB

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