Commit | Line | Data |
---|---|---|
4d2e26a3 | 1 | ======================== |
70bf0333 | 2 | The PowerPC boot wrapper |
4d2e26a3 MCC |
3 | ======================== |
4 | ||
70bf0333 GL |
5 | Copyright (C) Secret Lab Technologies Ltd. |
6 | ||
7 | PowerPC image targets compresses and wraps the kernel image (vmlinux) with | |
8 | a boot wrapper to make it usable by the system firmware. There is no | |
9 | standard PowerPC firmware interface, so the boot wrapper is designed to | |
10 | be adaptable for each kind of image that needs to be built. | |
11 | ||
12 | The boot wrapper can be found in the arch/powerpc/boot/ directory. The | |
13 | Makefile in that directory has targets for all the available image types. | |
14 | The different image types are used to support all of the various firmware | |
15 | interfaces found on PowerPC platforms. OpenFirmware is the most commonly | |
16 | used firmware type on general purpose PowerPC systems from Apple, IBM and | |
17 | others. U-Boot is typically found on embedded PowerPC hardware, but there | |
18 | are a handful of other firmware implementations which are also popular. Each | |
19 | firmware interface requires a different image format. | |
20 | ||
21 | The boot wrapper is built from the makefile in arch/powerpc/boot/Makefile and | |
22 | it uses the wrapper script (arch/powerpc/boot/wrapper) to generate target | |
23 | image. The details of the build system is discussed in the next section. | |
24 | Currently, the following image format targets exist: | |
25 | ||
4d2e26a3 | 26 | ==================== ======================================================== |
70bf0333 GL |
27 | cuImage.%: Backwards compatible uImage for older version of |
28 | U-Boot (for versions that don't understand the device | |
29 | tree). This image embeds a device tree blob inside | |
30 | the image. The boot wrapper, kernel and device tree | |
31 | are all embedded inside the U-Boot uImage file format | |
32 | with boot wrapper code that extracts data from the old | |
33 | bd_info structure and loads the data into the device | |
34 | tree before jumping into the kernel. | |
4d2e26a3 MCC |
35 | |
36 | Because of the series of #ifdefs found in the | |
70bf0333 GL |
37 | bd_info structure used in the old U-Boot interfaces, |
38 | cuImages are platform specific. Each specific | |
39 | U-Boot platform has a different platform init file | |
40 | which populates the embedded device tree with data | |
41 | from the platform specific bd_info file. The platform | |
42 | specific cuImage platform init code can be found in | |
4d2e26a3 | 43 | `arch/powerpc/boot/cuboot.*.c`. Selection of the correct |
70bf0333 GL |
44 | cuImage init code for a specific board can be found in |
45 | the wrapper structure. | |
4d2e26a3 | 46 | |
70bf0333 GL |
47 | dtbImage.%: Similar to zImage, except device tree blob is embedded |
48 | inside the image instead of provided by firmware. The | |
49 | output image file can be either an elf file or a flat | |
50 | binary depending on the platform. | |
4d2e26a3 MCC |
51 | |
52 | dtbImages are used on systems which do not have an | |
70bf0333 GL |
53 | interface for passing a device tree directly. |
54 | dtbImages are similar to simpleImages except that | |
55 | dtbImages have platform specific code for extracting | |
56 | data from the board firmware, but simpleImages do not | |
57 | talk to the firmware at all. | |
4d2e26a3 MCC |
58 | |
59 | PlayStation 3 support uses dtbImage. So do Embedded | |
70bf0333 GL |
60 | Planet boards using the PlanetCore firmware. Board |
61 | specific initialization code is typically found in a | |
62 | file named arch/powerpc/boot/<platform>.c; but this | |
63 | can be overridden by the wrapper script. | |
4d2e26a3 | 64 | |
70bf0333 GL |
65 | simpleImage.%: Firmware independent compressed image that does not |
66 | depend on any particular firmware interface and embeds | |
67 | a device tree blob. This image is a flat binary that | |
68 | can be loaded to any location in RAM and jumped to. | |
69 | Firmware cannot pass any configuration data to the | |
70 | kernel with this image type and it depends entirely on | |
71 | the embedded device tree for all information. | |
4d2e26a3 | 72 | |
70bf0333 GL |
73 | treeImage.%; Image format for used with OpenBIOS firmware found |
74 | on some ppc4xx hardware. This image embeds a device | |
75 | tree blob inside the image. | |
4d2e26a3 | 76 | |
70bf0333 GL |
77 | uImage: Native image format used by U-Boot. The uImage target |
78 | does not add any boot code. It just wraps a compressed | |
79 | vmlinux in the uImage data structure. This image | |
80 | requires a version of U-Boot that is able to pass | |
81 | a device tree to the kernel at boot. If using an older | |
82 | version of U-Boot, then you need to use a cuImage | |
83 | instead. | |
4d2e26a3 | 84 | |
70bf0333 GL |
85 | zImage.%: Image format which does not embed a device tree. |
86 | Used by OpenFirmware and other firmware interfaces | |
87 | which are able to supply a device tree. This image | |
88 | expects firmware to provide the device tree at boot. | |
89 | Typically, if you have general purpose PowerPC | |
90 | hardware then you want this image format. | |
4d2e26a3 | 91 | ==================== ======================================================== |
70bf0333 GL |
92 | |
93 | Image types which embed a device tree blob (simpleImage, dtbImage, treeImage, | |
94 | and cuImage) all generate the device tree blob from a file in the | |
95 | arch/powerpc/boot/dts/ directory. The Makefile selects the correct device | |
96 | tree source based on the name of the target. Therefore, if the kernel is | |
7ade8495 MS |
97 | built with 'make treeImage.walnut', then the build system will use |
98 | arch/powerpc/boot/dts/walnut.dts to build treeImage.walnut. | |
70bf0333 GL |
99 | |
100 | Two special targets called 'zImage' and 'zImage.initrd' also exist. These | |
101 | targets build all the default images as selected by the kernel configuration. | |
102 | Default images are selected by the boot wrapper Makefile | |
103 | (arch/powerpc/boot/Makefile) by adding targets to the $image-y variable. Look | |
104 | at the Makefile to see which default image targets are available. | |
105 | ||
106 | How it is built | |
107 | --------------- | |
108 | arch/powerpc is designed to support multiplatform kernels, which means | |
109 | that a single vmlinux image can be booted on many different target boards. | |
110 | It also means that the boot wrapper must be able to wrap for many kinds of | |
111 | images on a single build. The design decision was made to not use any | |
112 | conditional compilation code (#ifdef, etc) in the boot wrapper source code. | |
113 | All of the boot wrapper pieces are buildable at any time regardless of the | |
114 | kernel configuration. Building all the wrapper bits on every kernel build | |
115 | also ensures that obscure parts of the wrapper are at the very least compile | |
116 | tested in a large variety of environments. | |
117 | ||
118 | The wrapper is adapted for different image types at link time by linking in | |
119 | just the wrapper bits that are appropriate for the image type. The 'wrapper | |
120 | script' (found in arch/powerpc/boot/wrapper) is called by the Makefile and | |
121 | is responsible for selecting the correct wrapper bits for the image type. | |
122 | The arguments are well documented in the script's comment block, so they | |
123 | are not repeated here. However, it is worth mentioning that the script | |
124 | uses the -p (platform) argument as the main method of deciding which wrapper | |
125 | bits to compile in. Look for the large 'case "$platform" in' block in the | |
126 | middle of the script. This is also the place where platform specific fixups | |
127 | can be selected by changing the link order. | |
128 | ||
129 | In particular, care should be taken when working with cuImages. cuImage | |
130 | wrapper bits are very board specific and care should be taken to make sure | |
131 | the target you are trying to build is supported by the wrapper bits. |