Merge commit 'jwb/jwb-next'

1 files changed, 141 insertions, 0 deletions

diff --git a/Documentation/powerpc/bootwrapper.txt b/Documentation/powerpc/bootwrapper.txt
new file mode 100644
index 000000000000..d60fced5e1cc
--- /dev/null
+++ b/Documentation/powerpc/bootwrapper.txt
@@ -0,0 +1,141 @@
+The PowerPC boot wrapper
+------------------------
+Copyright (C) Secret Lab Technologies Ltd.
+
+PowerPC image targets compresses and wraps the kernel image (vmlinux) with
+a boot wrapper to make it usable by the system firmware.  There is no
+standard PowerPC firmware interface, so the boot wrapper is designed to
+be adaptable for each kind of image that needs to be built.
+
+The boot wrapper can be found in the arch/powerpc/boot/ directory.  The
+Makefile in that directory has targets for all the available image types.
+The different image types are used to support all of the various firmware
+interfaces found on PowerPC platforms.  OpenFirmware is the most commonly
+used firmware type on general purpose PowerPC systems from Apple, IBM and
+others.  U-Boot is typically found on embedded PowerPC hardware, but there
+are a handful of other firmware implementations which are also popular.  Each
+firmware interface requires a different image format.
+
+The boot wrapper is built from the makefile in arch/powerpc/boot/Makefile and
+it uses the wrapper script (arch/powerpc/boot/wrapper) to generate target
+image.  The details of the build system is discussed in the next section.
+Currently, the following image format targets exist:
+
+   cuImage.%:           Backwards compatible uImage for older version of
+                        U-Boot (for versions that don't understand the device
+                        tree).  This image embeds a device tree blob inside
+                        the image.  The boot wrapper, kernel and device tree
+                        are all embedded inside the U-Boot uImage file format
+                        with boot wrapper code that extracts data from the old
+                        bd_info structure and loads the data into the device
+                        tree before jumping into the kernel.
+                          Because of the series of #ifdefs found in the
+                        bd_info structure used in the old U-Boot interfaces,
+                        cuImages are platform specific.  Each specific
+                        U-Boot platform has a different platform init file
+                        which populates the embedded device tree with data
+                        from the platform specific bd_info file.  The platform
+                        specific cuImage platform init code can be found in
+                        arch/powerpc/boot/cuboot.*.c.  Selection of the correct
+                        cuImage init code for a specific board can be found in
+                        the wrapper structure.
+   dtbImage.%:          Similar to zImage, except device tree blob is embedded
+                        inside the image instead of provided by firmware.  The
+                        output image file can be either an elf file or a flat
+                        binary depending on the platform.
+                          dtbImages are used on systems which do not have an
+                        interface for passing a device tree directly.
+                        dtbImages are similar to simpleImages except that
+                        dtbImages have platform specific code for extracting
+                        data from the board firmware, but simpleImages do not
+                        talk to the firmware at all.
+                          PlayStation 3 support uses dtbImage.  So do Embedded
+                        Planet boards using the PlanetCore firmware.  Board
+                        specific initialization code is typically found in a
+                        file named arch/powerpc/boot/<platform>.c; but this
+                        can be overridden by the wrapper script.
+   simpleImage.%:       Firmware independent compressed image that does not
+                        depend on any particular firmware interface and embeds
+                        a device tree blob.  This image is a flat binary that
+                        can be loaded to any location in RAM and jumped to.
+                        Firmware cannot pass any configuration data to the
+                        kernel with this image type and it depends entirely on
+                        the embedded device tree for all information.
+                          The simpleImage is useful for booting systems with
+                        an unknown firmware interface or for booting from
+                        a debugger when no firmware is present (such as on
+                        the Xilinx Virtex platform).  The only assumption that
+                        simpleImage makes is that RAM is correctly initialized
+                        and that the MMU is either off or has RAM mapped to
+                        base address 0.
+                          simpleImage also supports inserting special platform
+                        specific initialization code to the start of the bootup
+                        sequence.  The virtex405 platform uses this feature to
+                        ensure that the cache is invalidated before caching
+                        is enabled.  Platform specific initialization code is
+                        added as part of the wrapper script and is keyed on
+                        the image target name.  For example, all
+                        simpleImage.virtex405-* targets will add the
+                        virtex405-head.S initialization code (This also means
+                        that the dts file for virtex405 targets should be
+                        named (virtex405-<board>.dts).  Search the wrapper
+                        script for 'virtex405' and see the file
+                        arch/powerpc/boot/virtex405-head.S for details.
+   treeImage.%;         Image format for used with OpenBIOS firmware found
+                        on some ppc4xx hardware.  This image embeds a device
+                        tree blob inside the image.
+   uImage:              Native image format used by U-Boot.  The uImage target
+                        does not add any boot code.  It just wraps a compressed
+                        vmlinux in the uImage data structure.  This image
+                        requires a version of U-Boot that is able to pass
+                        a device tree to the kernel at boot.  If using an older
+                        version of U-Boot, then you need to use a cuImage
+                        instead.
+   zImage.%:            Image format which does not embed a device tree.
+                        Used by OpenFirmware and other firmware interfaces
+                        which are able to supply a device tree.  This image
+                        expects firmware to provide the device tree at boot.
+                        Typically, if you have general purpose PowerPC
+                        hardware then you want this image format.
+
+Image types which embed a device tree blob (simpleImage, dtbImage, treeImage,
+and cuImage) all generate the device tree blob from a file in the
+arch/powerpc/boot/dts/ directory.  The Makefile selects the correct device
+tree source based on the name of the target.  Therefore, if the kernel is
+built with 'make treeImage.walnut simpleImage.virtex405-ml403', then the
+build system will use arch/powerpc/boot/dts/walnut.dts to build
+treeImage.walnut and arch/powerpc/boot/dts/virtex405-ml403.dts to build
+the simpleImage.virtex405-ml403.
+
+Two special targets called 'zImage' and 'zImage.initrd' also exist.  These
+targets build all the default images as selected by the kernel configuration.
+Default images are selected by the boot wrapper Makefile
+(arch/powerpc/boot/Makefile) by adding targets to the $image-y variable.  Look
+at the Makefile to see which default image targets are available.
+
+How it is built
+---------------
+arch/powerpc is designed to support multiplatform kernels, which means
+that a single vmlinux image can be booted on many different target boards.
+It also means that the boot wrapper must be able to wrap for many kinds of
+images on a single build.  The design decision was made to not use any
+conditional compilation code (#ifdef, etc) in the boot wrapper source code.
+All of the boot wrapper pieces are buildable at any time regardless of the
+kernel configuration.  Building all the wrapper bits on every kernel build
+also ensures that obscure parts of the wrapper are at the very least compile
+tested in a large variety of environments.
+
+The wrapper is adapted for different image types at link time by linking in
+just the wrapper bits that are appropriate for the image type.  The 'wrapper
+script' (found in arch/powerpc/boot/wrapper) is called by the Makefile and
+is responsible for selecting the correct wrapper bits for the image type.
+The arguments are well documented in the script's comment block, so they
+are not repeated here.  However, it is worth mentioning that the script
+uses the -p (platform) argument as the main method of deciding which wrapper
+bits to compile in.  Look for the large 'case "$platform" in' block in the
+middle of the script.  This is also the place where platform specific fixups
+can be selected by changing the link order.
+
+In particular, care should be taken when working with cuImages.  cuImage
+wrapper bits are very board specific and care should be taken to make sure
+the target you are trying to build is supported by the wrapper bits.