Kevin/Jibo-Platform-Tools-OLD
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

avionic design with actual uboot and tooling

Browse Source 
submodule of avionic design uboot bootloader and with included tools to
get you started , read readme.md and readme-tk1-loader.md
This commit is contained in:
Kevin
2026-03-03 21:46:32 +02:00
parent fe3ba02c96
commit 68d74d3181
11967 changed files with 2221897 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

608
u-boot/doc/uImage.FIT/beaglebone_vboot.txt Normal file
View File

@@ -0,0 +1,608 @@
Verified Boot on the Beaglebone Black
=====================================
Introduction
------------
Before reading this, please read verified-boot.txt and signature.txt. These
instructions are for mainline U-Boot from v2014.07 onwards.
There is quite a bit of documentation in this directory describing how
verified boot works in U-Boot. There is also a test which runs through the
entire process of signing an image and running U-Boot (sandbox) to check it.
However, it might be useful to also have an example on a real board.
Beaglebone Black is a fairly common board so seems to be a reasonable choice
for an example of how to enable verified boot using U-Boot.
First a note that may to help avoid confusion. U-Boot and Linux both use
device tree. They may use the same device tree source, but it is seldom useful
for them to use the exact same binary from the same place. More typically,
U-Boot has its device tree packaged wtih it, and the kernel's device tree is
packaged with the kernel. In particular this is important with verified boot,
since U-Boot's device tree must be immutable. If it can be changed then the
public keys can be changed and verified boot is useless. An attacker can
simply generate a new key and put his public key into U-Boot so that
everything verifies. On the other hand the kernel's device tree typically
changes when the kernel changes, so it is useful to package an updated device
tree with the kernel binary. U-Boot supports the latter with its flexible FIT
format (Flat Image Tree).
Overview
--------
The steps are roughly as follows:
1. Build U-Boot for the board, with the verified boot options enabled.
2. Obtain a suitable Linux kernel
3. Create a Image Tree Source file (ITS) file describing how you want the
kernel to be packaged, compressed and signed.
4. Create a key pair
5. Sign the kernel
6. Put the public key into U-Boot's image
7. Put U-Boot and the kernel onto the board
8. Try it
Step 1: Build U-Boot
--------------------
a. Set up the environment variable to point to your toolchain. You will need
this for U-Boot and also for the kernel if you build it. For example if you
installed a Linaro version manually it might be something like:
export CROSS_COMPILE=/opt/linaro/gcc-linaro-arm-linux-gnueabihf-4.8-2013.08_linux/bin/arm-linux-gnueabihf-
or if you just installed gcc-arm-linux-gnueabi then it might be
export CROSS_COMPILE=arm-linux-gnueabi-
b. Configure and build U-Boot with verified boot enabled:
export ARCH=arm
export UBOOT=/path/to/u-boot
cd $UBOOT
# You can add -j10 if you have 10 CPUs to make it faster
make O=b/am335x_boneblack_vboot am335x_boneblack_vboot_config all
export UOUT=$UBOOT/b/am335x_boneblack_vboot
c. You will now have a U-Boot image:
file b/am335x_boneblack_vboot/u-boot-dtb.img
b/am335x_boneblack_vboot/u-boot-dtb.img: u-boot legacy uImage, U-Boot 2014.07-rc2-00065-g2f69f8, Firmware/ARM, Firmware Image (Not compressed), 395375 bytes, Sat May 31 16:19:04 2014, Load Address: 0x80800000, Entry Point: 0x00000000, Header CRC: 0x0ABD6ACA, Data CRC: 0x36DEF7E4
Step 2: Build Linux
--------------------
a. Find the kernel image ('Image') and device tree (.dtb) file you plan to
use. In our case it is am335x-boneblack.dtb and it is built with the kernel.
At the time of writing an SD Boot image can be obtained from here:
http://www.elinux.org/Beagleboard:Updating_The_Software#Image_For_Booting_From_microSD
You can write this to an SD card and then mount it to extract the kernel and
device tree files.
You can also build a kernel. Instructions for this are are here:
http://elinux.org/Building_BBB_Kernel
or you can use your favourite search engine. Following these instructions
produces a kernel Image and device tree files. For the record the steps were:
export KERNEL=/path/to/kernel
cd $KERNEL
git clone git://github.com/beagleboard/kernel.git .
git checkout v3.14
./patch.sh
cp configs/beaglebone kernel/arch/arm/configs/beaglebone_defconfig
cd kernel
make beaglebone_defconfig
make uImage dtbs # -j10 if you have 10 CPUs
export OKERNEL=$KERNEL/kernel/arch/arm/boot
c. You now have the 'Image' and 'am335x-boneblack.dtb' files needed to boot.
Step 3: Create the ITS
----------------------
Set up a directory for your work.
export WORK=/path/to/dir
cd $WORK
Put this into a file in that directory called sign.its:
/dts-v1/;
/ {
description = "Beaglebone black";
#address-cells = <1>;
images {
kernel@1 {
data = /incbin/("Image.lzo");
type = "kernel";
arch = "arm";
os = "linux";
compression = "lzo";
load = <0x80008000>;
entry = <0x80008000>;
hash@1 {
algo = "sha1";
};
};
fdt@1 {
description = "beaglebone-black";
data = /incbin/("am335x-boneblack.dtb");
type = "flat_dt";
arch = "arm";
compression = "none";
hash@1 {
algo = "sha1";
};
};
};
configurations {
default = "conf@1";
conf@1 {
kernel = "kernel@1";
fdt = "fdt@1";
signature@1 {
algo = "sha1,rsa2048";
key-name-hint = "dev";
sign-images = "fdt", "kernel";
};
};
};
};
The explanation for this is all in the documentation you have already read.
But briefly it packages a kernel and device tree, and provides a single
configuration to be signed with a key named 'dev'. The kernel is compressed
with LZO to make it smaller.
Step 4: Create a key pair
-------------------------
See signature.txt for details on this step.
cd $WORK
mkdir keys
openssl genrsa -F4 -out keys/dev.key 2048
openssl req -batch -new -x509 -key keys/dev.key -out keys/dev.crt
Note: keys/dev.key contains your private key and is very secret. If anyone
gets access to that file they can sign kernels with it. Keep it secure.
Step 5: Sign the kernel
-----------------------
We need to use mkimage (which was built when you built U-Boot) to package the
Linux kernel into a FIT (Flat Image Tree, a flexible file format that U-Boot
can load) using the ITS file you just created.
At the same time we must put the public key into U-Boot device tree, with the
'required' property, which tells U-Boot that this key must be verified for the
image to be valid. You will make this key available to U-Boot for booting in
step 6.
ln -s $OKERNEL/dts/am335x-boneblack.dtb
ln -s $OKERNEL/Image
ln -s $UOUT/u-boot-dtb.img
cp $UOUT/arch/arm/dts/am335x-boneblack.dtb am335x-boneblack-pubkey.dtb
lzop Image
$UOUT/tools/mkimage -f sign.its -K am335x-boneblack-pubkey.dtb -k keys -r image.fit
You should see something like this:
FIT description: Beaglebone black
Created: Sun Jun 1 12:50:30 2014
Image 0 (kernel@1)
Description: unavailable
Created: Sun Jun 1 12:50:30 2014
Type: Kernel Image
Compression: lzo compressed
Data Size: 7790938 Bytes = 7608.34 kB = 7.43 MB
Architecture: ARM
OS: Linux
Load Address: 0x80008000
Entry Point: 0x80008000
Hash algo: sha1
Hash value: c94364646427e10f423837e559898ef02c97b988
Image 1 (fdt@1)
Description: beaglebone-black
Created: Sun Jun 1 12:50:30 2014
Type: Flat Device Tree
Compression: uncompressed
Data Size: 31547 Bytes = 30.81 kB = 0.03 MB
Architecture: ARM
Hash algo: sha1
Hash value: cb09202f889d824f23b8e4404b781be5ad38a68d
Default Configuration: 'conf@1'
Configuration 0 (conf@1)
Description: unavailable
Kernel: kernel@1
FDT: fdt@1
Now am335x-boneblack-pubkey.dtb contains the public key and image.fit contains
the signed kernel. Jump to step 6 if you like, or continue reading to increase
your understanding.
You can also run fit_check_sign to check it:
$UOUT/tools/fit_check_sign -f image.fit -k am335x-boneblack-pubkey.dtb
which results in:
Verifying Hash Integrity ... sha1,rsa2048:dev+
## Loading kernel from FIT Image at 7fc6ee469000 ...
Using 'conf@1' configuration
Verifying Hash Integrity ...
sha1,rsa2048:dev+
OK
Trying 'kernel@1' kernel subimage
Description: unavailable
Created: Sun Jun 1 12:50:30 2014
Type: Kernel Image
Compression: lzo compressed
Data Size: 7790938 Bytes = 7608.34 kB = 7.43 MB
Architecture: ARM
OS: Linux
Load Address: 0x80008000
Entry Point: 0x80008000
Hash algo: sha1
Hash value: c94364646427e10f423837e559898ef02c97b988
Verifying Hash Integrity ...
sha1+
OK
Unimplemented compression type 4
## Loading fdt from FIT Image at 7fc6ee469000 ...
Using 'conf@1' configuration
Trying 'fdt@1' fdt subimage
Description: beaglebone-black
Created: Sun Jun 1 12:50:30 2014
Type: Flat Device Tree
Compression: uncompressed
Data Size: 31547 Bytes = 30.81 kB = 0.03 MB
Architecture: ARM
Hash algo: sha1
Hash value: cb09202f889d824f23b8e4404b781be5ad38a68d
Verifying Hash Integrity ...
sha1+
OK
Loading Flat Device Tree ... OK
## Loading ramdisk from FIT Image at 7fc6ee469000 ...
Using 'conf@1' configuration
Could not find subimage node
Signature check OK
At the top, you see "sha1,rsa2048:dev+". This means that it checked an RSA key
of size 2048 bits using SHA1 as the hash algorithm. The key name checked was
'dev' and the '+' means that it verified. If it showed '-' that would be bad.
Once the configuration is verified it is then possible to rely on the hashes
in each image referenced by that configuration. So fit_check_sign goes on to
load each of the images. We have a kernel and an FDT but no ramkdisk. In each
case fit_check_sign checks the hash and prints sha1+ meaning that the SHA1
hash verified. This means that none of the images has been tampered with.
There is a test in test/vboot which uses U-Boot's sandbox build to verify that
the above flow works.
But it is fun to do this by hand, so you can load image.fit into a hex editor
like ghex, and change a byte in the kernel:
$UOUT/tools/fit_info -f image.fit -n /images/kernel@1 -p data
NAME: kernel@1
LEN: 7790938
OFF: 168
This tells us that the kernel starts at byte offset 168 (decimal) in image.fit
and extends for about 7MB. Try changing a byte at 0x2000 (say) and run
fit_check_sign again. You should see something like:
Verifying Hash Integrity ... sha1,rsa2048:dev+
## Loading kernel from FIT Image at 7f5a39571000 ...
Using 'conf@1' configuration
Verifying Hash Integrity ...
sha1,rsa2048:dev+
OK
Trying 'kernel@1' kernel subimage
Description: unavailable
Created: Sun Jun 1 13:09:21 2014
Type: Kernel Image
Compression: lzo compressed
Data Size: 7790938 Bytes = 7608.34 kB = 7.43 MB
Architecture: ARM
OS: Linux
Load Address: 0x80008000
Entry Point: 0x80008000
Hash algo: sha1
Hash value: c94364646427e10f423837e559898ef02c97b988
Verifying Hash Integrity ...
sha1 error
Bad hash value for 'hash@1' hash node in 'kernel@1' image node
Bad Data Hash
## Loading fdt from FIT Image at 7f5a39571000 ...
Using 'conf@1' configuration
Trying 'fdt@1' fdt subimage
Description: beaglebone-black
Created: Sun Jun 1 13:09:21 2014
Type: Flat Device Tree
Compression: uncompressed
Data Size: 31547 Bytes = 30.81 kB = 0.03 MB
Architecture: ARM
Hash algo: sha1
Hash value: cb09202f889d824f23b8e4404b781be5ad38a68d
Verifying Hash Integrity ...
sha1+
OK
Loading Flat Device Tree ... OK
## Loading ramdisk from FIT Image at 7f5a39571000 ...
Using 'conf@1' configuration
Could not find subimage node
Signature check Bad (error 1)
It has detected the change in the kernel.
You can also be sneaky and try to switch images, using the libfdt utilities
that come with dtc (package name is device-tree-compiler but you will need a
recent version like 1.4:
dtc -v
Version: DTC 1.4.0
First we can check which nodes are actually hashed by the configuration:
fdtget -l image.fit /
images
configurations
fdtget -l image.fit /configurations
conf@1
fdtget -l image.fit /configurations/conf@1
signature@1
fdtget -p image.fit /configurations/conf@1/signature@1
hashed-strings
hashed-nodes
timestamp
signer-version
signer-name
value
algo
key-name-hint
sign-images
fdtget image.fit /configurations/conf@1/signature@1 hashed-nodes
/ /configurations/conf@1 /images/fdt@1 /images/fdt@1/hash@1 /images/kernel@1 /images/kernel@1/hash@1
This gives us a bit of a look into the signature that mkimage added. Note you
can also use fdtdump to list the entire device tree.
Say we want to change the kernel that this configuration uses
(/images/kernel@1). We could just put a new kernel in the image, but we will
need to change the hash to match. Let's simulate that by changing a byte of
the hash:
fdtget -tx image.fit /images/kernel@1/hash@1 value
c9436464 6427e10f 423837e5 59898ef0 2c97b988
fdtput -tx image.fit /images/kernel@1/hash@1 value c9436464 6427e10f 423837e5 59898ef0 2c97b981
Now check it again:
$UOUT/tools/fit_check_sign -f image.fit -k am335x-boneblack-pubkey.dtb
Verifying Hash Integrity ... sha1,rsa2048:devrsa_verify_with_keynode: RSA failed to verify: -13
rsa_verify_with_keynode: RSA failed to verify: -13
-
Failed to verify required signature 'key-dev'
Signature check Bad (error 1)
This time we don't even get as far as checking the images, since the
configuration signature doesn't match. We can't change any hashes without the
signature check noticing. The configuration is essentially locked. U-Boot has
a public key for which it requires a match, and will not permit the use of any
configuration that does not match that public key. The only way the
configuration will match is if it was signed by the matching private key.
It would also be possible to add a new signature node that does match your new
configuration. But that won't work since you are not allowed to change the
configuration in any way. Try it with a fresh (valid) image if you like by
running the mkimage link again. Then:
fdtput -p image.fit /configurations/conf@1/signature@2 value fred
$UOUT/tools/fit_check_sign -f image.fit -k am335x-boneblack-pubkey.dtb
Verifying Hash Integrity ... -
sha1,rsa2048:devrsa_verify_with_keynode: RSA failed to verify: -13
rsa_verify_with_keynode: RSA failed to verify: -13
-
Failed to verify required signature 'key-dev'
Signature check Bad (error 1)
Of course it would be possible to add an entirely new configuration and boot
with that, but it still needs to be signed, so it won't help.
6. Put the public key into U-Boot's image
-----------------------------------------
Having confirmed that the signature is doing its job, let's try it out in
U-Boot on the board. U-Boot needs access to the public key corresponding to
the private key that you signed with so that it can verify any kernels that
you sign.
cd $UBOOT
make O=b/am335x_boneblack_vboot EXT_DTB=${WORK}/am335x-boneblack-pubkey.dtb
Here we are overrriding the normal device tree file with our one, which
contains the public key.
Now you have a special U-Boot image with the public key. It can verify can
kernel that you sign with the private key as in step 5.
If you like you can take a look at the public key information that mkimage
added to U-Boot's device tree:
fdtget -p am335x-boneblack-pubkey.dtb /signature/key-dev
required
algo
rsa,r-squared
rsa,modulus
rsa,n0-inverse
rsa,num-bits
key-name-hint
This has information about the key and some pre-processed values which U-Boot
can use to verify against it. These values are obtained from the public key
certificate by mkimage, but require quite a bit of code to generate. To save
code space in U-Boot, the information is extracted and written in raw form for
U-Boot to easily use. The same mechanism is used in Google's Chrome OS.
Notice the 'required' property. This marks the key as required - U-Boot will
not boot any image that does not verify against this key.
7. Put U-Boot and the kernel onto the board
-------------------------------------------
The method here varies depending on how you are booting. For this example we
are booting from an micro-SD card with two partitions, one for U-Boot and one
for Linux. Put it into your machine and write U-Boot and the kernel to it.
Here the card is /dev/sde:
cd $WORK
export UDEV=/dev/sde1 # Change thes two lines to the correct device
export KDEV=/dev/sde2
sudo mount $UDEV /mnt/tmp && sudo cp $UOUT/u-boot-dtb.img /mnt/tmp/u-boot.img && sleep 1 && sudo umount $UDEV
sudo mount $KDEV /mnt/tmp && sudo cp $WORK/image.fit /mnt/tmp/boot/image.fit && sleep 1 && sudo umount $KDEV
8. Try it
---------
Boot the board using the commands below:
setenv bootargs console=ttyO0,115200n8 quiet root=/dev/mmcblk0p2 ro rootfstype=ext4 rootwait
ext2load mmc 0:2 82000000 /boot/image.fit
bootm 82000000
You should then see something like this:
U-Boot# setenv bootargs console=ttyO0,115200n8 quiet root=/dev/mmcblk0p2 ro rootfstype=ext4 rootwait
U-Boot# ext2load mmc 0:2 82000000 /boot/image.fit
7824930 bytes read in 589 ms (12.7 MiB/s)
U-Boot# bootm 82000000
## Loading kernel from FIT Image at 82000000 ...
Using 'conf@1' configuration
Verifying Hash Integrity ... sha1,rsa2048:dev+ OK
Trying 'kernel@1' kernel subimage
Description: unavailable
Created: 2014-06-01 19:32:54 UTC
Type: Kernel Image
Compression: lzo compressed
Data Start: 0x820000a8
Data Size: 7790938 Bytes = 7.4 MiB
Architecture: ARM
OS: Linux
Load Address: 0x80008000
Entry Point: 0x80008000
Hash algo: sha1
Hash value: c94364646427e10f423837e559898ef02c97b988
Verifying Hash Integrity ... sha1+ OK
## Loading fdt from FIT Image at 82000000 ...
Using 'conf@1' configuration
Trying 'fdt@1' fdt subimage
Description: beaglebone-black
Created: 2014-06-01 19:32:54 UTC
Type: Flat Device Tree
Compression: uncompressed
Data Start: 0x8276e2ec
Data Size: 31547 Bytes = 30.8 KiB
Architecture: ARM
Hash algo: sha1
Hash value: cb09202f889d824f23b8e4404b781be5ad38a68d
Verifying Hash Integrity ... sha1+ OK
Booting using the fdt blob at 0x8276e2ec
Uncompressing Kernel Image ... OK
Loading Device Tree to 8fff5000, end 8ffffb3a ... OK
Starting kernel ...
[ 0.582377] omap_init_mbox: hwmod doesn't have valid attrs
[ 2.589651] musb-hdrc musb-hdrc.0.auto: Failed to request rx1.
[ 2.595830] musb-hdrc musb-hdrc.0.auto: musb_init_controller failed with status -517
[ 2.606470] musb-hdrc musb-hdrc.1.auto: Failed to request rx1.
[ 2.612723] musb-hdrc musb-hdrc.1.auto: musb_init_controller failed with status -517
[ 2.940808] drivers/rtc/hctosys.c: unable to open rtc device (rtc0)
[ 7.248889] libphy: PHY 4a101000.mdio:01 not found
[ 7.253995] net eth0: phy 4a101000.mdio:01 not found on slave 1
systemd-fsck[83]: Angstrom: clean, 50607/218160 files, 306348/872448 blocks
.---O---.
| | .-. o o
| | |-----.-----.-----.| | .----..-----.-----.
| | | __ | ---'| '--.| .-'| | |
| | | | | |--- || --'| | | ' | | | |
'---'---'--'--'--. |-----''----''--' '-----'-'-'-'
-' |
'---'
The Angstrom Distribution beaglebone ttyO0
Angstrom v2012.12 - Kernel 3.14.1+
beaglebone login:
At this point your kernel has been verified and you can be sure that it is one
that you signed. As an exercise, try changing image.fit as in step 5 and see
what happens.
Further Improvements
--------------------
Several of the steps here can be easily automated. In particular it would be
capital if signing and packaging a kernel were easy, perhaps a simple make
target in the kernel.
Some mention of how to use multiple .dtb files in a FIT might be useful.
U-Boot's verified boot mechanism has not had a robust and independent security
review. Such a review should look at the implementation and its resistance to
attacks.
Perhaps the verified boot feature could could be integrated into the Amstrom
distribution.
Simon Glass
sjg@chromium.org
2-June-14

191
u-boot/doc/uImage.FIT/command_syntax_extensions.txt Normal file
View File

@@ -0,0 +1,191 @@
Command syntax extensions for the new uImage format
===================================================
Author: Bartlomiej Sieka <tur@semihalf.com>
With the introduction of the new uImage format, bootm command (and other
commands as well) have to understand new syntax of the arguments. This is
necessary in order to specify objects contained in the new uImage, on which
bootm has to operate. This note attempts to first summarize bootm usage
scenarios, and then introduces new argument syntax.
bootm usage scenarios
---------------------
Below is a summary of bootm usage scenarios, focused on booting a PowerPC
Linux kernel. The purpose of the following list is to document a complete list
of supported bootm usages.
Note: U-Boot supports two methods of booting a PowerPC Linux kernel: old way,
i.e., without passing the Flattened Device Tree (FDT), and new way, where the
kernel is passed a pointer to the FDT. The boot method is indicated for each
scenario.
1. bootm boot image at the current address, equivalent to 2,3,8
Old uImage:
2. bootm <addr1> /* single image at <addr1> */
3. bootm <addr1> /* multi-image at <addr1> */
4. bootm <addr1> - /* multi-image at <addr1> */
5. bootm <addr1> <addr2> /* single image at <addr1> */
6. bootm <addr1> <addr2> <addr3> /* single image at <addr1> */
7. bootm <addr1> - <addr3> /* single image at <addr1> */
New uImage:
8. bootm <addr1>
9. bootm [<addr1>]:<subimg1>
10. bootm [<addr1>]#<conf>
11. bootm [<addr1>]:<subimg1> [<addr2>]:<subimg2>
12. bootm [<addr1>]:<subimg1> [<addr2>]:<subimg2> [<addr3>]:<subimg3>
13. bootm [<addr1>]:<subimg1> [<addr2>]:<subimg2> <addr3>
14. bootm [<addr1>]:<subimg1> - [<addr3>]:<subimg3>
15. bootm [<addr1>]:<subimg1> - <addr3>
Ad. 1. This is equivalent to cases 2,3,8, depending on the type of image at
the current image address.
- boot method: see cases 2,3,8
Ad. 2. Boot kernel image located at <addr1>.
- boot method: non-FDT
Ad. 3. First and second components of the image at <addr1> are assumed to be a
kernel and a ramdisk, respectively. The kernel is booted with initrd loaded
with the ramdisk from the image.
- boot method: depends on the number of components at <addr1>, and on whether
U-Boot is compiled with OF support:
| 2 components | 3 components |
| (kernel, initrd) | (kernel, initrd, fdt) |
---------------------------------------------------------------------
#ifdef CONFIG_OF_* | non-FDT | FDT |
#ifndef CONFIG_OF_* | non-FDT | non-FDT |
Ad. 4. Similar to case 3, but the kernel is booted without initrd. Second
component of the multi-image is irrelevant (it can be a dummy, 1-byte file).
- boot method: see case 3
Ad. 5. Boot kernel image located at <addr1> with initrd loaded with ramdisk
from the image at <addr2>.
- boot method: non-FDT
Ad. 6. <addr1> is the address of a kernel image, <addr2> is the address of a
ramdisk image, and <addr3> is the address of a FDT binary blob. Kernel is
booted with initrd loaded with ramdisk from the image at <addr2>.
- boot method: FDT
Ad. 7. <addr1> is the address of a kernel image and <addr3> is the address of
a FDT binary blob. Kernel is booted without initrd.
- boot method: FDT
Ad. 8. Image at <addr1> is assumed to contain a default configuration, which
is booted.
- boot method: FDT or non-FDT, depending on whether the default configuration
defines FDT
Ad. 9. Similar to case 2: boot kernel stored in <subimg1> from the image at
address <addr1>.
- boot method: non-FDT
Ad. 10. Boot configuration <conf> from the image at <addr1>.
- boot method: FDT or non-FDT, depending on whether the configuration given
defines FDT
Ad. 11. Equivalent to case 5: boot kernel stored in <subimg1> from the image
at <addr1> with initrd loaded with ramdisk <subimg2> from the image at
<addr2>.
- boot method: non-FDT
Ad. 12. Equivalent to case 6: boot kernel stored in <subimg1> from the image
at <addr1> with initrd loaded with ramdisk <subimg2> from the image at
<addr2>, and pass FDT blob <subimg3> from the image at <addr3>.
- boot method: FDT
Ad. 13. Similar to case 12, the difference being that <addr3> is the address
of FDT binary blob that is to be passed to the kernel.
- boot method: FDT
Ad. 14. Equivalent to case 7: boot kernel stored in <subimg1> from the image
at <addr1>, without initrd, and pass FDT blob <subimg3> from the image at
<addr3>.
- boot method: FDT
Ad. 15. Similar to case 14, the difference being that <addr3> is the address
of the FDT binary blob that is to be passed to the kernel.
- boot method: FDT
New uImage argument syntax
--------------------------
New uImage support introduces two new forms for bootm arguments, with the
following syntax:
- new uImage sub-image specification
<addr>:<sub-image unit_name>
- new uImage configuration specification
<addr>#<configuration unit_name>
Examples:
- boot kernel "kernel@1" stored in a new uImage located at 200000:
bootm 200000:kernel@1
- boot configuration "cfg@1" from a new uImage located at 200000:
bootm 200000#cfg@1
- boot "kernel@1" from a new uImage at 200000 with initrd "ramdisk@2" found in
some other new uImage stored at address 800000:
bootm 200000:kernel@1 800000:ramdisk@2
- boot "kernel@2" from a new uImage at 200000, with initrd "ramdisk@1" and FDT
"fdt@1", both stored in some other new uImage located at 800000:
bootm 200000:kernel@1 800000:ramdisk@1 800000:fdt@1
- boot kernel "kernel@2" with initrd "ramdisk@2", both stored in a new uImage
at address 200000, with a raw FDT blob stored at address 600000:
bootm 200000:kernel@2 200000:ramdisk@2 600000
- boot kernel "kernel@2" from new uImage at 200000 with FDT "fdt@1" from the
same new uImage:
bootm 200000:kernel@2 - 200000:fdt@1
Note on current image address
-----------------------------
When bootm is called without arguments, the image at current image address is
booted. The current image address is the address set most recently by a load
command, etc, and is by default equal to CONFIG_SYS_LOAD_ADDR. For example, consider
the following commands:
tftp 200000 /tftpboot/kernel
bootm
Last command is equivalent to:
bootm 200000
In case of the new uImage argument syntax, the address portion of any argument
can be omitted. If <addr3> is omitted, then it is assumed that image at
<addr2> should be used. Similarly, when <addr2> is omitted, it is assumed that
image at <addr1> should be used. If <addr1> is omitted, it is assumed that the
current image address is to be used. For example, consider the following
commands:
tftp 200000 /tftpboot/uImage
bootm :kernel@1
Last command is equivalent to:
bootm 200000:kernel@1
tftp 200000 /tftpboot/uImage
bootm 400000:kernel@1 :ramdisk@1
Last command is equivalent to:
bootm 400000:kernel@1 400000:ramdisk@1
tftp 200000 /tftpboot/uImage
bootm :kernel@1 400000:ramdisk@1 :fdt@1
Last command is equivalent to:
bootm 200000:kernel@1 400000:ramdisk@1 400000:fdt@1

300
u-boot/doc/uImage.FIT/howto.txt Normal file
View File

@@ -0,0 +1,300 @@
How to use images in the new image format
=========================================
Author: Bartlomiej Sieka <tur@semihalf.com>
Overview
--------
The new uImage format allows more flexibility in handling images of various
types (kernel, ramdisk, etc.), it also enhances integrity protection of images
with sha1 and md5 checksums.
Two auxiliary tools are needed on the development host system in order to
create an uImage in the new format: mkimage and dtc, although only one
(mkimage) is invoked directly. dtc is called from within mkimage and operates
behind the scenes, but needs to be present in the $PATH nevertheless. It is
important that the dtc used has support for binary includes -- refer to
git://git.kernel.org/pub/scm/utils/dtc/dtc.git
for its latest version. mkimage (together with dtc) takes as input
an image source file, which describes the contents of the image and defines
its various properties used during booting. By convention, image source file
has the ".its" extension, also, the details of its format are given in
doc/uImage.FIT/source_file_format.txt. The actual data that is to be included in
the uImage (kernel, ramdisk, etc.) is specified in the image source file in the
form of paths to appropriate data files. The outcome of the image creation
process is a binary file (by convention with the ".itb" extension) that
contains all the referenced data (kernel, ramdisk, etc.) and other information
needed by U-Boot to handle the uImage properly. The uImage file is then
transferred to the target (e.g., via tftp) and booted using the bootm command.
To summarize the prerequisites needed for new uImage creation:
- mkimage
- dtc (with support for binary includes)
- image source file (*.its)
- image data file(s)
Here's a graphical overview of the image creation and booting process:
image source file mkimage + dtc transfer to target
+ ---------------> image file --------------------> bootm
image data file(s)
Example 1 -- old-style (non-FDT) kernel booting
-----------------------------------------------
Consider a simple scenario, where a PPC Linux kernel built from sources on the
development host is to be booted old-style (non-FDT) by U-Boot on an embedded
target. Assume that the outcome of the build is vmlinux.bin.gz, a file which
contains a gzip-compressed PPC Linux kernel (the only data file in this case).
The uImage can be produced using the image source file
doc/uImage.FIT/kernel.its (note that kernel.its assumes that vmlinux.bin.gz is
in the current working directory; if desired, an alternative path can be
specified in the kernel.its file). Here's how to create the image and inspect
its contents:
[on the host system]
$ mkimage -f kernel.its kernel.itb
DTC: dts->dtb on file "kernel.its"
$
$ mkimage -l kernel.itb
FIT description: Simple image with single Linux kernel
Created: Tue Mar 11 17:26:15 2008
Image 0 (kernel@1)
Description: Vanilla Linux kernel
Type: Kernel Image
Compression: gzip compressed
Data Size: 943347 Bytes = 921.24 kB = 0.90 MB
Architecture: PowerPC
OS: Linux
Load Address: 0x00000000
Entry Point: 0x00000000
Hash algo: crc32
Hash value: 2ae2bb40
Hash algo: sha1
Hash value: 3c200f34e2c226ddc789240cca0c59fc54a67cf4
Default Configuration: 'config@1'
Configuration 0 (config@1)
Description: Boot Linux kernel
Kernel: kernel@1
The resulting image file kernel.itb can be now transferred to the target,
inspected and booted (note that first three U-Boot commands below are shown
for completeness -- they are part of the standard booting procedure and not
specific to the new image format).
[on the target system]
=> print nfsargs
nfsargs=setenv bootargs root=/dev/nfs rw nfsroot=${serverip}:${rootpath}
=> print addip
addip=setenv bootargs ${bootargs} ip=${ipaddr}:${serverip}:${gatewayip}:${netmask}:${hostname}:${netdev}:off panic=1
=> run nfsargs addip
=> tftp 900000 /path/to/tftp/location/kernel.itb
Using FEC device
TFTP from server 192.168.1.1; our IP address is 192.168.160.5
Filename '/path/to/tftp/location/kernel.itb'.
Load address: 0x900000
Loading: #################################################################
done
Bytes transferred = 944464 (e6950 hex)
=> iminfo
## Checking Image at 00900000 ...
FIT image found
FIT description: Simple image with single Linux kernel
Created: 2008-03-11 16:26:15 UTC
Image 0 (kernel@1)
Description: Vanilla Linux kernel
Type: Kernel Image
Compression: gzip compressed
Data Start: 0x009000e0
Data Size: 943347 Bytes = 921.2 kB
Architecture: PowerPC
OS: Linux
Load Address: 0x00000000
Entry Point: 0x00000000
Hash algo: crc32
Hash value: 2ae2bb40
Hash algo: sha1
Hash value: 3c200f34e2c226ddc789240cca0c59fc54a67cf4
Default Configuration: 'config@1'
Configuration 0 (config@1)
Description: Boot Linux kernel
Kernel: kernel@1
=> bootm
## Booting kernel from FIT Image at 00900000 ...
Using 'config@1' configuration
Trying 'kernel@1' kernel subimage
Description: Vanilla Linux kernel
Type: Kernel Image
Compression: gzip compressed
Data Start: 0x009000e0
Data Size: 943347 Bytes = 921.2 kB
Architecture: PowerPC
OS: Linux
Load Address: 0x00000000
Entry Point: 0x00000000
Hash algo: crc32
Hash value: 2ae2bb40
Hash algo: sha1
Hash value: 3c200f34e2c226ddc789240cca0c59fc54a67cf4
Verifying Hash Integrity ... crc32+ sha1+ OK
Uncompressing Kernel Image ... OK
Memory BAT mapping: BAT2=256Mb, BAT3=0Mb, residual: 0Mb
Linux version 2.4.25 (m8@hekate) (gcc version 4.0.0 (DENX ELDK 4.0 4.0.0)) #2 czw lip 5 17:56:18 CEST 2007
On node 0 totalpages: 65536
zone(0): 65536 pages.
zone(1): 0 pages.
zone(2): 0 pages.
Kernel command line: root=/dev/nfs rw nfsroot=192.168.1.1:/opt/eldk-4.1/ppc_6xx ip=192.168.160.5:192.168.1.1::255.255.0.0:lite5200b:eth0:off panic=1
Calibrating delay loop... 307.20 BogoMIPS
Example 2 -- new-style (FDT) kernel booting
-------------------------------------------
Consider another simple scenario, where a PPC Linux kernel is to be booted
new-style, i.e., with a FDT blob. In this case there are two prerequisite data
files: vmlinux.bin.gz (Linux kernel) and target.dtb (FDT blob). The uImage can
be produced using image source file doc/uImage.FIT/kernel_fdt.its like this
(note again, that both prerequisite data files are assumed to be present in
the current working directory -- image source file kernel_fdt.its can be
modified to take the files from some other location if needed):
[on the host system]
$ mkimage -f kernel_fdt.its kernel_fdt.itb
DTC: dts->dtb on file "kernel_fdt.its"
$
$ mkimage -l kernel_fdt.itb
FIT description: Simple image with single Linux kernel and FDT blob
Created: Tue Mar 11 16:29:22 2008
Image 0 (kernel@1)
Description: Vanilla Linux kernel
Type: Kernel Image
Compression: gzip compressed
Data Size: 1092037 Bytes = 1066.44 kB = 1.04 MB
Architecture: PowerPC
OS: Linux
Load Address: 0x00000000
Entry Point: 0x00000000
Hash algo: crc32
Hash value: 2c0cc807
Hash algo: sha1
Hash value: 264b59935470e42c418744f83935d44cdf59a3bb
Image 1 (fdt@1)
Description: Flattened Device Tree blob
Type: Flat Device Tree
Compression: uncompressed
Data Size: 16384 Bytes = 16.00 kB = 0.02 MB
Architecture: PowerPC
Hash algo: crc32
Hash value: 0d655d71
Hash algo: sha1
Hash value: 25ab4e15cd4b8a5144610394560d9c318ce52def
Default Configuration: 'conf@1'
Configuration 0 (conf@1)
Description: Boot Linux kernel with FDT blob
Kernel: kernel@1
FDT: fdt@1
The resulting image file kernel_fdt.itb can be now transferred to the target,
inspected and booted:
[on the target system]
=> tftp 900000 /path/to/tftp/location/kernel_fdt.itb
Using FEC device
TFTP from server 192.168.1.1; our IP address is 192.168.160.5
Filename '/path/to/tftp/location/kernel_fdt.itb'.
Load address: 0x900000
Loading: #################################################################
###########
done
Bytes transferred = 1109776 (10ef10 hex)
=> iminfo
## Checking Image at 00900000 ...
FIT image found
FIT description: Simple image with single Linux kernel and FDT blob
Created: 2008-03-11 15:29:22 UTC
Image 0 (kernel@1)
Description: Vanilla Linux kernel
Type: Kernel Image
Compression: gzip compressed
Data Start: 0x009000ec
Data Size: 1092037 Bytes = 1 MB
Architecture: PowerPC
OS: Linux
Load Address: 0x00000000
Entry Point: 0x00000000
Hash algo: crc32
Hash value: 2c0cc807
Hash algo: sha1
Hash value: 264b59935470e42c418744f83935d44cdf59a3bb
Image 1 (fdt@1)
Description: Flattened Device Tree blob
Type: Flat Device Tree
Compression: uncompressed
Data Start: 0x00a0abdc
Data Size: 16384 Bytes = 16 kB
Architecture: PowerPC
Hash algo: crc32
Hash value: 0d655d71
Hash algo: sha1
Hash value: 25ab4e15cd4b8a5144610394560d9c318ce52def
Default Configuration: 'conf@1'
Configuration 0 (conf@1)
Description: Boot Linux kernel with FDT blob
Kernel: kernel@1
FDT: fdt@1
=> bootm
## Booting kernel from FIT Image at 00900000 ...
Using 'conf@1' configuration
Trying 'kernel@1' kernel subimage
Description: Vanilla Linux kernel
Type: Kernel Image
Compression: gzip compressed
Data Start: 0x009000ec
Data Size: 1092037 Bytes = 1 MB
Architecture: PowerPC
OS: Linux
Load Address: 0x00000000
Entry Point: 0x00000000
Hash algo: crc32
Hash value: 2c0cc807
Hash algo: sha1
Hash value: 264b59935470e42c418744f83935d44cdf59a3bb
Verifying Hash Integrity ... crc32+ sha1+ OK
Uncompressing Kernel Image ... OK
## Flattened Device Tree from FIT Image at 00900000
Using 'conf@1' configuration
Trying 'fdt@1' FDT blob subimage
Description: Flattened Device Tree blob
Type: Flat Device Tree
Compression: uncompressed
Data Start: 0x00a0abdc
Data Size: 16384 Bytes = 16 kB
Architecture: PowerPC
Hash algo: crc32
Hash value: 0d655d71
Hash algo: sha1
Hash value: 25ab4e15cd4b8a5144610394560d9c318ce52def
Verifying Hash Integrity ... crc32+ sha1+ OK
Booting using the fdt blob at 0xa0abdc
Loading Device Tree to 007fc000, end 007fffff ... OK
[ 0.000000] Using lite5200 machine description
[ 0.000000] Linux version 2.6.24-rc6-gaebecdfc (m8@hekate) (gcc version 4.0.0 (DENX ELDK 4.1 4.0.0)) #1 Sat Jan 12 15:38:48 CET 2008
Example 3 -- advanced booting
-----------------------------
Refer to doc/uImage.FIT/multi.its for an image source file that allows more
sophisticated booting scenarios (multiple kernels, ramdisks and fdt blobs).

87
u-boot/doc/uImage.FIT/kernel.its Normal file
View File

@@ -0,0 +1,87 @@
/*
* Simple U-Boot uImage source file containing a single kernel
*/
/dts-v1/;
/ {
description = "Simple image with single Linux kernel";
#address-cells = <1>;
images {
kernel@1 {
description = "Vanilla Linux kernel";
data = /incbin/("./vmlinux.bin.gz");
type = "kernel";
arch = "ppc";
os = "linux";
compression = "gzip";
load = <00000000>;
entry = <00000000>;
hash@1 {
algo = "crc32";
};
hash@2 {
algo = "sha1";
};
};
};
configurations {
default = "config@1";
config@1 {
description = "Boot Linux kernel";
kernel = "kernel@1";
};
};
};
For x86 a setup node is also required: see x86-fit-boot.txt.
/dts-v1/;
/ {
description = "Simple image with single Linux kernel on x86";
#address-cells = <1>;
images {
kernel@1 {
description = "Vanilla Linux kernel";
data = /incbin/("./image.bin.lzo");
type = "kernel";
arch = "x86";
os = "linux";
compression = "lzo";
load = <0x01000000>;
entry = <0x00000000>;
hash@2 {
algo = "sha1";
};
};
setup@1 {
description = "Linux setup.bin";
data = /incbin/("./setup.bin");
type = "x86_setup";
arch = "x86";
os = "linux";
compression = "none";
load = <0x00090000>;
entry = <0x00090000>;
hash@2 {
algo = "sha1";
};
};
};
configurations {
default = "config@1";
config@1 {
description = "Boot Linux kernel";
kernel = "kernel@1";
setup = "setup@1";
};
};
};

51
u-boot/doc/uImage.FIT/kernel_fdt.its Normal file
View File

@@ -0,0 +1,51 @@
/*
* Simple U-Boot uImage source file containing a single kernel and FDT blob
*/
/dts-v1/;
/ {
description = "Simple image with single Linux kernel and FDT blob";
#address-cells = <1>;
images {
kernel@1 {
description = "Vanilla Linux kernel";
data = /incbin/("./vmlinux.bin.gz");
type = "kernel";
arch = "ppc";
os = "linux";
compression = "gzip";
load = <00000000>;
entry = <00000000>;
hash@1 {
algo = "crc32";
};
hash@2 {
algo = "sha1";
};
};
fdt@1 {
description = "Flattened Device Tree blob";
data = /incbin/("./target.dtb");
type = "flat_dt";
arch = "ppc";
compression = "none";
hash@1 {
algo = "crc32";
};
hash@2 {
algo = "sha1";
};
};
};
configurations {
default = "conf@1";
conf@1 {
description = "Boot Linux kernel with FDT blob";
kernel = "kernel@1";
fdt = "fdt@1";
};
};
};

67
u-boot/doc/uImage.FIT/multi-with-fpga.its Normal file
View File

@@ -0,0 +1,67 @@
/*
* U-Boot uImage source file with multiple kernels, ramdisks and FDT blobs
* This example makes use of the 'loadables' field
*/
/dts-v1/;
/ {
description = "Configuration to load fpga before Kernel";
#address-cells = <1>;
images {
fdt@1 {
description = "zc706";
data = /incbin/("/tftpboot/devicetree.dtb");
type = "flat_dt";
arch = "arm";
compression = "none";
load = <0x10000000>;
hash@1 {
algo = "md5";
};
};
fpga@1 {
description = "FPGA";
data = /incbin/("/tftpboot/download.bit");
type = "fpga";
arch = "arm";
compression = "none";
load = <0x30000000>;
hash@1 {
algo = "md5";
};
};
linux_kernel@1 {
description = "Linux";
data = /incbin/("/tftpboot/zImage");
type = "kernel";
arch = "arm";
os = "linux";
compression = "none";
load = <0x8000>;
entry = <0x8000>;
hash@1 {
algo = "md5";
};
};
};
configurations {
default = "config@2";
config@1 {
description = "Linux";
kernel = "linux_kernel@1";
fdt = "fdt@1";
};
config@2 {
description = "Linux with fpga";
kernel = "linux_kernel@1";
fdt = "fdt@1";
fpga = "fpga@1";
};
};
};

89
u-boot/doc/uImage.FIT/multi-with-loadables.its Normal file
View File

@@ -0,0 +1,89 @@
/*
* U-Boot uImage source file with multiple kernels, ramdisks and FDT blobs
* This example makes use of the 'loadables' field
*/
/dts-v1/;
/ {
description = "Configuration to load a Xen Kernel";
#address-cells = <1>;
images {
xen_kernel@1 {
description = "xen binary";
data = /incbin/("./xen");
type = "kernel";
arch = "arm";
os = "linux";
compression = "none";
load = <0xa0000000>;
entry = <0xa0000000>;
hash@1 {
algo = "md5";
};
};
fdt@1 {
description = "xexpress-ca15 tree blob";
data = /incbin/("./vexpress-v2p-ca15-tc1.dtb");
type = "flat_dt";
arch = "arm";
compression = "none";
load = <0xb0000000>;
hash@1 {
algo = "md5";
};
};
fdt@2 {
description = "xexpress-ca15 tree blob";
data = /incbin/("./vexpress-v2p-ca15-tc1.dtb");
type = "flat_dt";
arch = "arm";
compression = "none";
load = <0xb0400000>;
hash@1 {
algo = "md5";
};
};
linux_kernel@1 {
description = "Linux Image";
data = /incbin/("./Image");
type = "kernel";
arch = "arm";
os = "linux";
compression = "none";
load = <0xa0000000>;
entry = <0xa0000000>;
hash@1 {
algo = "md5";
};
};
};
configurations {
default = "config@2";
config@1 {
description = "Just plain Linux";
kernel = "linux_kernel@1";
fdt = "fdt@1";
};
config@2 {
description = "Xen one loadable";
kernel = "xen_kernel@1";
fdt = "fdt@1";
loadables = "linux_kernel@1";
};
config@3 {
description = "Xen two loadables";
kernel = "xen_kernel@1";
fdt = "fdt@1";
loadables = "linux_kernel@1", "fdt@2";
};
};
};

133
u-boot/doc/uImage.FIT/multi.its Normal file
View File

@@ -0,0 +1,133 @@
/*
* U-Boot uImage source file with multiple kernels, ramdisks and FDT blobs
*/
/dts-v1/;
/ {
description = "Various kernels, ramdisks and FDT blobs";
#address-cells = <1>;
images {
kernel@1 {
description = "vanilla-2.6.23";
data = /incbin/("./vmlinux.bin.gz");
type = "kernel";
arch = "ppc";
os = "linux";
compression = "gzip";
load = <00000000>;
entry = <00000000>;
hash@1 {
algo = "md5";
};
hash@2 {
algo = "sha1";
};
};
kernel@2 {
description = "2.6.23-denx";
data = /incbin/("./2.6.23-denx.bin.gz");
type = "kernel";
arch = "ppc";
os = "linux";
compression = "gzip";
load = <00000000>;
entry = <00000000>;
hash@1 {
algo = "sha1";
};
};
kernel@3 {
description = "2.4.25-denx";
data = /incbin/("./2.4.25-denx.bin.gz");
type = "kernel";
arch = "ppc";
os = "linux";
compression = "gzip";
load = <00000000>;
entry = <00000000>;
hash@1 {
algo = "md5";
};
};
ramdisk@1 {
description = "eldk-4.2-ramdisk";
data = /incbin/("./eldk-4.2-ramdisk");
type = "ramdisk";
arch = "ppc";
os = "linux";
compression = "gzip";
load = <00000000>;
entry = <00000000>;
hash@1 {
algo = "sha1";
};
};
ramdisk@2 {
description = "eldk-3.1-ramdisk";
data = /incbin/("./eldk-3.1-ramdisk");
type = "ramdisk";
arch = "ppc";
os = "linux";
compression = "gzip";
load = <00000000>;
entry = <00000000>;
hash@1 {
algo = "crc32";
};
};
fdt@1 {
description = "tqm5200-fdt";
data = /incbin/("./tqm5200.dtb");
type = "flat_dt";
arch = "ppc";
compression = "none";
hash@1 {
algo = "crc32";
};
};
fdt@2 {
description = "tqm5200s-fdt";
data = /incbin/("./tqm5200s.dtb");
type = "flat_dt";
arch = "ppc";
compression = "none";
load = <00700000>;
hash@1 {
algo = "sha1";
};
};
};
configurations {
default = "config@1";
config@1 {
description = "tqm5200 vanilla-2.6.23 configuration";
kernel = "kernel@1";
ramdisk = "ramdisk@1";
fdt = "fdt@1";
};
config@2 {
description = "tqm5200s denx-2.6.23 configuration";
kernel = "kernel@2";
ramdisk = "ramdisk@1";
fdt = "fdt@2";
};
config@3 {
description = "tqm5200s denx-2.4.25 configuration";
kernel = "kernel@3";
ramdisk = "ramdisk@2";
};
};
};

45
u-boot/doc/uImage.FIT/sign-configs.its Normal file
View File

@@ -0,0 +1,45 @@
/dts-v1/;
/ {
description = "Chrome OS kernel image with one or more FDT blobs";
#address-cells = <1>;
images {
kernel@1 {
data = /incbin/("test-kernel.bin");
type = "kernel_noload";
arch = "sandbox";
os = "linux";
compression = "lzo";
load = <0x4>;
entry = <0x8>;
kernel-version = <1>;
hash@1 {
algo = "sha1";
};
};
fdt@1 {
description = "snow";
data = /incbin/("sandbox-kernel.dtb");
type = "flat_dt";
arch = "sandbox";
compression = "none";
fdt-version = <1>;
hash@1 {
algo = "sha1";
};
};
};
configurations {
default = "conf@1";
conf@1 {
kernel = "kernel@1";
fdt = "fdt@1";
signature@1 {
algo = "sha1,rsa2048";
key-name-hint = "dev";
sign-images = "fdt", "kernel";
};
};
};
};

42
u-boot/doc/uImage.FIT/sign-images.its Normal file
View File

@@ -0,0 +1,42 @@
/dts-v1/;
/ {
description = "Chrome OS kernel image with one or more FDT blobs";
#address-cells = <1>;
images {
kernel@1 {
data = /incbin/("test-kernel.bin");
type = "kernel_noload";
arch = "sandbox";
os = "linux";
compression = "none";
load = <0x4>;
entry = <0x8>;
kernel-version = <1>;
signature@1 {
algo = "sha1,rsa2048";
key-name-hint = "dev";
};
};
fdt@1 {
description = "snow";
data = /incbin/("sandbox-kernel.dtb");
type = "flat_dt";
arch = "sandbox";
compression = "none";
fdt-version = <1>;
signature@1 {
algo = "sha1,rsa2048";
key-name-hint = "dev";
};
};
};
configurations {
default = "conf@1";
conf@1 {
kernel = "kernel@1";
fdt = "fdt@1";
};
};
};

408
u-boot/doc/uImage.FIT/signature.txt Normal file
View File

@@ -0,0 +1,408 @@
U-Boot FIT Signature Verification
=================================
Introduction
------------
FIT supports hashing of images so that these hashes can be checked on
loading. This protects against corruption of the image. However it does not
prevent the substitution of one image for another.
The signature feature allows the hash to be signed with a private key such
that it can be verified using a public key later. Provided that the private
key is kept secret and the public key is stored in a non-volatile place,
any image can be verified in this way.
See verified-boot.txt for more general information on verified boot.
Concepts
--------
Some familiarity with public key cryptography is assumed in this section.
The procedure for signing is as follows:
- hash an image in the FIT
- sign the hash with a private key to produce a signature
- store the resulting signature in the FIT
The procedure for verification is:
- read the FIT
- obtain the public key
- extract the signature from the FIT
- hash the image from the FIT
- verify (with the public key) that the extracted signature matches the
hash
The signing is generally performed by mkimage, as part of making a firmware
image for the device. The verification is normally done in U-Boot on the
device.
Algorithms
----------
In principle any suitable algorithm can be used to sign and verify a hash.
At present only one class of algorithms is supported: SHA1 hashing with RSA.
This works by hashing the image to produce a 20-byte hash.
While it is acceptable to bring in large cryptographic libraries such as
openssl on the host side (e.g. mkimage), it is not desirable for U-Boot.
For the run-time verification side, it is important to keep code and data
size as small as possible.
For this reason the RSA image verification uses pre-processed public keys
which can be used with a very small amount of code - just some extraction
of data from the FDT and exponentiation mod n. Code size impact is a little
under 5KB on Tegra Seaboard, for example.
It is relatively straightforward to add new algorithms if required. If
another RSA variant is needed, then it can be added to the table in
image-sig.c. If another algorithm is needed (such as DSA) then it can be
placed alongside rsa.c, and its functions added to the table in image-sig.c
also.
Creating an RSA key pair and certificate
----------------------------------------
To create a new public/private key pair, size 2048 bits:
$ openssl genpkey -algorithm RSA -out keys/dev.key \
-pkeyopt rsa_keygen_bits:2048 -pkeyopt rsa_keygen_pubexp:65537
To create a certificate for this containing the public key:
$ openssl req -batch -new -x509 -key keys/dev.key -out keys/dev.crt
If you like you can look at the public key also:
$ openssl rsa -in keys/dev.key -pubout
Device Tree Bindings
--------------------
The following properties are required in the FIT's signature node(s) to
allow thes signer to operate. These should be added to the .its file.
Signature nodes sit at the same level as hash nodes and are called
signature@1, signature@2, etc.
- algo: Algorithm name (e.g. "sha1,rs2048")
- key-name-hint: Name of key to use for signing. The keys will normally be in
a single directory (parameter -k to mkimage). For a given key <name>, its
private key is stored in <name>.key and the certificate is stored in
<name>.crt.
When the image is signed, the following properties are added (mandatory):
- value: The signature data (e.g. 256 bytes for 2048-bit RSA)
When the image is signed, the following properties are optional:
- timestamp: Time when image was signed (standard Unix time_t format)
- signer-name: Name of the signer (e.g. "mkimage")
- signer-version: Version string of the signer (e.g. "2013.01")
- comment: Additional information about the signer or image
For config bindings (see Signed Configurations below), the following
additional properties are optional:
- sign-images: A list of images to sign, each being a property of the conf
node that contains then. The default is "kernel,fdt" which means that these
two images will be looked up in the config and signed if present.
For config bindings, these properties are added by the signer:
- hashed-nodes: A list of nodes which were hashed by the signer. Each is
a string - the full path to node. A typical value might be:
hashed-nodes = "/", "/configurations/conf@1", "/images/kernel@1",
"/images/kernel@1/hash@1", "/images/fdt@1",
"/images/fdt@1/hash@1";
- hashed-strings: The start and size of the string region of the FIT that
was hashed
Example: See sign-images.its for an example image tree source file and
sign-configs.its for config signing.
Public Key Storage
------------------
In order to verify an image that has been signed with a public key we need to
have a trusted public key. This cannot be stored in the signed image, since
it would be easy to alter. For this implementation we choose to store the
public key in U-Boot's control FDT (using CONFIG_OF_CONTROL).
Public keys should be stored as sub-nodes in a /signature node. Required
properties are:
- algo: Algorithm name (e.g. "sha1,rs2048")
Optional properties are:
- key-name-hint: Name of key used for signing. This is only a hint since it
is possible for the name to be changed. Verification can proceed by checking
all available signing keys until one matches.
- required: If present this indicates that the key must be verified for the
image / configuration to be considered valid. Only required keys are
normally verified by the FIT image booting algorithm. Valid values are
"image" to force verification of all images, and "conf" to force verfication
of the selected configuration (which then relies on hashes in the images to
verify those).
Each signing algorithm has its own additional properties.
For RSA the following are mandatory:
- rsa,num-bits: Number of key bits (e.g. 2048)
- rsa,modulus: Modulus (N) as a big-endian multi-word integer
- rsa,exponent: Public exponent (E) as a 64 bit unsigned integer
- rsa,r-squared: (2^num-bits)^2 as a big-endian multi-word integer
- rsa,n0-inverse: -1 / modulus[0] mod 2^32
Signed Configurations
---------------------
While signing images is useful, it does not provide complete protection
against several types of attack. For example, it it possible to create a
FIT with the same signed images, but with the configuration changed such
that a different one is selected (mix and match attack). It is also possible
to substitute a signed image from an older FIT version into a newer FIT
(roll-back attack).
As an example, consider this FIT:
/ {
images {
kernel@1 {
data = <data for kernel1>
signature@1 {
algo = "sha1,rsa2048";
value = <...kernel signature 1...>
};
};
kernel@2 {
data = <data for kernel2>
signature@1 {
algo = "sha1,rsa2048";
value = <...kernel signature 2...>
};
};
fdt@1 {
data = <data for fdt1>;
signature@1 {
algo = "sha1,rsa2048";
vaue = <...fdt signature 1...>
};
};
fdt@2 {
data = <data for fdt2>;
signature@1 {
algo = "sha1,rsa2048";
vaue = <...fdt signature 2...>
};
};
};
configurations {
default = "conf@1";
conf@1 {
kernel = "kernel@1";
fdt = "fdt@1";
};
conf@1 {
kernel = "kernel@2";
fdt = "fdt@2";
};
};
};
Since both kernels are signed it is easy for an attacker to add a new
configuration 3 with kernel 1 and fdt 2:
configurations {
default = "conf@1";
conf@1 {
kernel = "kernel@1";
fdt = "fdt@1";
};
conf@1 {
kernel = "kernel@2";
fdt = "fdt@2";
};
conf@3 {
kernel = "kernel@1";
fdt = "fdt@2";
};
};
With signed images, nothing protects against this. Whether it gains an
advantage for the attacker is debatable, but it is not secure.
To solved this problem, we support signed configurations. In this case it
is the configurations that are signed, not the image. Each image has its
own hash, and we include the hash in the configuration signature.
So the above example is adjusted to look like this:
/ {
images {
kernel@1 {
data = <data for kernel1>
hash@1 {
algo = "sha1";
value = <...kernel hash 1...>
};
};
kernel@2 {
data = <data for kernel2>
hash@1 {
algo = "sha1";
value = <...kernel hash 2...>
};
};
fdt@1 {
data = <data for fdt1>;
hash@1 {
algo = "sha1";
value = <...fdt hash 1...>
};
};
fdt@2 {
data = <data for fdt2>;
hash@1 {
algo = "sha1";
value = <...fdt hash 2...>
};
};
};
configurations {
default = "conf@1";
conf@1 {
kernel = "kernel@1";
fdt = "fdt@1";
signature@1 {
algo = "sha1,rsa2048";
value = <...conf 1 signature...>;
};
};
conf@2 {
kernel = "kernel@2";
fdt = "fdt@2";
signature@1 {
algo = "sha1,rsa2048";
value = <...conf 1 signature...>;
};
};
};
};
You can see that we have added hashes for all images (since they are no
longer signed), and a signature to each configuration. In the above example,
mkimage will sign configurations/conf@1, the kernel and fdt that are
pointed to by the configuration (/images/kernel@1, /images/kernel@1/hash@1,
/images/fdt@1, /images/fdt@1/hash@1) and the root structure of the image
(so that it isn't possible to add or remove root nodes). The signature is
written into /configurations/conf@1/signature@1/value. It can easily be
verified later even if the FIT has been signed with other keys in the
meantime.
Verification
------------
FITs are verified when loaded. After the configuration is selected a list
of required images is produced. If there are 'required' public keys, then
each image must be verified against those keys. This means that every image
that might be used by the target needs to be signed with 'required' keys.
This happens automatically as part of a bootm command when FITs are used.
Enabling FIT Verification
-------------------------
In addition to the options to enable FIT itself, the following CONFIGs must
be enabled:
CONFIG_FIT_SIGNATURE - enable signing and verfication in FITs
CONFIG_RSA - enable RSA algorithm for signing
WARNING: When relying on signed FIT images with required signature check
the legacy image format is default disabled by not defining
CONFIG_IMAGE_FORMAT_LEGACY
Testing
-------
An easy way to test signing and verfication is to use the test script
provided in test/vboot/vboot_test.sh. This uses sandbox (a special version
of U-Boot which runs under Linux) to show the operation of a 'bootm'
command loading and verifying images.
A sample run is show below:
$ make O=sandbox sandbox_config
$ make O=sandbox
$ O=sandbox ./test/vboot/vboot_test.sh
Simple Verified Boot Test
=========================
Please see doc/uImage.FIT/verified-boot.txt for more information
/home/hs/ids/u-boot/sandbox/tools/mkimage -D -I dts -O dtb -p 2000
Build keys
do sha1 test
Build FIT with signed images
Test Verified Boot Run: unsigned signatures:: OK
Sign images
Test Verified Boot Run: signed images: OK
Build FIT with signed configuration
Test Verified Boot Run: unsigned config: OK
Sign images
Test Verified Boot Run: signed config: OK
check signed config on the host
Signature check OK
OK
Test Verified Boot Run: signed config: OK
Test Verified Boot Run: signed config with bad hash: OK
do sha256 test
Build FIT with signed images
Test Verified Boot Run: unsigned signatures:: OK
Sign images
Test Verified Boot Run: signed images: OK
Build FIT with signed configuration
Test Verified Boot Run: unsigned config: OK
Sign images
Test Verified Boot Run: signed config: OK
check signed config on the host
Signature check OK
OK
Test Verified Boot Run: signed config: OK
Test Verified Boot Run: signed config with bad hash: OK
Test passed
Future Work
-----------
- Roll-back protection using a TPM is done using the tpm command. This can
be scripted, but we might consider a default way of doing this, built into
bootm.
Possible Future Work
--------------------
- Add support for other RSA/SHA variants, such as rsa4096,sha512.
- Other algorithms besides RSA
- More sandbox tests for failure modes
- Passwords for keys/certificates
- Perhaps implement OAEP
- Enhance bootm to permit scripted signature verification (so that a script
can verify an image but not actually boot it)
Simon Glass
sjg@chromium.org
1-1-13

292
u-boot/doc/uImage.FIT/source_file_format.txt Normal file
View File

@@ -0,0 +1,292 @@
U-Boot new uImage source file format (bindings definition)
==========================================================
Author: Marian Balakowicz <m8@semihalf.com>
External data additions, 25/1/16 Simon Glass <sjg@chromium.org>
1) Introduction
---------------
Evolution of the 2.6 Linux kernel for embedded PowerPC systems introduced new
booting method which requires that hardware description is available to the
kernel in the form of Flattened Device Tree.
Booting with a Flattened Device Tree is much more flexible and is intended to
replace direct passing of 'struct bd_info' which was used to boot pre-FDT
kernels.
However, U-Boot needs to support both techniques to provide backward
compatibility for platforms which are not FDT ready. Number of elements
playing role in the booting process has increased and now includes the FDT
blob. Kernel image, FDT blob and possibly ramdisk image - all must be placed
in the system memory and passed to bootm as a arguments. Some of them may be
missing: FDT is not present for legacy platforms, ramdisk is always optional.
Additionally, old uImage format has been extended to support multi sub-images
but the support is limited by simple format of the legacy uImage structure.
Single binary header 'struct image_header' is not flexible enough to cover all
possible scenarios.
All those factors combined clearly show that there is a need for new, more
flexible, multi component uImage format.
2) New uImage format assumptions
--------------------------------
a) Implementation
Libfdt has been selected for the new uImage format implementation as (1) it
provides needed functionality, (2) is actively maintained and developed and
(3) increases code reuse as it is already part of the U-Boot source tree.
b) Terminology
This document defines new uImage structure by providing FDT bindings for new
uImage internals. Bindings are defined from U-Boot perspective, i.e. describe
final form of the uImage at the moment when it reaches U-Boot. User
perspective may be simpler, as some of the properties (like timestamps and
hashes) will need to be filled in automatically by the U-Boot mkimage tool.
To avoid confusion with the kernel FDT the following naming convention is
proposed for the new uImage format related terms:
FIT - Flattened uImage Tree
FIT is formally a flattened device tree (in the libfdt meaning), which
conforms to bindings defined in this document.
.its - image tree source
.itb - flattened image tree blob
c) Image building procedure
The following picture shows how the new uImage is prepared. Input consists of
image source file (.its) and a set of data files. Image is created with the
help of standard U-Boot mkimage tool which in turn uses dtc (device tree
compiler) to produce image tree blob (.itb). Resulting .itb file is the
actual binary of a new uImage.
tqm5200.its
+
vmlinux.bin.gz mkimage + dtc xfer to target
eldk-4.2-ramdisk --------------> tqm5200.itb --------------> bootm
tqm5200.dtb /|\
... |
'new uImage'
- create .its file, automatically filled-in properties are omitted
- call mkimage tool on a .its file
- mkimage calls dtc to create .itb image and assures that
missing properties are added
- .itb (new uImage) is uploaded onto the target and used therein
d) Unique identifiers
To identify FIT sub-nodes representing images, hashes, configurations (which
are defined in the following sections), the "unit name" of the given sub-node
is used as it's identifier as it assures uniqueness without additional
checking required.
3) Root node properties
-----------------------
Root node of the uImage Tree should have the following layout:
/ o image-tree
|- description = "image description"
|- timestamp = <12399321>
|- #address-cells = <1>
|
o images
| |
| o image@1 {...}
| o image@2 {...}
| ...
|
o configurations
|- default = "conf@1"
|
o conf@1 {...}
o conf@2 {...}
...
Optional property:
- description : Textual description of the uImage
Mandatory property:
- timestamp : Last image modification time being counted in seconds since
1970-01-01 00:00:00 - to be automatically calculated by mkimage tool.
Conditionally mandatory property:
- #address-cells : Number of 32bit cells required to represent entry and
load addresses supplied within sub-image nodes. May be omitted when no
entry or load addresses are used.
Mandatory node:
- images : This node contains a set of sub-nodes, each of them representing
single component sub-image (like kernel, ramdisk, etc.). At least one
sub-image is required.
Optional node:
- configurations : Contains a set of available configuration nodes and
defines a default configuration.
4) '/images' node
-----------------
This node is a container node for component sub-image nodes. Each sub-node of
the '/images' node should have the following layout:
o image@1
|- description = "component sub-image description"
|- data = /incbin/("path/to/data/file.bin")
|- type = "sub-image type name"
|- arch = "ARCH name"
|- os = "OS name"
|- compression = "compression name"
|- load = <00000000>
|- entry = <00000000>
|
o hash@1 {...}
o hash@2 {...}
...
Mandatory properties:
- description : Textual description of the component sub-image
- type : Name of component sub-image type, supported types are:
"standalone", "kernel", "ramdisk", "firmware", "script", "filesystem",
"flat_dt" and others (see uimage_type in common/image.c).
- data : Path to the external file which contains this node's binary data.
- compression : Compression used by included data. Supported compressions
are "gzip" and "bzip2". If no compression is used compression property
should be set to "none".
Conditionally mandatory property:
- os : OS name, mandatory for types "kernel" and "ramdisk". Valid OS names
are: "openbsd", "netbsd", "freebsd", "4_4bsd", "linux", "svr4", "esix",
"solaris", "irix", "sco", "dell", "ncr", "lynxos", "vxworks", "psos", "qnx",
"u_boot", "rtems", "unity", "integrity".
- arch : Architecture name, mandatory for types: "standalone", "kernel",
"firmware", "ramdisk" and "fdt". Valid architecture names are: "alpha",
"arm", "i386", "ia64", "mips", "mips64", "ppc", "s390", "sh", "sparc",
"sparc64", "m68k", "microblaze", "nios2", "blackfin", "avr32", "st200",
"sandbox".
- entry : entry point address, address size is determined by
'#address-cells' property of the root node. Mandatory for for types:
"standalone" and "kernel".
- load : load address, address size is determined by '#address-cells'
property of the root node. Mandatory for types: "standalone" and "kernel".
Optional nodes:
- hash@1 : Each hash sub-node represents separate hash or checksum
calculated for node's data according to specified algorithm.
5) Hash nodes
-------------
o hash@1
|- algo = "hash or checksum algorithm name"
|- value = [hash or checksum value]
Mandatory properties:
- algo : Algorithm name, supported are "crc32", "md5" and "sha1".
- value : Actual checksum or hash value, correspondingly 4, 16 or 20 bytes
long.
6) '/configurations' node
-------------------------
The 'configurations' node is optional. If present, it allows to create a
convenient, labeled boot configurations, which combine together kernel images
with their ramdisks and fdt blobs.
The 'configurations' node has has the following structure:
o configurations
|- default = "default configuration sub-node unit name"
|
o config@1 {...}
o config@2 {...}
...
Optional property:
- default : Selects one of the configuration sub-nodes as a default
configuration.
Mandatory nodes:
- configuration-sub-node-unit-name : At least one of the configuration
sub-nodes is required.
7) Configuration nodes
----------------------
Each configuration has the following structure:
o config@1
|- description = "configuration description"
|- kernel = "kernel sub-node unit name"
|- ramdisk = "ramdisk sub-node unit name"
|- fdt = "fdt sub-node unit-name"
|- fpga = "fpga sub-node unit-name"
|- loadables = "loadables sub-node unit-name"
Mandatory properties:
- description : Textual configuration description.
- kernel : Unit name of the corresponding kernel image (image sub-node of a
"kernel" type).
Optional properties:
- ramdisk : Unit name of the corresponding ramdisk image (component image
node of a "ramdisk" type).
- fdt : Unit name of the corresponding fdt blob (component image node of a
"fdt type").
- setup : Unit name of the corresponding setup binary (used for booting
an x86 kernel). This contains the setup.bin file built by the kernel.
- fpga : Unit name of the corresponding fpga bitstream blob
(component image node of a "fpga type").
- loadables : Unit name containing a list of additional binaries to be
loaded at their given locations. "loadables" is a comma-separated list
of strings. U-Boot will load each binary at its given start-address.
The FDT blob is required to properly boot FDT based kernel, so the minimal
configuration for 2.6 FDT kernel is (kernel, fdt) pair.
Older, 2.4 kernel and 2.6 non-FDT kernel do not use FDT blob, in such cases
'struct bd_info' must be passed instead of FDT blob, thus fdt property *must
not* be specified in a configuration node.
8) External data
----------------
The above format shows a 'data' property which holds the data for each image.
It is also possible for this data to reside outside the FIT itself. This
allows the FIT to be quite small, so that it can be loaded and scanned
without loading a large amount of data. Then when an image is needed it can
be loaded from an external source.
In this case the 'data' property is omitted. Instead you can use:
- data-offset : offset of the data in a separate image store. The image
store is placed immediately after the last byte of the device tree binary,
aligned to a 4-byte boundary.
- data-size : size of the data in bytes
The 'data-offset' property can be substituted with 'data-position', which
defines an absolute position or address as the offset. This is helpful when
booting U-Boot proper before performing relocation.
9) Examples
-----------
Please see doc/uImage.FIT/*.its for actual image source files.

44
u-boot/doc/uImage.FIT/update3.its Normal file
View File

@@ -0,0 +1,44 @@
/*
* Example Automatic software update file.
*/
/dts-v1/;
/ {
description = "Automatic software updates: kernel, ramdisk, FDT";
#address-cells = <1>;
images {
update@1 {
description = "Linux kernel binary";
data = /incbin/("./vmlinux.bin.gz");
compression = "none";
type = "firmware";
load = <FF700000>;
hash@1 {
algo = "sha1";
};
};
update@2 {
description = "Ramdisk image";
data = /incbin/("./ramdisk_image.gz");
compression = "none";
type = "firmware";
load = <FF8E0000>;
hash@1 {
algo = "sha1";
};
};
update@3 {
description = "FDT blob";
data = /incbin/("./blob.fdt");
compression = "none";
type = "firmware";
load = <FFAC0000>;
hash@1 {
algo = "sha1";
};
};
};
};

