Recent changes

02. Placing the FIT on the board's eMMC

There are many ways to make the FIT image available to U-Boot. For this task we chose a method that may seem roundabout, but can serve as a starting point toward making our board's configuration persistent across resets (i.e.: no longer using SDP each time we restart it.)

The goal is to add a FAT partition on the eMMC storage device and on that partition, place the FIT image. bl33 has the drivers necessary to parse the partition table and interact with the FAT32 file system.

Later in this exercise we will see how uuu can be used to overwrite the eMMC. Unfortunately, it will overwrite it indiscriminately starting at the very beginning. This means that an attempt to just flash the FIT image onto the eMMC will delete the partition table, rendering it useless to bl33. To circumvent this issue, we will create a disk image, containing the following:

A partition table: needed in order to identify different partitions on the eMMC.
~10MB of empty space: this is where you can place the FIP image (i.e.: the one with the bootloaders and firmware) to be loaded automatically during an eMMC boot (refer to the Jumper configuration part of the previous lab).
A FAT32 formatted partition containing the FIT image. Other file system types such as ext4 may be a bit too exotic for some bootloaders out there, but everyone should know how to interpret FAT.

Task A - Create the disk image

Start of by creating an empty file. If your FIT image is ~70MB, then 100MB should suffice. No need to be conservative.

$ truncate --size 100M disk.img

Next, use fdisk to create a partition on disk.img.

Figure 1: Disk image layout. The optional Firmware Image Package would be loaded during an MMC boot from a 32KB offset. Adding the FIP to the disk image is not part of the task.

Before creating the partition, explicitly add a Master Boot Record (MBR) partition table. If you don't and there's no partition table at the start of disk.img, fdisk will create a MBR by default. However, you never know what garbage data was already on your hard drive when you truncated the new file.

When asked where the partition should start, remember that fdisk expresses the offsets in sectors. One sector is 512 bytes. So, how many sectors are there in 10MB?

Now that we have a partition, we want to format it with a FAT32 filesystem. Normally, the OS would make this painfully easy for us, by creating /dev/ entries for each partition. For example, if you plugged in a USB stick identified as /dev/sda with two partitions, the kernel would also generate the sda1 and sda2 entries for you to target with mkfs or to mount. As of now, the kernel does not recognize a random file that we just created as a storage device. So let's change that:

# -a : add new disk
# -v : verbose output helps identify the new device
$ partx -a -v disk.img

The partx tool made our disk.img file known to the kernel and asked for it to be scanned for partitions. The kernel obliged and created a loopback device (i.e.: a file-backed storage device).

You can run lsblk to confirm this. However, if you are using Ubuntu, you will most likely see a lot of loopback devices, one for each snap that you have installed. Look for a 100M disk with a 90M partition.

We've finally arrived at the point where we can format the partition, mount it and copy the fit image onto it:

# create FAT32 file system 
$ mkfs.fat -F 32 /dev/loop0p1
 
# mount file system (assuming /mnt is empty)
$ mount /dev/loop0p1 /mnt
 
# copy the FIT image
$ cp linux.itb /mnt
 
# unmount the file system
$ umount /mnt

Although chances are you still need to make changes to the disk image, you can clean up the loopback device using the commands below. Alternatively, you can safely shut down your machine since the configuration is not persistent.

# deregister our disk image as a storage device
$ partx -d /dev/loop0
 
# delete the loopback device that was allocated for us
$ losetup -D /dev/loop0

Task B - Overwrite the eMMC

For this task we are going to follow the TechNexion guide for flashing the eMMC. Download their pre-compiled uuu binary since it comes with a few extra scripts and a custom bl2 downloads the disk image via SDP and uses it to overwrite the eMMC instead of booting into it, like our SPL.

We will use u-boot's Mass Storage Device emulation to present the board's eMMC flash memory as host device and write our image:

u-boot> ums mmc 0
# keep it running (i.e., do not ctrl+c)!

Simply use the dd tool or another image writer tool to burn the disk.bin image on the USB device presented by the board:

# first, run lsblk and determine the device's address:
lsblk
# look at the disk capacities and choose the 16G one
# PLEASE BE CAREFUL! TAKE NOTE TO IGNORE YOUR MAIN HOST PARTITIONS!
# OTHERWISE, YOU MAY LOSE PERSONAL DATA!
dd if=disk.bin of=/dev/<sdaX?> bs=4k