Re: [PATCH] powerpc/bootwrapper: Add documentation of boot wrapper targets

Thanks for this documentation - I found it very illuminating.  My question was going to be similar to Stephen's in that I don't find it clear which of the images with an embedded device tree I should be using.  This is all in contrast to the Xilinx git tree where I just use zImage with a config option for embedding the device tree...

-- Peter

Stephen Neuendorffer wrote:

My unanswered questions:

1) Why are there 4 different types of targets that embed a device tree?
I assume they differ in how they are started loaded, but (unfortunately)
the names are meaningless (With the exception of cuImage, which is only
cryptic.. :)  If I'm adding support for a new board, which should I use?

2) The simpleImage target is capable of selecting a head.s file to link
based on the target name.  This needs to be documented.

  

quoted

-----Original Message-----
From: Grant Likely [mailto:grant.likely@secretlab.ca]
Sent: Wednesday, June 25, 2008 1:21 PM
To: John Linn; Stephen Neuendorffer; linuxppc-dev@ozlabs.com;
    

paulus@samba.org
  

quoted

Cc: petermendham@computing.dundee.ac.uk
Subject: [PATCH] powerpc/bootwrapper: Add documentation of boot
    

wrapper targets
  

quoted

From: Grant Likely <redacted>

There have been many questions on and off the mailing list about how
exactly the bootwrapper is used for embedded targets.  Add some
documentation and help text to try and clarify the system.

Signed-off-by: Grant Likely <redacted>
---

 Documentation/powerpc/bootwrapper.txt |   78
    

+++++++++++++++++++++++++++++++++
  

quoted

 arch/powerpc/Makefile                 |   15 ++++++
 arch/powerpc/boot/wrapper             |    4 ++
 3 files changed, 96 insertions(+), 1 deletions(-)

diff --git a/Documentation/powerpc/bootwrapper.txt
    

b/Documentation/powerpc/bootwrapper.txt
  

quoted

new file mode 100644
index 0000000..8dcb560

--- /dev/null
+++ b/Documentation/powerpc/bootwrapper.txt

@@ -0,0 +1,78 @@
+The PowerPC boot wrapper
+------------------------
+Copyright (C) Secret Lab Technologies Ltd.
+
+PowerPC image targets compresses and wraps the kernel image (vmlinux)
    

with
  

quoted

+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
  

quoted

+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
  

quoted

+Makefile in that directory has targets for all the available image
    

types.
  

quoted

+Currently, the following image targets exist:
+
+   cuImage.%:		Backwards compatible uImage for older
    

version of
  

quoted

+			U-Boot (for versions that don't understand the
    

device
  

quoted

+			tree).  This image embeds a device tree blob
    

inside
  

quoted

+			the image.
+   dtbImage.%:		Similar to zImage, except device tree
    

blob is embedded
  

quoted

+			inside the image.
+   simpleImage.%:	Firmware independent compressed image that does
    

not
  

quoted

+			depend on any particular firmware interface and
    

embeds
  

quoted

+			a device tree blob.  This image can be loaded to
    

any
  

quoted

+			location in RAM and jumped to.  Firmware cannot
    

pass
  

quoted

+			any configuration data to the kernel with this
    

image
  

quoted

+			type and the kernel depends on the device tree
    

to
  

quoted

+			determine its console device.
+   treeImage.%;		Image format for some versions of ppc4xx
    

firmware (non
  

quoted

+			U-Boot firmware).  This image embeds a device
    

tree
  

quoted

+			blob inside the image.
+   uImage:		Native image format used by U-Boot.  The uImage
    

target
  

quoted

+			does not add any boot code.  It just wraps a
    

compressed
  

quoted

+			vmlinux in the uImage data structure.
+   zImage.%:		Image usable by OpenFirmware.  Image expects
    

firmware
  

quoted

+			to provide the device tree using OpenFirmware
+			interfaces.  Typically general purpose hardware
    

uses
  

quoted

+			this image format.
+
+Image types which embed a device tree blob (simpleImage, dtbImage,
    

treeImage,
  

quoted

+and cuImage) all generate the device tree blob from a file in the
+arch/powerpc/boot/dts/ directory.  The Makefile selects the correct
    

device
  

quoted

+tree source based on the name of the target.  Therefore, if the
    

kernel is
  

quoted

+built with 'make treeImage.walnut simpleImage.virtex405-ml403', then
    

the
  

quoted

+build system will use arch/powerpc/boot/dts/walnut.dts to build
+treeImage.walnut and arch/powerpc/boot/dts/virtex405-ml403.dts to
    

build
  

quoted

+the simpleImage.virtex405-ml403.
+
+Two special targets called 'zImage' and 'zImage.initrd' also exist.
    

These
  

quoted

+targets build all the default images as selected by the kernel
    

configuration.
  

quoted

+Default images are selected by the boot wrapper Makefile
+(arch/powerpc/boot/Makefile) by adding targets to the $image-y
    