24
u-boot/doc/uImage.FIT/update_uboot.its Normal file
View File

@@ -0,0 +1,24 @@
/*
* Automatic software update for U-Boot
* Make sure the flashing addresses ('load' prop) is correct for your board!
*/
/dts-v1/;
/ {
description = "Automatic U-Boot update";
#address-cells = <1>;
images {
update@1 {
description = "U-Boot binary";
data = /incbin/("./u-boot.bin");
compression = "none";
type = "firmware";
load = <FFFC0000>;
hash@1 {
algo = "sha1";
};
};
};
};

104
u-boot/doc/uImage.FIT/verified-boot.txt Normal file
View File

@@ -0,0 +1,104 @@
U-Boot Verified Boot
====================
Introduction
------------
Verified boot here means the verification of all software loaded into a
machine during the boot process to ensure that it is authorised and correct
for that machine.
Verified boot extends from the moment of system reset to as far as you wish
into the boot process. An example might be loading U-Boot from read-only
memory, then loading a signed kernel, then using the kernel's dm-verity
driver to mount a signed root filesystem.
A key point is that it is possible to field-upgrade the software on machines
which use verified boot. Since the machine will only run software that has
been correctly signed, it is safe to read software from an updatable medium.
It is also possible to add a secondary signed firmware image, in read-write
memory, so that firmware can easily be upgraded in a secure manner.
Signing
-------
Verified boot uses cryptographic algorithms to 'sign' software images.
Images are signed using a private key known only to the signer, but can
be verified using a public key. As its name suggests the public key can be
made available without risk to the verification process. The private and
public keys are mathematically related. For more information on how this
works look up "public key cryptography" and "RSA" (a particular algorithm).
The signing and verification process looks something like this:
Signing Verification
======= ============
+--------------+ *
| RSA key pair | * +---------------+
| .key .crt | * | Public key in |
+--------------+ +------> public key ----->| trusted place |
| | * +---------------+
| | * |
v | * v
+---------+ | * +--------------+
| |----------+ * | |
| signer | * | U-Boot |
| |----------+ * | signature |--> yes/no
+---------+ | * | verification |
^ | * | |
| | * +--------------+
| | * ^
+----------+ | * |
| Software | +----> signed image -------------+
| image | *
+----------+ *
The signature algorithm relies only on the public key to do its work. Using
this key it checks the signature that it finds in the image. If it verifies
then we know that the image is OK.
The public key from the signer allows us to verify and therefore trust
software from updatable memory.
It is critical that the public key be secure and cannot be tampered with.
It can be stored in read-only memory, or perhaps protected by other on-chip
crypto provided by some modern SOCs. If the public key can be changed, then
the verification is worthless.
Chaining Images
---------------
The above method works for a signer providing images to a run-time U-Boot.
It is also possible to extend this scheme to a second level, like this:
1. Master private key is used by the signer to sign a first-stage image.
2. Master public key is placed in read-only memory.
2. Secondary private key is created and used to sign second-stage images.
3. Secondary public key is placed in first stage images
4. We use the master public key to verify the first-stage image. We then
use the secondary public key in the first-stage image to verify the second-
state image.
5. This chaining process can go on indefinitely. It is recommended to use a
different key at each stage, so that a compromise in one place will not
affect the whole change.
Flattened Image Tree (FIT)
--------------------------
The FIT format is already widely used in U-Boot. It is a flattened device
tree (FDT) in a particular format, with images contained within. FITs
include hashes to verify images, so it is relatively straightforward to
add signatures as well.
The public key can be stored in U-Boot's CONFIG_OF_CONTROL device tree in
a standard place. Then when a FIT it loaded it can be verified using that
public key. Multiple keys and multiple signatures are supported.
See signature.txt for more information.
Simon Glass
sjg@chromium.org
1-1-13

