Modify Bootloader

This page shows you how to modify bootloader and boot firmware to enable new board and module designs for Ubuntu on Genio images.

As described in Software Overview, the bootloader binaries in the boot firmware, including the binaries for Genio EVK boards, are built with IoT Yocto.

The boot firmware files are also called board assets in this guide and in IoT Yocto.

Note

There are access control and license requirements for part of the bootloader source code. Please visit IoT Yocto documentation on board enablement and account setup.

To modify the boot loader binaries involve these steps:

Install Required Build Tools

Follow the steps in Setup IoT Yocto Build Environment to set up a build environment for IoT Yocto in your Ubuntu host machine.

Re-Build Boot Firmware for Genio EVK Boards

Before modifying the bootloader source code, we recommend you to rebuild boot firmwares for the reference Genio EVK boards from source code. This ensures the proper configuration of the build environment, and can be very useful for code investigation and issue analysis.

To rebuild boot firmwares of Genio EVK boards, follow these steps:

Initialize IoT Yocto Build Environment

On your Ubuntu build machine, use these commands to download IoT Yocto recipes and initialize a Yocto build environment:

# download recipe with manifests
$ mkdir iot-yocto; cd iot-yocto
$ export PROJ_ROOT=`pwd`
$ repo init -u https://gitlab.com/mediatek/aiot/bsp/manifest.git -b refs/tags/rity-kirkstone-v23.1 -m default.xml --no-repo-verify
$ repo sync

# initialize Yocto build environment
$ TEMPLATECONF=$PWD/src/meta-rity/meta/conf source src/poky/oe-init-build-env
$ export BUILD_DIR=`pwd`

# Enable components that require NDA access
$ echo NDA_BUILD = \"1\" >> ${BUILD_DIR}/conf/local.conf

Note

We enable NDA_BUILD in line 12 because board customization involves modifying proprietary components, notably the DRAM calibration drivers and essential soc platform initialization libraries. This requires additional access permissions. Please follow the instructions in this page.

In line 4 of the example above, we are fetching the manifest of the IoT Yocto v23.1 release.

Please visit IoT Yocto release notes to get the latest version of IoT Yocto.

The steps above create default configuration files in the iot-yocto/build directory, and set up shell environment variables for the Yocto build tool, bitbake.

Note that you need to run source src/poky/oe-init-build-env every time you start a new shell to set up environment variables again.

Troubleshooting

If the repo tool reports manifest syntax error, you might want to install the latest repo tool manually with:

mkdir -p ~/.bin
PATH="${HOME}/.bin:${PATH}"
curl https://storage.googleapis.com/git-repo-downloads/repo > ~/.bin/repo
chmod a+rx ~/.bin/repo

Note

To learn more about the build steps, please visit IoT Yocto developer guide .

Build Genio EVK Board Assets

All board-specific configurations in IoT Yocto are associated with a bitbake variable MACHINE. To build board assets for each Genio EVK board, assign the MACHINE variable and invoke the bitbake command:

Genio 350 EVK

# fetch required Yocto packages and build board-assets
MACHINE=genio-350-evk bitbake board-assets

The output archive is located in $BUILD_DIR/tmp/deploy/images/genio-350-evk/board-assets.tar.gz.

Genio 510 EVK

# fetch required Yocto packages and build board-assets
MACHINE=genio-510-evk bitbake board-assets

The output archive is located in $BUILD_DIR/tmp/deploy/images/genio-510-evk/board-assets.tar.gz.

Genio 700 EVK

# fetch required Yocto packages and build board-assets
MACHINE=genio-700-evk bitbake board-assets

The output archive is located in $BUILD_DIR/tmp/deploy/images/genio-700-evk/board-assets.tar.gz.

Genio 1200 EVK (P1V2)

# fetch required Yocto packages and build board-assets
MACHINE=genio-1200-evk bitbake board-assets

The output archive is located in $BUILD_DIR/tmp/deploy/images/genio-1200-evk/board-assets.tar.gz.

Genio 1200 EVK (P1V1)

# fetch required Yocto packages and build board-assets
MACHINE=genio-1200-evk-p1v1 bitbake board-assets

The output archive is located in $BUILD_DIR/tmp/deploy/images/genio-1200-evk-p1v1/board-assets.tar.gz. Note: P1V1 are engineering samples of Genio 1200 EVK and will become deprecated.

Modify Boot Script to EFI Boot Flow

