DeviceTree Booting | Linux 6.18.37

요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.

1. 요약·해설

원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.

요약과 해설

booting.rst:1-110

Open Firmware callback 경로와 flattened-DT 직접 경로를 하나의 kernel entry가 수용합니다. 새 platform은 device tree와 `ppc_md` callback으로 식별되어야 하며 Book E와 classic core를 한 build에 섞을 수 없습니다.

2. 영어 원문 전체

번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.

원문 전체 펼치기

1 .. SPDX-License-Identifier: GPL-2.0

3 DeviceTree Booting

4 ------------------

6 During the development of the Linux/ppc64 kernel, and more specifically, the

7 addition of new platform types outside of the old IBM pSeries/iSeries pair, it

8 was decided to enforce some strict rules regarding the kernel entry and

9 bootloader <-> kernel interfaces, in order to avoid the degeneration that had

10 become the ppc32 kernel entry point and the way a new platform should be added

11 to the kernel. The legacy iSeries platform breaks those rules as it predates

12 this scheme, but no new board support will be accepted in the main tree that

13 doesn't follow them properly. In addition, since the advent of the arch/powerpc

14 merged architecture for ppc32 and ppc64, new 32-bit platforms and 32-bit

15 platforms which move into arch/powerpc will be required to use these rules as

16 well.

18 The main requirement that will be defined in more detail below is the presence

19 of a device-tree whose format is defined after Open Firmware specification.

20 However, in order to make life easier to embedded board vendors, the kernel

21 doesn't require the device-tree to represent every device in the system and only

22 requires some nodes and properties to be present. For example, the kernel does

23 not require you to create a node for every PCI device in the system. It is a

24 requirement to have a node for PCI host bridges in order to provide interrupt

25 routing information and memory/IO ranges, among others. It is also recommended

26 to define nodes for on chip devices and other buses that don't specifically fit

27 in an existing OF specification. This creates a great flexibility in the way the

28 kernel can then probe those and match drivers to device, without having to hard

29 code all sorts of tables. It also makes it more flexible for board vendors to do

30 minor hardware upgrades without significantly impacting the kernel code or

31 cluttering it with special cases.

34 Entry point

35 ~~~~~~~~~~~

37 There is one single entry point to the kernel, at the start

38 of the kernel image. That entry point supports two calling

39 conventions:

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:

46 r5 : OF callback pointer as defined by IEEE 1275

47 bindings to powerpc. Only the 32-bit client interface

48 is currently supported

50 r3, r4 : address & length of an initrd if any or 0

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.

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:

72 r3 : physical pointer to the device-tree block

73 (defined in chapter II) in RAM

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.

80 r5 : NULL (as to differentiate with method a)

82 Note about SMP entry: Either your firmware puts your other

83 CPUs in some sleep loop or spin loop in ROM where you can get

84 them out via a soft reset or some other means, in which case

85 you don't need to care, or you'll have to enter the kernel

86 with all CPUs. The way to do that with method b) will be

87 described in a later revision of this document.

89 Board supports (platforms) are not exclusive config options. An

90 arbitrary set of board supports can be built in a single kernel

91 image. The kernel will "know" what set of functions to use for a

92 given platform based on the content of the device-tree. Thus, you

93 should:

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.

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

107 A kernel image may support multiple platforms, but only if the

108 platforms feature the same core architecture. A single kernel build

109 cannot support both configurations with Book E and configurations

110 with classic Powerpc architectures.

111

3. 한국어 전문 번역

영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.

DeviceTree boot contract의 배경

1-33

SPDX-License-Identifier는 GPL-2.0입니다. Linux/ppc64 kernel이 과거 IBM pSeries/iSeries 이외의 platform을 지원하게 되면서, ppc32의 kernel entry point와 새 platform 추가 방식이 무질서해졌던 문제를 반복하지 않도록 kernel entry와 bootloader-kernel interface에 엄격한 규칙을 두었습니다.

