Create Container Boot Image

This page provides instructions for creating a bootable Linux kernel image in container format and setup boot partition in SBL to boot from it.

Note

See Container Tool for more details on container format.

The following step-by-step instructions is an example to boot Yocto kernel using container image format on UP2.

Important

SBL Linux boot image containers typically include the kernel, kernel params and initramfs. The kernel then will mount the root file system from the boot media. There may be additional requirements in terms of configuration and layout for the kernel to locate and mount the root file system. If your boot image has some partition layout requirements, file/file-path dependencies, etc., you still need to adhere to those requirements when using container boot.

Step 1: Download GenContainer.py, SingleSign.py and CommonUtility.py to the same working directory to use the container tool.

Step 2: Get kernel and associated files from target Yocto disk image.

  1. Locate and save a copy of vmlinuz (e.g. vmlinuz), initramfs (initrd)

  2. Create cmdline.txt with kernel command line string. There are different ways to extract kernel command line from a booted system. Examples includes grub.cfg, /proc/cmdline or via dmesg | grep 'Command line'. If the command line is empty, create an empty file.

Step 3: Generate container.bin file

Run:

GenContainer.py create -cl CMDL:<cmdline.txt> KRNL:<vmlinuz> INRD:<initrd> -k <RSA_private_key> -t CLASSIC -o container.bin

   <RSA_private_key>: RSA 2048/3072 private key path in PEM format to sign image.
                      Ex: OS1_TestKey_Priv_RSA2048.pem/OS1_TestKey_Priv_RSA3072.pem available in SblKeys directory. Alternatively it can be generated from GenerateKeys.py
   <RSA_private_key>: Hash of the public key should be included in SBL Key Manifest and HASH_USAGE should be set to 'PUBKEY_OS' during SBL build.
                      SBL Key hash manifest is configured in GetKeyHashList in platform BoarConfig.py. Default hash included is for OS1_TestKey_Priv_RSA2048.pem/OS1_TestKey_Priv_RSA3072.pem.

Sample output messages:

Container 'BOOT' was created successfully at:
/home/user/container.bin

Step 4: Copy container.bin onto the first boot partition on UP2.

Depending whether you are booting from eMMC or USB, container.bin should be copied to the root directory on the boot device.

Step 5: Configure boot option entry to load container.bin from the boot partition

Make sure the boot option is configured to the location of container.bin on the boot device. E.g., if container.bin is located on the first boot FAT32 partition on USB, the boot option entry should look like the following:

- !expand { BOOT_OPTION_TMPL : [ 3 ,   0    ,  0 ,    5   ,   0   ,    0  ,     0 ,     0 , 'container.bin' ] }

See Change Boot Options for more details.

Step 6: Build, stitch, flash and boot

Follow Supported Hardware to build a flashable image for the target platform.

Note

If the target boot option is not the first entry, enter SBL shell first to switch it to the first one.

Example boot messages:

...
<Switch boot option to boot USB ...>
...

Shell> exit
Boot options (in HEX):

Idx|ImgType|DevType|DevNum|Flags|HwPart|FsType|SwPart|File/Lbaoffset
  0|      0|   USB |    0 |   0 |    0 | EXT2 |    1 | container.bin
  1|      0|  SATA |    0 |   0 |    1 | EXT2 |    1 | container.bin
  2|      0|   MMC |    0 |   0 |    0 | EXT2 |    1 | container.bin
  3|      0|  NVME |    0 |   0 |    0 | EXT2 |    1 | container.bin


======== Try Booting with Boot Option 0 ========
BootMediumPciBase(0x1500)
Getting boot image from USB
Init USB XHCI - Success
Enumerate Bus - Success
Found 2 USB devices on bus
Found mass storage on device 1
Try to find boot partition
Find partition success
Init File system
Detected FAT on StartBlock 270336 Part 0
BootSlot = 0x0
File 'container.bin' size 17244208
Get file 'container.bin' (size:0x1072030) success.
LoadBootImage ImageType-0 Image
ParseBootImage ImageType-0
Registering container BOOT
HASH verification for usage (0x00000800) with Hash Alg (0x1): Success
SignType (0x1) SignSize (0x100)  SignHashAlg (0x1)
RSA verification for usage (0x00000800): Success
CONTAINER size = 0x1072030, image type = 0xF3, # of components = 4
COMP:CMDL Success
COMP:KRNL Success
COMP:INRD Success
Unregister done - Success!
SetupBootImage ImageType-0
Assume BzImage...
Found bzimage Signature

Dump normal boot image info:


============ KERNEL SETUP ============
SetupSectorss: 0x20
RootFlags: 0x1
SysSize: 0x106D2A

...