Ubuntu on Genio is based on EFI boot flow and the default boot flow in boot firmwares are FIT boot. Therefore, you need to unarchive boot firmwares and modify the lines:

boot_targets=embedded

to:

boot_targets=mmc0

You can then update the new boot loaders to the board using Genio Tools. Please refer to Genio Tools.

Modify Boot Loader Source Code with devtool

The bootloaders consists of these components:

• BL2 implemented by Trusted-Firmware-A

• BL31 also implemented by Trusted-Firmware-A

• BL32 implemented by OP-TEE

• BL33 implemented by U-Boot

For new boards that uses different DRAM or storage parts, a boot strapping binary for genio-flash called lk.bin is also required. Please refer to IoT Yocto Boot Architecture for details.

To modify the source code of these components, use the Yocto tool devtool to extract the source code of their corresponding recipes. For example, use the following command to extract U-boot source code:

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

Their corresponding source code will be extracted to:

build/workspace/sources/u-boot

Warning

While it may appear to work if you modify the source code files under the build/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/workspace.

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

• The git repository commit designated by the Yocto recipe’s SRC_URI and SRC_REV variables.

• Extra patches applied by the Yocto recipe on top of the SRC_REV commit. These patches are usually MACHINE 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 pathces in .bbappend file in meta-rity: src/meta-mediatek-bsp/recipes-bsp/u-boot/u-boot_git.bbappend

The design of Yocto is flexible and each layers have the option to append new patches on top of other layers. Therefore, we recommend you to always extrace the source code with MACHINE=<your-machine> devtool modify so that you get the correct commit histories.

Note

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

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

MACHINE=<board-name> bitbake -c compile u-boot

and build the u-boot binaries with:

MACHINE=<board-name> bitbake u-boot

If you suspect that the build cache is corrupted and you want to clean old build artifacts, you can use:

MACHINE=<board-name> bitbake -c cleanall u-boot

There are a few caveats if you want to flash the new u-boot binary to the board:

• BL31, BL32 and BL33 are wrapped together in a partition image fip.bin.

• Rebuilding u-boot recipe does not update fip.bin

You must build the trusted-firmware-a recipe to actually update fip.bin:

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

the updated fip.bin is located in:

$BUILD_DIR/tmp/deploy/images/<board-name>/fip.bin

Please refer to Yocto documentation for references on using devtool.

The following table shows the bootloader components and corresponding Yocto recipe names:

Partition Layout for Ubuntu on Genio on Genio EVK boards

Boot Phase	Yocto Recipe	Partition Binary File	EMMC Partition Label	Rebuild with Recipe	Purpose
BL2	bl2	bl2.img	mmc0boot0	bl2	DRAM initialization
BL31	trusted-firmware-a	fip.bin	bootloaders	trusted-firmware-a	platform initialization
BL32	optee-os	fip.bin	bootloaders	trusted-firmware-a	secure environment
BL33	u-boot	fip.bin	bootloaders	trusted-firmware-a	EBBR boot, device tree loading and other OS bootstrap features
Download Agent	lk	lk.bin	N/A	lk	bootstrap binary used by genio-flash to initialize DRAM, storage to support fastboot protocol
U-Boot Env	board-assets	u-boot-env.bin	mmc0boot1	board-assets	Generated by genio-flash from u-boot-initial-env text file

Update Bootloader Binaries to the Board

After modifying the boot firmwares, you can use genio-tools to write the boot firmwares to the target storage, without modifying rootfs and other partitions:

cd baoshan-{UBUNTU_IMAGE}
genio-flash mmc0boot0 mmc0boot1 bootloaders

For detail usage please refer to Flash a Single Partition to Genio EVK.

Create New Board Support Layers

After successfully modify and rebuild boot firmwares for Genio EVK, you can now start adding your own board configuration and organize them in a separate directory.

In Yocto this involves following steps:

1. Add a new Yocto layer that overlays your board configurations on top of Genio EVK boards.

2. Declare new MACHINE configuration so the bitbake build system could properly apply the configuration for your new board.

3. Add bbappend files to include additional patches you need to apply to bootloader components.

Please refer to the following documentation:

• IoT Yocto Board Bring-Up

• Official Yocto Board Support Package Developer Guide

In most cases you also need to create a new Linux device tree for your board, and embed the new device tree binary into the boot firmwares. Follow the instructions in Modify Device Tree to do so.

Once the layer and machine configuration are ready, you can build the boot firmwares for your board with:

MACHINE=<your-board-name> bitbake board-assets

The devtool and genio-flash tools usage remains the same.