0001 ========================
0002 The PowerPC boot wrapper
0003 ========================
0004
0005 Copyright (C) Secret Lab Technologies Ltd.
0006
0007 PowerPC image targets compresses and wraps the kernel image (vmlinux) with
0008 a boot wrapper to make it usable by the system firmware. There is no
0009 standard PowerPC firmware interface, so the boot wrapper is designed to
0010 be adaptable for each kind of image that needs to be built.
0011
0012 The boot wrapper can be found in the arch/powerpc/boot/ directory. The
0013 Makefile in that directory has targets for all the available image types.
0014 The different image types are used to support all of the various firmware
0015 interfaces found on PowerPC platforms. OpenFirmware is the most commonly
0016 used firmware type on general purpose PowerPC systems from Apple, IBM and
0017 others. U-Boot is typically found on embedded PowerPC hardware, but there
0018 are a handful of other firmware implementations which are also popular. Each
0019 firmware interface requires a different image format.
0020
0021 The boot wrapper is built from the makefile in arch/powerpc/boot/Makefile and
0022 it uses the wrapper script (arch/powerpc/boot/wrapper) to generate target
0023 image. The details of the build system is discussed in the next section.
0024 Currently, the following image format targets exist:
0025
0026 ==================== ========================================================
0027 cuImage.%: Backwards compatible uImage for older version of
0028 U-Boot (for versions that don't understand the device
0029 tree). This image embeds a device tree blob inside
0030 the image. The boot wrapper, kernel and device tree
0031 are all embedded inside the U-Boot uImage file format
0032 with boot wrapper code that extracts data from the old
0033 bd_info structure and loads the data into the device
0034 tree before jumping into the kernel.
0035
0036 Because of the series of #ifdefs found in the
0037 bd_info structure used in the old U-Boot interfaces,
0038 cuImages are platform specific. Each specific
0039 U-Boot platform has a different platform init file
0040 which populates the embedded device tree with data
0041 from the platform specific bd_info file. The platform
0042 specific cuImage platform init code can be found in
0043 `arch/powerpc/boot/cuboot.*.c`. Selection of the correct
0044 cuImage init code for a specific board can be found in
0045 the wrapper structure.
0046
0047 dtbImage.%: Similar to zImage, except device tree blob is embedded
0048 inside the image instead of provided by firmware. The
0049 output image file can be either an elf file or a flat
0050 binary depending on the platform.
0051
0052 dtbImages are used on systems which do not have an
0053 interface for passing a device tree directly.
0054 dtbImages are similar to simpleImages except that
0055 dtbImages have platform specific code for extracting
0056 data from the board firmware, but simpleImages do not
0057 talk to the firmware at all.
0058
0059 PlayStation 3 support uses dtbImage. So do Embedded
0060 Planet boards using the PlanetCore firmware. Board
0061 specific initialization code is typically found in a
0062 file named arch/powerpc/boot/<platform>.c; but this
0063 can be overridden by the wrapper script.
0064
0065 simpleImage.%: Firmware independent compressed image that does not
0066 depend on any particular firmware interface and embeds
0067 a device tree blob. This image is a flat binary that
0068 can be loaded to any location in RAM and jumped to.
0069 Firmware cannot pass any configuration data to the
0070 kernel with this image type and it depends entirely on
0071 the embedded device tree for all information.
0072
0073 treeImage.%; Image format for used with OpenBIOS firmware found
0074 on some ppc4xx hardware. This image embeds a device
0075 tree blob inside the image.
0076
0077 uImage: Native image format used by U-Boot. The uImage target
0078 does not add any boot code. It just wraps a compressed
0079 vmlinux in the uImage data structure. This image
0080 requires a version of U-Boot that is able to pass
0081 a device tree to the kernel at boot. If using an older
0082 version of U-Boot, then you need to use a cuImage
0083 instead.
0084
0085 zImage.%: Image format which does not embed a device tree.
0086 Used by OpenFirmware and other firmware interfaces
0087 which are able to supply a device tree. This image
0088 expects firmware to provide the device tree at boot.
0089 Typically, if you have general purpose PowerPC
0090 hardware then you want this image format.
0091 ==================== ========================================================
0092
0093 Image types which embed a device tree blob (simpleImage, dtbImage, treeImage,
0094 and cuImage) all generate the device tree blob from a file in the
0095 arch/powerpc/boot/dts/ directory. The Makefile selects the correct device
0096 tree source based on the name of the target. Therefore, if the kernel is
0097 built with 'make treeImage.walnut', then the build system will use
0098 arch/powerpc/boot/dts/walnut.dts to build treeImage.walnut.
0099
0100 Two special targets called 'zImage' and 'zImage.initrd' also exist. These
0101 targets build all the default images as selected by the kernel configuration.
0102 Default images are selected by the boot wrapper Makefile
0103 (arch/powerpc/boot/Makefile) by adding targets to the $image-y variable. Look
0104 at the Makefile to see which default image targets are available.
0105
0106 How it is built
0107 ---------------
0108 arch/powerpc is designed to support multiplatform kernels, which means
0109 that a single vmlinux image can be booted on many different target boards.
0110 It also means that the boot wrapper must be able to wrap for many kinds of
0111 images on a single build. The design decision was made to not use any
0112 conditional compilation code (#ifdef, etc) in the boot wrapper source code.
0113 All of the boot wrapper pieces are buildable at any time regardless of the
0114 kernel configuration. Building all the wrapper bits on every kernel build
0115 also ensures that obscure parts of the wrapper are at the very least compile
0116 tested in a large variety of environments.
0117
0118 The wrapper is adapted for different image types at link time by linking in
0119 just the wrapper bits that are appropriate for the image type. The 'wrapper
0120 script' (found in arch/powerpc/boot/wrapper) is called by the Makefile and
0121 is responsible for selecting the correct wrapper bits for the image type.
0122 The arguments are well documented in the script's comment block, so they
0123 are not repeated here. However, it is worth mentioning that the script
0124 uses the -p (platform) argument as the main method of deciding which wrapper
0125 bits to compile in. Look for the large 'case "$platform" in' block in the
0126 middle of the script. This is also the place where platform specific fixups
0127 can be selected by changing the link order.
0128
0129 In particular, care should be taken when working with cuImages. cuImage
0130 wrapper bits are very board specific and care should be taken to make sure
0131 the target you are trying to build is supported by the wrapper bits.