이 scheme보다 먼저 존재한 legacy iSeries platform은 규칙을 어기지만, 이를 제대로 따르지 않는 새 board support는 main tree에 받아들이지 않습니다. ppc32와 ppc64가 `arch/powerpc`로 통합된 뒤에는 새 32-bit platform과 `arch/powerpc`로 옮겨오는 32-bit platform도 같은 규칙을 따라야 합니다.

핵심 요구 사항은 Open Firmware specification을 바탕으로 한 형식의 device tree입니다. Embedded board vendor의 부담을 줄이기 위해 kernel은 device tree가 system의 모든 device를 표현하도록 요구하지 않고 일부 node와 property만 필수로 둡니다.

예를 들어 모든 PCI device node는 필요하지 않지만, interrupt routing과 memory/I/O range 등을 제공하려면 PCI host bridge node가 필요합니다. On-chip device와 기존 OF specification에 명확히 들어맞지 않는 bus도 node로 정의하는 것이 좋습니다. 그러면 kernel이 hard-coded table 없이 device를 probe하고 driver를 match할 수 있고, board vendor도 kernel code에 많은 special case를 넣지 않고 작은 hardware upgrade를 처리할 수 있습니다.

단일 kernel entry point

34-88

Kernel image 시작에는 entry point가 하나뿐이며 두 calling convention을 지원합니다.

방식	Register contract	동작
a) Open Firmware boot	`r5`: IEEE 1275 PowerPC binding의 OF callback pointer, `r3`,`r4`: initrd address와 length 또는 0	현재 32-bit client interface만 지원합니다. MMU는 켜져 있거나 꺼져 있을 수 있습니다.
b) Flattened device-tree 직접 진입	`r3`: RAM 안 device-tree block의 physical pointer, `r4`: kernel 자체의 physical pointer, `r5`: `NULL`	OF client interface가 없는 bootloader와 `kexec`가 사용합니다.

방식 a)에서는 kernel이 `arch/powerpc/kernel/prom_init.c`의 trampoline을 firmware context에서 실행합니다. Trampoline은 Open Firmware에서 device tree와 다른 정보를 추출해 flattened device tree를 만들고, `prom_init()`이 방식 b)로 kernel에 다시 진입합니다. 이 동안의 exception은 firmware가 처리해야 합니다.

방식 b)의 `r4`는 MMU가 enable되어 있고 mapping이 1:1이 아닐 때 assembly code가 MMU를 올바르게 disable하는 데 사용됩니다. `r5 = NULL`은 방식 a)와 구분하는 표지입니다.

SMP system에서 firmware가 다른 CPU를 ROM의 sleep/spin loop에 두고 soft reset 등으로 깨울 수 있다면 추가 조치가 필요 없습니다. 그렇지 않으면 모든 CPU로 kernel에 진입해야 합니다. 방식 b)에서 이를 수행하는 절차는 이 문서의 이후 revision에서 설명할 예정입니다.

PowerPC kernel 진입 경로

Open Firmware`r5` OF callback`prom_init()` trampolineFlattened DTKernel

Bootloader / kexec`r3` DTB, `r4` kernel, `r5` NULLKernel

두 calling convention은 최종적으로 같은 flattened device-tree entry로 합쳐집니다.

Multi-platform board support

89-110

Board 또는 platform support는 서로 배타적인 config option이 아닙니다. 한 kernel image에 임의의 board support 집합을 포함할 수 있고, kernel은 device tree 내용으로 현재 platform에서 사용할 function 집합을 선택합니다.

`arch/powerpc/Kconfig`에 platform support를 `_boolean_` option으로 추가합니다. `PPC_PSERIES`와 `PPC_PMAC`, 특히 후자를 시작 예제로 삼을 수 있습니다.
Main platform file을 `arch/powerpc/platforms/myplatform/myboard_setup.c`로 만들고 해당 `CONFIG_` option 조건 아래 Makefile에 추가합니다. 이 file은 generic code가 platform-specific code에 접근할 callback을 담은 `ppc_md` structure를 정의합니다.

Kernel image 하나가 여러 platform을 지원할 수는 있지만 core architecture가 같아야 합니다. 한 kernel build에서 Book E configuration과 classic PowerPC architecture configuration을 동시에 지원할 수 없습니다.