Modifying Board Assets

The booting procedure of the Genio platform consists of several stages, and each stage is implemented by different software component, which is described in IoT Yocto BSP & Boot Architecture.

The following sections will walk you through the process to modify these software components and flash board assets to the target board for testing.

Important

Before proceeding, please ensure that you have downloaded IoT Yocto source tree and built an image from it. Please refer to Build from Source Code for more information.

Note

The document will take U-Boot as an example to demonstrate how to check out, modify, and build the source tree. The same procedure applies to other components.

Modifying U-Boot

To modify the U-Boot source tree, please use Yocto devtool to check out the source tree specified by the recipe:

MACHINE=<board-name> devtool modify u-boot

After running the command, the checked out source tree will be located under the path <BUILD_DIR>/workspace/sources/u-boot.

Warning

While it may appear to work if you modify the source code files under the <BUILD_DIR>/tmp/work directories, this breaks Yocto’s build cache management logic, and your changes may be overwritten by the bitbake tool without warning. Always use devtool and modify files under <BUILD_DIR>/workspace.

The extracted directory is a git repository, and you can modify the source code and run git commit to track changes locally. The initial git history created by devtool modify consists of:

• The git repository commit designated by the SRC_URI and SRCREV variables in the recipe.

• Extra patches applied by the Yocto recipe on top of the SRCREV commit. These patches are usually board dependent fixes.

An example of U-Boot commit history shows these commits:

In the example above, the U-Boot recipe fetches commit a5d8f6 from the U-Boot source repository, and then applies 4 patches. These patches are the result of two different Yocto layers:

• 1 additional patches in .bb file in meta-mediatek-bsp: src/meta-mediatek-bsp/recipes-bsp/u-boot/u-boot_git.bb.

• 3 additional patches in .bbappend file in meta-rity: src/meta-mediatek-bsp/recipes-bsp/u-boot/u-boot_git.bbappend

Because of the flexible layered architecture of Yocto, each layer is able to extend or modify settings of base layers, it is not easy to figure out correctly which git commit to check out, or which patch to be applied on the source tree. Therefore, we recommend you to always extract the source tree with MACHINE=<board-name> devtool modify so that you can get the correct source tree.

Note

Once devtool modify <recipe> has been executed, patch changes in the recipe files will be ignored, because the extracted source repository in workspace overrides configurations in the recipe.

After modifying the source code, you can re-compile it with:

MACHINE=<board-name> bitbake u-boot

Since the U-Boot binary is not the final image used for flashing the target board, we need one more step for generating it:

MACHINE=<board-name> bitbake trusted-firmware-a

The built artifact is located in <BUILD_DIR>/tmp/deploy/images/<MACHINE>/fip.bin.

Important

It is not intuitive to determine which recipe used for modifying source tree and which recipe used for generating images for flashing the target board. Here is the table for listing each component and the corresponding recipes used for modification and image generation.

Recipes for modification and image generation

Component	Recipe for modification	Recipe for image generation	Image	Purpose
BL2	bl2	bl2	bl2.img	DRAM initialization
BL31	trusted-firmware-a	trusted-firmware-a	fip.bin	platform initialization
BL32	optee-os	trusted-firmware-a	fip.bin	secure environment
BL33	u-boot	trusted-firmware-a	fip.bin	For booting operating system
Download Agent	lk	lk	lk.bin	bootstrap binary used by genio-flash to initalize DRAM, storage to support fastboot protocol
U-Boot Env	N/A	u-boot	u-boot-env.bin	Generated by genio-flash from u-boot-initial-env text file

Note that since BL31, BL32, BL33 are all bundled in single partition image fip.bin, updating the source of any one of them requires rebuilding both the recipe for modification and the recipe for image generation.

Once you are satisfied with the modifications, there are two ways for integrating these changes to the recipe:

• If you are maintaining your own U-Boot git repository, you can commit your changes to it, and update the SRCREV of the corresponding recipe with the correct git hash.

• If those changes are small enough, you can create patches, add them to the directory containing patches in the Yocto source tree, and update the SRC_URI of the corresponding recipe to add your listing of patches.

After finishing the integration, now you can reset the devtool environment and switch to use the updated recipe for building U-Boot:

MACHINE=<board-name> devtool reset u-boot

Note

After running devtool reset <recipe>, the workspace folder (<BUILD_DIR>/workspace/sources/u-boot in this case) containing checked out source tree will be kept. You are free to delete it if you don’t need it anymore.

Modifying boot assets

In addition to modifying bootloaders, IoT Yocto allows the user to add or modify static data such as boot logos, audio, or video files, which will be stored in the bootassets partition.

To add new data, please create a new file bootassets-part.bbappend under your custom layer, with following content:

FILESEXTRAPATHS:prepend := "${THISDIR}/files:"

SRC_URI += " \
   file://data.bin \
"

collect_artifacts:append() {
   cp ${WORKDIR}/data.bin ${BOOTASSETS_IMAGE_FS}
}

And please run the command to generate boot assets:

MACHINE=<board-name> bitbake bootassets-part

The generated image will be in <BUILD_DIR>/tmp/deploy/images/<MACHINE>/bootassets.vfat.

Flashing to target board

After modifying board assets (including bootloader binaries or boot assets), we can use genio-flash tool to flash those images to the target board. Each partition can be flashed individually without touching others:

$ cd <BUILD_DIR>/deploy/images/<MACHINE>/

# Flash bl2
$ genio-flash mmc0boot0

# Flash U-Boot
$ genio-flash bootloaders

# Flash U-Boot & U-Boot env
$ genio-flash bootloaders mmc0boot1

# Flash boot assets
$ genio-flash bootassets

The table below lists the needed argument supplied to genio-flash for flashing board assets.

Partitions and corresponding images for flashing

Component	Partition name for genio-flash	Image
BL2	mmc0boot0	bl2.img
BL31	bootloaders	fip.bin
BL32	bootloaders	fip.bin
BL33	bootloaders	fip.bin
U-Boot Env	mmc0boot1	u-boot-env.bin
Boot assets	bootassets	bootassets.vfat