Oops, sent to the wrong address for the mailing list...
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 +++++++++++++++++++++++++++++++++
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
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
+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.
+Currently, the following image 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.
+ dtbImage.%: Similar to zImage, except device tree blob is embedded
+ inside the image.
+ simpleImage.%: Firmware independent compressed image that does not
+ depend on any particular firmware interface and embeds
+ a device tree blob. This image 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 the kernel depends on the device tree to
+ determine its console device.
+ treeImage.%; Image format for some versions of
ppc4xx firmware (non
+ U-Boot firmware). 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.
+ zImage.%: Image usable by OpenFirmware. Image expects firmware
+ to provide the device tree using OpenFirmware
+ interfaces. Typically general purpose hardware uses
+ 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.
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)/%,$@)
define archhelp
- @echo '* zImage - Compressed kernel image(arch/$(ARCH)/boot/zImage.*)'
+ @echo '* zImage - Build default images selected by kernel config'
+ @echo ' zImage.* - Compressed kernel image
(arch/$(ARCH)/boot/zImage.*)'
+ @echo ' uImage - U-Book native image format'
+ @echo ' cuImage.<dt> - Backwards compatible U-Boot image for older'
+ @echo ' versions which do not support device trees'
+ @echo ' dtbImage.<dt> - zImage with an embedded device tree blob'
+ @echo ' simpleImage.<dt> - Firmware independant image.'
+ @echo ' treeImage.<dt> - Support for older IBM 4xx firmware (not U-Boot)'
@echo ' install - Install kernel using'
@echo ' (your) ~/bin/installkernel or'
@echo ' (distribution) /sbin/installkernel or'
@echo ' install to $$(INSTALL_PATH) and run lilo'
@echo ' *_defconfig - Select default config from arch/$(ARCH)/configs'
+ @echo ''
+ @echo ' Targets with <dt> embed a device tree blob inside the image'
+ @echo ' These targets support board with firmware that does not'
+ @echo ' support passing a device tree directly. Replace <dt> with the'
+ @echo ' name of a dts file from the arch/$(ARCH)/boot/dts/ directory'
+ @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"
--
Grant Likely, B.Sc., P.Eng.
Secret Lab Technologies Ltd.
Thanks Grant, that's a great start for helping us to better understand
the bootwrapper.
The wrapper is somewhat complex and hard to get your head around, or at
least my head ;).
-- John
-----Original Message-----
From: Grant Likely [mailto:grant.likely@secretlab.ca] =
Sent: Wednesday, June 25, 2008 2:21 PM
To: John Linn; Stephen Neuendorffer; linuxppc-dev@ozlabs.com;
paulus@samba.org
Cc: petermendham@computing.dundee.ac.uk
Subject: [PATCH] powerpc/bootwrapper: Add documentation of boot wrapper
targets
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
+++++++++++++++++++++++++++++++++
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
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
+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.
+Currently, the following image 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.
+ dtbImage.%: Similar to zImage, except device tree blob is
embedded
+ inside the image.
+ simpleImage.%: Firmware independent compressed image that does
not
+ depend on any particular firmware interface and
embeds
+ a device tree blob. This image 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 the kernel depends on the device tree
to
+ determine its console device.
+ treeImage.%; Image format for some versions of ppc4xx
firmware (non
+ U-Boot firmware). 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.
+ zImage.%: Image usable by OpenFirmware. Image expects
firmware
+ to provide the device tree using OpenFirmware
+ interfaces. Typically general purpose hardware
uses
+ 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.
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=3Dppc64 $(build)=3D$(boot) $(patsubst
%,$(boot)/%,$@)
=
define archhelp
- @echo '* zImage - Compressed kernel image
(arch/$(ARCH)/boot/zImage.*)'
+ @echo '* zImage - Build default images selected by kernel
config'
+ @echo ' zImage.* - Compressed kernel image
(arch/$(ARCH)/boot/zImage.*)'
+ @echo ' uImage - U-Book native image format'
+ @echo ' cuImage.<dt> - Backwards compatible U-Boot image for
older'
+ @echo ' versions which do not support device
trees'
+ @echo ' dtbImage.<dt> - zImage with an embedded device tree blob'
+ @echo ' simpleImage.<dt> - Firmware independant image.'
+ @echo ' treeImage.<dt> - Support for older IBM 4xx firmware (not
U-Boot)'
@echo ' install - Install kernel using'
@echo ' (your) ~/bin/installkernel or'
@echo ' (distribution) /sbin/installkernel or'
@echo ' install to $$(INSTALL_PATH) and run lilo'
@echo ' *_defconfig - Select default config from
arch/$(ARCH)/configs'
+ @echo ''
+ @echo ' Targets with <dt> embed a device tree blob inside the image'
+ @echo ' These targets support board with firmware that does not'
+ @echo ' support passing a device tree directly. Replace <dt> with
the'
+ @echo ' name of a dts file from the arch/$(ARCH)/boot/dts/
directory'
+ @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=3D"$object/virtex405-head.o $object/simpleboot.o"
binary=3Dy
;;
+simpleboot-*)
+ platformo=3D"$object/simpleboot.o"
+ binary=3Dy
+ ;;
esac
=
vmz=3D"$tmpdir/`basename \"$kernel\"`.$ext"
This email and any attachments are intended for the sole use of the named r=
ecipient(s) and contain(s) confidential information that may be proprietary=
, privileged or copyrighted under applicable law. If you are not the intend=
ed recipient, do not read, copy, or forward this email message or any attac=
hments. Delete this email message and any attachments immediately.
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.
-----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
Cc: petermendham@computing.dundee.ac.uk
Subject: [PATCH] powerpc/bootwrapper: Add documentation of boot
wrapper targets
=
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
+++++++++++++++++++++++++++++++++
arch/powerpc/Makefile | 15 ++++++
arch/powerpc/boot/wrapper | 4 ++
3 files changed, 96 insertions(+), 1 deletions(-)
=
quoted hunk
diff --git a/Documentation/powerpc/bootwrapper.txt
b/Documentation/powerpc/bootwrapper.txt
quoted hunk
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
+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.
+Currently, the following image 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.
+ dtbImage.%: Similar to zImage, except device tree
blob is embedded
+ inside the image.
+ simpleImage.%: Firmware independent compressed image that does
not
+ depend on any particular firmware interface and
embeds
+ a device tree blob. This image 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 the kernel depends on the device tree
to
+ determine its console device.
+ treeImage.%; Image format for some versions of ppc4xx
firmware (non
+ U-Boot firmware). 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.
+ zImage.%: Image usable by OpenFirmware. Image expects
firmware
+ to provide the device tree using OpenFirmware
+ interfaces. Typically general purpose hardware
uses
+ 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
quoted hunk
+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=3Dppc64 $(build)=3D$(boot) $(patsubst
%,$(boot)/%,$@)
=
define archhelp
- @echo '* zImage - Compressed kernel image
(arch/$(ARCH)/boot/zImage.*)'
+ @echo '* zImage - Build default images selected by kernel
config'
+ @echo ' zImage.* - Compressed kernel image
(arch/$(ARCH)/boot/zImage.*)'
+ @echo ' uImage - U-Book native image format'
+ @echo ' cuImage.<dt> - Backwards compatible U-Boot image for
older'
+ @echo ' versions which do not support device
trees'
+ @echo ' dtbImage.<dt> - zImage with an embedded device tree
blob'
+ @echo ' simpleImage.<dt> - Firmware independant image.'
+ @echo ' treeImage.<dt> - Support for older IBM 4xx firmware (not
U-Boot)'
@echo ' install - Install kernel using'
@echo ' (your) ~/bin/installkernel or'
@echo ' (distribution) /sbin/installkernel or'
@echo ' install to $$(INSTALL_PATH) and run
lilo'
@echo ' *_defconfig - Select default config from
arch/$(ARCH)/configs'
+ @echo ''
+ @echo ' Targets with <dt> embed a device tree blob inside the
image'
+ @echo ' These targets support board with firmware that does not'
+ @echo ' support passing a device tree directly. Replace <dt> with
the'
+ @echo ' name of a dts file from the arch/$(ARCH)/boot/dts/
directory'
+ @echo ' (minus the .dts extension).'
endef
=
quoted hunk
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=3D"$object/virtex405-head.o $object/simpleboot.o"
binary=3Dy
;;
+simpleboot-*)
+ platformo=3D"$object/simpleboot.o"
+ binary=3Dy
+ ;;
esac=
vmz=3D"$tmpdir/`basename \"$kernel\"`.$ext"
=
This email and any attachments are intended for the sole use of the named r=
ecipient(s) and contain(s) confidential information that may be proprietary=
, privileged or copyrighted under applicable law. If you are not the intend=
ed recipient, do not read, copy, or forward this email message or any attac=
hments. Delete this email message and any attachments immediately.
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.
-----Original Message-----
From: Josh Boyer [mailto:jwboyer@gmail.com]
Sent: Thursday, June 26, 2008 12:07 PM
To: Stephen Neuendorffer
Cc: grant.likely@secretlab.ca; John Linn; linuxppc-dev@ozlabs.com;
paulus@samba.org;
petermendham@computing.dundee.ac.uk
Subject: RE: [PATCH] powerpc/bootwrapper: Add documentation of boot
wrappertargets
=
On Thu, 2008-06-26 at 09:48 -0700, Stephen Neuendorffer wrote:
quoted
My unanswered questions:
1) Why are there 4 different types of targets that embed a device
tree?
quoted
I assume they differ in how they are started loaded, but
(unfortunately)
quoted
the names are meaningless (With the exception of cuImage, which is
only
quoted
cryptic.. :) If I'm adding support for a new board, which should I
use?
=
They are all needed to deal with different firmwares.
Where 'firmware' really means 'method of invoking the kernel'
treeImage is for OpenBIOS based boards (Ebony, Walnut, some boards
running PIBS can also use this). This firmware requires a special
header on the image file.
So it's not an elf? or it is an .elf? maybe it should be
'openBiosImage'?
=
cuImage is for boards running an older U-Boot that does not understand
device trees.
Forgive my ignorance here, but what specifically does this imply? As
far as I can tell, generally speaking, some of the board-specific
information is passed into the boot wrapper, which then stuffs it into
the device tree.
uImage is for device-tree aware U-Boot versions
And this differs from above because it gets a device tree passed in,
which uboot has already stuffed correctly.
dtbImage is used for boards that can take an ELF zImage, but still
need
a dtb provided.
=
simpleImage, not sure here.
So both of these are elfs... but how do they differ? Is it only in how
the right head.s file gets picked up?
Steve
This email and any attachments are intended for the sole use of the named r=
ecipient(s) and contain(s) confidential information that may be proprietary=
, privileged or copyrighted under applicable law. If you are not the intend=
ed recipient, do not read, copy, or forward this email message or any attac=
hments. Delete this email message and any attachments immediately.
Stephen Neuendorffer wrote:
quoted
cuImage is for boards running an older U-Boot that does not understand
device trees.
Forgive my ignorance here, but what specifically does this imply? As
far as I can tell, generally speaking, some of the board-specific
information is passed into the boot wrapper, which then stuffs it into
the device tree.
It implies that the binary is in uImage format, targets older u-boot (as
opposed to some other bootloader entirely, which might be targeted with
a dtbImage -- see adder875, for example), and has a device tree embedded.
quoted
uImage is for device-tree aware U-Boot versions
And this differs from above because it gets a device tree passed in,
which uboot has already stuffed correctly.
Yes.
quoted
dtbImage is used for boards that can take an ELF zImage, but still
need
quoted
a dtb provided.
simpleImage, not sure here.
So both of these are elfs... but how do they differ? Is it only in how
the right head.s file gets picked up?
Neither is necessarily an ELF. The only simpleboot target I see is a
flat binary, as are some of the dtbImage targets (adder875, ep88xc,
ep405, etc). simpleboot is more of a platform than an image type; it's
a platform that assumes nothing about the firmware that loaded it, and
gets all information from the embedded device tree.
-Scott
On Thu, Jun 26, 2008 at 1:16 PM, Stephen Neuendorffer
[off-list ref] wrote:
Forgive my ignorance here, but what specifically does this imply? As
far as I can tell, generally speaking, some of the board-specific
information is passed into the boot wrapper, which then stuffs it into
the device tree.
Yes, you are correct. I'll fill out the documentation more here.
quoted
uImage is for device-tree aware U-Boot versions
And this differs from above because it gets a device tree passed in,
which uboot has already stuffed correctly.
Correct.
quoted
dtbImage is used for boards that can take an ELF zImage, but still
need
quoted
a dtb provided.
simpleImage, not sure here.
So both of these are elfs... but how do they differ? Is it only in how
the right head.s file gets picked up?
simpleImage is not an elf. Its a raw position-independent binary
which can be loaded anywhere in RAM.
Some dtbImages are elfs; but there are a flat binaries. The main
difference is that all simpleImages assume that firmware provides
nothing interesting; but the flat dtbImages have custom code for
extracting a little bit of data out of the boards firmware.
It's all a bit of a confusing mess. It might be a good idea to rework
all the image names to stuff not so non-obvious, but I'm not sure the
best way to go about it. There is a lot of historical stuff in there
where the various 'zImage.*' targets grew and morphed over time in
ways that are hard to follow. It may make more sense to change the
flat-binary dtbImages to be simpleImages instead with overrides for
specific boards (just like is done for virtex405-*). ps3 is the other
major user of dtbImage. I created the whole dtbImage stuff in the
first place to eliminate overloaded makefile targets where some
zImage% target were providing a device tree and other zImage% targets
were not. Splitting dtb-provided from dtb-not-provided targets
clarified the Makefile quite a bit. dtbImage is not a fantastic name,
but I needed something different from zImage for images with an
embedded device tree.
Looking at the Makefile, dtbImage and simpleImage targets are
virtually identical. Perhaps it would be best to merge the targets
and deal with all the differences in the wrapper script (with the
default to just use simpleboot.S as the init code). Thoughts?
Cheers,
g.
--
Grant Likely, B.Sc., P.Eng.
Secret Lab Technologies Ltd.
simpleImage should also create an .elf (for xmd or systemAce loading)
If dtbImage and simpleImage could be merged, I'd be all for it...
At some point of course, I need to figure merge the Device Tree in BRAM code that I've been using, which would be a simpleImage which wouldn't need a device tree. However, I don't see this happening before August.
Steve
-----Original Message-----
From: glikely@secretlab.ca on behalf of Grant Likely
Sent: Fri 6/27/2008 9:22 PM
To: Stephen Neuendorffer
Cc: Josh Boyer; John Linn; linuxppc-dev@ozlabs.com; paulus@samba.org; petermendham@computing.dundee.ac.uk; Scott Wood; Geoff Levand
Subject: Re: [PATCH] powerpc/bootwrapper: Add documentation of boot wrappertargets
On Thu, Jun 26, 2008 at 1:16 PM, Stephen Neuendorffer
[off-list ref] wrote:
Forgive my ignorance here, but what specifically does this imply? As
far as I can tell, generally speaking, some of the board-specific
information is passed into the boot wrapper, which then stuffs it into
the device tree.
Yes, you are correct. I'll fill out the documentation more here.
quoted
uImage is for device-tree aware U-Boot versions
And this differs from above because it gets a device tree passed in,
which uboot has already stuffed correctly.
Correct.
quoted
dtbImage is used for boards that can take an ELF zImage, but still
need
quoted
a dtb provided.
simpleImage, not sure here.
So both of these are elfs... but how do they differ? Is it only in how
the right head.s file gets picked up?
simpleImage is not an elf. Its a raw position-independent binary
which can be loaded anywhere in RAM.
Some dtbImages are elfs; but there are a flat binaries. The main
difference is that all simpleImages assume that firmware provides
nothing interesting; but the flat dtbImages have custom code for
extracting a little bit of data out of the boards firmware.
It's all a bit of a confusing mess. It might be a good idea to rework
all the image names to stuff not so non-obvious, but I'm not sure the
best way to go about it. There is a lot of historical stuff in there
where the various 'zImage.*' targets grew and morphed over time in
ways that are hard to follow. It may make more sense to change the
flat-binary dtbImages to be simpleImages instead with overrides for
specific boards (just like is done for virtex405-*). ps3 is the other
major user of dtbImage. I created the whole dtbImage stuff in the
first place to eliminate overloaded makefile targets where some
zImage% target were providing a device tree and other zImage% targets
were not. Splitting dtb-provided from dtb-not-provided targets
clarified the Makefile quite a bit. dtbImage is not a fantastic name,
but I needed something different from zImage for images with an
embedded device tree.
Looking at the Makefile, dtbImage and simpleImage targets are
virtually identical. Perhaps it would be best to merge the targets
and deal with all the differences in the wrapper script (with the
default to just use simpleboot.S as the init code). Thoughts?
Cheers,
g.
--
Grant Likely, B.Sc., P.Eng.
Secret Lab Technologies Ltd.
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.