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