variable.  Look
  

quoted

+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
  

quoted

+that a single vmlinux image can be booted on many different target
    

boards.
  

quoted

+It also means that the boot wrapper must be able to wrap for many
    

kinds of
  

quoted

+images on a single build.  The design decision was made to not use
    

any
  

quoted

+conditional compilation code (#ifdef, etc) in the boot wrapper source
    

code.
  

quoted

+All of the boot wrapper pieces are buildable at any time regardless
    

of the
  

quoted

+kernel configuration.  Building all the wrapper bits on every kernel
    

build
  

quoted

+also ensures that obscure parts of the wrapper are at the very least
    

compile
  

quoted

+tested in a large variety of environments.
+
+The wrapper is adapted for different image types at link time by
    

linking in
  

quoted

+just the wrapper bits that are appropriate for the image type.  The
    

'wrapper'
  

quoted

+script (found in arch/powerpc/boot/wrapper) is called by the Makefile
    

and
  

quoted

+is responsible for selecting the correct wrapper bits for the image
    

type.
  

quoted

+The arguments are well documented in the script's comment block, so
    

they
  

quoted

+are not repeated here.  However, it is worth mentioning that the
    

script
  

quoted

+uses the -p (platform) argument as the main method of deciding which
    

wrapper
  

quoted

+bits to compile in.  Look for the large 'case "$platform" in' block
    

in the
  

quoted

+middle of the script.  This is also the place where platform specific
    

fixups
  

quoted

+can be selected by changing the link order.
+
+In particular, care should be taken when working with cuImages.
    

cuImage
  

quoted

+wrapper bits are very board specific and care should be taken to make
    

sure
  

quoted

+the target you are trying to build is supported by the wrapper bits.

diff --git a/arch/powerpc/Makefile b/arch/powerpc/Makefile
index b7d4c4c..754c7eb 100644
--- a/arch/powerpc/Makefile
+++ b/arch/powerpc/Makefile

@@ -169,12 +169,25 @@ bootwrapper_install %.dtb:
 	$(Q)$(MAKE) ARCH=ppc64 $(build)=$(boot) $(patsubst
    

%,$(boot)/%,$@)
  

quoted

 define archhelp
-  @echo '* zImage          - Compressed kernel image
    

(arch/$(ARCH)/boot/zImage.*)'
  

quoted

+  @echo '* zImage          - Build default images selected by kernel
    

config'
  

quoted

+  @echo '  zImage.*        - Compressed kernel image
    

(arch/$(ARCH)/boot/zImage.*)'
  

quoted

+  @echo '  uImage          - U-Book native image format'
+  @echo '  cuImage.<dt>    - Backwards compatible U-Boot image for
    

older'
  

quoted

+  @echo '                    versions which do not support device
    

trees'
  

quoted

+  @echo '  dtbImage.<dt>   - zImage with an embedded device tree
    

blob'
  

quoted

+  @echo '  simpleImage.<dt> - Firmware independant image.'
+  @echo '  treeImage.<dt>  - Support for older IBM 4xx firmware (not
    

U-Boot)'
  

quoted

   @echo '  install         - Install kernel using'
   @echo '                    (your) ~/bin/installkernel or'
   @echo '                    (distribution) /sbin/installkernel or'
   @echo '                    install to $$(INSTALL_PATH) and run
    

lilo'
  

quoted

   @echo '  *_defconfig     - Select default config from
    

arch/$(ARCH)/configs'
  

quoted

+  @echo ''
+  @echo '  Targets with <dt> embed a device tree blob inside the
    

image'
  

quoted

+  @echo '  These targets support board with firmware that does not'
+  @echo '  support passing a device tree directly.  Replace <dt> with
    

the'
  

quoted

+  @echo '  name of a dts file from the arch/$(ARCH)/boot/dts/
    

directory'
  

quoted

+  @echo '  (minus the .dts extension).'
 endef

 install:

diff --git a/arch/powerpc/boot/wrapper b/arch/powerpc/boot/wrapper
index d6c96d9..7cd4182 100755
--- a/arch/powerpc/boot/wrapper
+++ b/arch/powerpc/boot/wrapper

@@ -203,6 +203,10 @@ simpleboot-virtex405-*)
     platformo="$object/virtex405-head.o $object/simpleboot.o"
     binary=y
     ;;
+simpleboot-*)
+    platformo="$object/simpleboot.o"
+    binary=y
+    ;;
 esac

 vmz="$tmpdir/`basename \"$kernel\"`.$ext"

    

This email and any attachments are intended for the sole use of the named recipient(s) and contain(s) confidential information that may be proprietary, privileged or copyrighted under applicable law. If you are not the intended recipient, do not read, copy, or forward this email message or any attachments. Delete this email message and any attachments immediately.


  

The University of Dundee is a Scottish Registered Charity, No. SC015096.