276
u-boot/doc/uImage.FIT/x86-fit-boot.txt Normal file
View File

@@ -0,0 +1,276 @@
Booting Linux on x86 with FIT
=============================
Background
----------
(corrections to the text below are welcome)
Generally Linux x86 uses its own very complex booting method. There is a setup
binary which contains all sorts of parameters and a compressed self-extracting
binary for the kernel itself, often with a small built-in serial driver to
display decompression progress.
The x86 CPU has various processor modes. I am no expert on these, but my
understanding is that an x86 CPU (even a really new one) starts up in a 16-bit
'real' mode where only 1MB of memory is visible, moves to 32-bit 'protected'
mode where 4GB is visible (or more with special memory access techniques) and
then to 64-bit 'long' mode if 64-bit execution is required.
Partly the self-extracting nature of Linux was introduced to cope with boot
loaders that were barely capable of loading anything. Even changing to 32-bit
mode was something of a challenge, so putting this logic in the kernel seemed
to make sense.
Bit by bit more and more logic has been added to this post-boot pre-Linux
wrapper:
- Changing to 32-bit mode
- Decompression
- Serial output (with drivers for various chips)
- Load address randomisation
- Elf loader complete with relocation (for the above)
- Random number generator via 3 methods (again for the above)
- Some sort of EFI mini-loader (1000+ glorious lines of code)
- Locating and tacking on a device tree and ramdisk
To my mind, if you sit back and look at things from first principles, this
doesn't make a huge amount of sense. Any boot loader worth its salts already
has most of the above features and more besides. The boot loader already knows
the layout of memory, has a serial driver, can decompress things, includes an
ELF loader and supports device tree and ramdisks. The decision to duplicate
all these features in a Linux wrapper caters for the lowest common
denominator: a boot loader which consists of a BIOS call to load something off
disk, followed by a jmp instruction.
(Aside: On ARM systems, we worry that the boot loader won't know where to load
the kernel. It might be easier to just provide that information in the image,
or in the boot loader rather than adding a self-relocator to put it in the
right place. Or just use ELF?
As a result, the x86 kernel boot process is needlessly complex. The file
format is also complex, and obfuscates the contents to a degree that it is
quite a challenge to extract anything from it. This bzImage format has become
so prevalent that is actually isn't possible to produce the 'raw' kernel build
outputs with the standard Makefile (as it is on ARM for example, at least at
the time of writing).
This document describes an alternative boot process which uses simple raw
images which are loaded into the right place by the boot loader and then
executed.
Build the kernel
----------------
Note: these instructions assume a 32-bit kernel. U-Boot does not currently
support booting a 64-bit kernel as it has no way of going into 64-bit mode on
x86.
You can build the kernel as normal with 'make'. This will create a file called
'vmlinux'. This is a standard ELF file and you can look at it if you like:
$ objdump -h vmlinux
vmlinux: file format elf32-i386
Sections:
Idx Name Size VMA LMA File off Algn
0 .text 00416850 81000000 01000000 00001000 2**5
CONTENTS, ALLOC, LOAD, RELOC, READONLY, CODE
1 .notes 00000024 81416850 01416850 00417850 2**2
CONTENTS, ALLOC, LOAD, READONLY, CODE
2 __ex_table 00000c50 81416880 01416880 00417880 2**3
CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA
3 .rodata 00154b9e 81418000 01418000 00419000 2**5
CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA
4 __bug_table 0000597c 8156cba0 0156cba0 0056dba0 2**0
CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA
5 .pci_fixup 00001b80 8157251c 0157251c 0057351c 2**2
CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA
6 .tracedata 00000024 8157409c 0157409c 0057509c 2**0
CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA
7 __ksymtab 00007ec0 815740c0 015740c0 005750c0 2**2
CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA
8 __ksymtab_gpl 00004a28 8157bf80 0157bf80 0057cf80 2**2
CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA
9 __ksymtab_strings 0001d6fc 815809a8 015809a8 005819a8 2**0
CONTENTS, ALLOC, LOAD, READONLY, DATA
10 __init_rodata 00001c3c 8159e0a4 0159e0a4 0059f0a4 2**2
CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA
11 __param 00000ff0 8159fce0 0159fce0 005a0ce0 2**2
CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA
12 __modver 00000330 815a0cd0 015a0cd0 005a1cd0 2**2
CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA
13 .data 00063000 815a1000 015a1000 005a2000 2**12
CONTENTS, ALLOC, LOAD, RELOC, DATA
14 .init.text 0002f104 81604000 01604000 00605000 2**2
CONTENTS, ALLOC, LOAD, RELOC, READONLY, CODE
15 .init.data 00040cdc 81634000 01634000 00635000 2**12
CONTENTS, ALLOC, LOAD, RELOC, DATA
16 .x86_cpu_dev.init 0000001c 81674cdc 01674cdc 00675cdc 2**2
CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA
17 .altinstructions 0000267c 81674cf8 01674cf8 00675cf8 2**0
CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA
18 .altinstr_replacement 00000942 81677374 01677374 00678374 2**0
CONTENTS, ALLOC, LOAD, READONLY, CODE
19 .iommu_table 00000014 81677cb8 01677cb8 00678cb8 2**2
CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA
20 .apicdrivers 00000004 81677cd0 01677cd0 00678cd0 2**2
CONTENTS, ALLOC, LOAD, RELOC, DATA
21 .exit.text 00001a80 81677cd8 01677cd8 00678cd8 2**0
CONTENTS, ALLOC, LOAD, RELOC, READONLY, CODE
22 .data..percpu 00007880 8167a000 0167a000 0067b000 2**12
CONTENTS, ALLOC, LOAD, RELOC, DATA
23 .smp_locks 00003000 81682000 01682000 00683000 2**2
CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA
24 .bss 000a1000 81685000 01685000 00686000 2**12
ALLOC
25 .brk 00424000 81726000 01726000 00686000 2**0
ALLOC
26 .comment 00000049 00000000 00000000 00686000 2**0
CONTENTS, READONLY
27 .GCC.command.line 0003e055 00000000 00000000 00686049 2**0
CONTENTS, READONLY
28 .debug_aranges 0000f4c8 00000000 00000000 006c40a0 2**3
CONTENTS, RELOC, READONLY, DEBUGGING
29 .debug_info 0440b0df 00000000 00000000 006d3568 2**0
CONTENTS, RELOC, READONLY, DEBUGGING
30 .debug_abbrev 0022a83b 00000000 00000000 04ade647 2**0
CONTENTS, READONLY, DEBUGGING
31 .debug_line 004ead0d 00000000 00000000 04d08e82 2**0
CONTENTS, RELOC, READONLY, DEBUGGING
32 .debug_frame 0010a960 00000000 00000000 051f3b90 2**2
CONTENTS, RELOC, READONLY, DEBUGGING
33 .debug_str 001b442d 00000000 00000000 052fe4f0 2**0
CONTENTS, READONLY, DEBUGGING
34 .debug_loc 007c7fa9 00000000 00000000 054b291d 2**0
CONTENTS, RELOC, READONLY, DEBUGGING
35 .debug_ranges 00098828 00000000 00000000 05c7a8c8 2**3
CONTENTS, RELOC, READONLY, DEBUGGING
There is also the setup binary mentioned earlier. This is at
arch/x86/boot/setup.bin and is about 12KB in size. It includes the command
line and various settings need by the kernel. Arguably the boot loader should
provide all of this also, but setting it up is some complex that the kernel
helps by providing a head start.
As you can see the code loads to address 0x01000000 and everything else
follows after that. We could load this image using the 'bootelf' command but
we would still need to provide the setup binary. This is not supported by
U-Boot although I suppose you could mostly script it. This would permit the
use of a relocatable kernel.
All we need to boot is the vmlinux file and the setup.bin file.
Create a FIT
------------
To create a FIT you will need a source file describing what should go in the
FIT. See kernel.its for an example for x86. Put this into a file called
image.its.
Note that setup is loaded to the special address of 0x90000 (a special address
you just have to know) and the kernel is loaded to 0x01000000 (the address you
saw above). This means that you will need to load your FIT to a different
address so that U-Boot doesn't overwrite it when decompressing. Something like
0x02000000 will do so you can set CONFIG_SYS_LOAD_ADDR to that.
In that example the kernel is compressed with lzo. Also we need to provide a
flat binary, not an ELF. So the steps needed to set things are are:
# Create a flat binary
objcopy -O binary vmlinux vmlinux.bin
# Compress it into LZO format
lzop vmlinux.bin
# Build a FIT image
mkimage -f image.its image.fit
(be careful to run the mkimage from your U-Boot tools directory since it
will have x86_setup support.)
You can take a look at the resulting fit file if you like:
$ dumpimage -l image.fit
FIT description: Simple image with single Linux kernel on x86
Created: Tue Oct 7 10:57:24 2014
Image 0 (kernel@1)
Description: Vanilla Linux kernel
Created: Tue Oct 7 10:57:24 2014
Type: Kernel Image
Compression: lzo compressed
Data Size: 4591767 Bytes = 4484.15 kB = 4.38 MB
Architecture: Intel x86
OS: Linux
Load Address: 0x01000000
Entry Point: 0x00000000
Hash algo: sha1
Hash value: 446b5163ebfe0fb6ee20cbb7a8501b263cd92392
Image 1 (setup@1)
Description: Linux setup.bin
Created: Tue Oct 7 10:57:24 2014
Type: x86 setup.bin
Compression: uncompressed
Data Size: 12912 Bytes = 12.61 kB = 0.01 MB
Hash algo: sha1
Hash value: a1f2099cf47ff9816236cd534c77af86e713faad
Default Configuration: 'config@1'
Configuration 0 (config@1)
Description: Boot Linux kernel
Kernel: kernel@1
Booting the FIT
---------------
To make it boot you need to load it and then use 'bootm' to boot it. A
suitable script to do this from a network server is:
bootp
tftp image.fit
bootm
This will load the image from the network and boot it. The command line (from
the 'bootargs' environment variable) will be passed to the kernel.
If you want a ramdisk you can add it as normal with FIT. If you want a device
tree then x86 doesn't normally use those - it has ACPI instead.
Why Bother?
-----------
1. It demystifies the process of booting an x86 kernel
2. It allows use of the standard U-Boot boot file format
3. It allows U-Boot to perform decompression - problems will provide an error
message and you are still in the boot loader. It is possible to investigate.
4. It avoids all the pre-loader code in the kernel which is quite complex to
follow
5. You can use verified/secure boot and other features which haven't yet been
added to the pre-Linux
6. It makes x86 more like other architectures in the way it boots a kernel.
You can potentially use the same file format for the kernel, and the same
procedure for building and packaging it.
References
----------
In the Linux kernel, Documentation/x86/boot.txt defines the boot protocol for
the kernel including the setup.bin format. This is handled in U-Boot in
arch/x86/lib/zimage.c and arch/x86/lib/bootm.c.
The procedure for entering 64-bit mode on x86 seems to be described here:
http://wiki.osdev.org/64-bit_Higher_Half_Kernel_with_GRUB_2
Various files in the same directory as this file describe the FIT format.
--
Simon Glass
sjg@chromium.org
7-Oct-2014