Skip to main content
Version: Torizon OS 7.x.y

How to Use Bootloader Updates with Torizon OS

Introduction​

This article presents the steps to perform bootloader updates with Torizon Cloud and devices running Torizon OS.

Prerequisites​

This article focuses on remote updates. To know more about how the update runs, see The Update Process in the Remote OTA Updates Overview.

Preparation​

To prepare for the update, you should:

  • Ensure the device is running a version of Torizon OS supporting bootloader updates (this should always be the case with Torizon OS 6).
  • Ensure the bootloader packages provided by Toradex are accessible on your platform account.
  • Choose an appropriate version of the bootloader to switch to.

These items are described next.

Upgrade to a Version of Torizon OS Supporting Bootloader Updates​

The present article assumes a device is running Torizon OS 6, which has support for bootloader updates out-of-the-box. If the device is instead running an earlier major version of the OS, the recommendation is to first update it to the latest Torizon OS 6 version (by following Upgrading from TorizonCore 5.x to Torizon OS 6.x) and continue from here afterward. The reason for this recommendation is that skipping majors is not a use case actively tested by Toradex.

Add Bootloader Packages Source to the Platform Account​

Bootloader packages are made available to Platform Services accounts by means of a special package source called tdx-bootloader. Before attempting to perform a bootloader update, please make sure that source is present on your account. To do this, access your account on app.torizon.io and select "Packages" on the side menu; then check the list of package sources to see if tdx-bootloader is there. If not, then add it manually by following these steps:

  1. Again, access "Packages" on the side menu.

  2. Click on the Sources filter and then Manage Sources.

  3. On the Manage Package Sources dialog, hit the Add Source button.

  4. On the next dialog, select From URL, and copy the Package Source URL:

    https://artifacts.toradex.com/artifactory/torizoncore-bootloader-prod-frankfurt/tdx-bootloader-src.json

  5. Then, click Fetch Data.

  6. Give the new Source a Label. Click on continue and then Save Package Source.

  7. Back to the Package page, you can now select the new source in the Sources filter.

Choose the Bootloader Package Version​

In all cases, the package name to be employed is of the form bootloader/<MACHINE>/u-boot-ota.bin where <MACHINE> is the machine name as defined by Toradex BSP layers. This piece of information can be determined on a live device by running:

# echo $MACHINE

The following table defines the package version that shall be used depending on the purpose of the update and the target machine.

PurposeMachinePackage version
to use
OS major upgrade: 6.x.y → 7.x.yapalis-imx6, colibri-imx6, colibri-imx6ull-emmc, colibri-imx7-emmc, verdin-imx8mm2024.07-7.0.0+git.3f772959501c-r1
OS major upgrade: 6.x.y → 7.x.yapalis-imx82024.04-7.0.0-devel+git.22d100d163d8-m1
OS major upgrade: 6.x.y → 7.x.ycolibri-imx8x2024.04-7.0.0+git.22d100d163d8-r1
OS major upgrade: 6.x.y → 7.x.yverdin-imx8mp2024.07-7.1.0+git.3f772959501c-r4
OS major downgrade: 7.x.y → 6.x.yapalis-imx6, colibri-imx6, colibri-imx6ull-emmc, colibri-imx7-emmc2022.07-6.8.0+git.e092e3250270-r22
OS major downgrade: 7.x.y → 6.x.yapalis-imx8, colibri-imx8x, verdin-imx8mm, verdin-imx8mp2022.04-6.8.0+git.a1eb18d157f4-r22
warning

For a smooth upgrade experience, be sure to follow the instructions carefully, as outlined in the following sections. In particular, skipping the step of upgrading the OS to the latest version in the series before updating the bootloader may cause some devices (for example, the Verdin-imx8mp) to hang during boot.

Performing a Bootloader Update​

Updating the bootloader of a device is no different from updating the Torizon OS or the Application. The steps are:

  1. Select the device on the Torizon Cloud web interface and hit Initiate Update.
  2. The web interface should ask which component needs to be updated; select the one referring to the bootloader, whose name is in the form <MACHINE>-bootloader (for example for an Colibri iMX.6 the actual name is Colibri-iMX6-bootloader) and hit Continue.
  3. Enable the appropriate package source (that is tdx-bootloader) and select in the UI the desired package plus its version (as chosen in the preparation step); then hit Continue again.
  4. Finally confirm the operation.

To follow up the progress of the update, one can look at the Aktualizr logs on the device by running:

# journalctl -fu aktualizr\*

Major Upgrades and Downgrades of Torizon OS​

When the bootloader update is being performed with the purpose of a Torizon OS major number upgrade or downgrade, it is important to note that the bootloader update itself is just a step of a multi-step process. Also, as pointed out in the introductory section, the bootloader package may contain multiple pieces of firmware and newer versions of the OS may require those firmware to be installed to boot up properly. In general, newer versions of the bootloader are guaranteed to be compatible with older versions of the OS. Considering these points, there is a certain sequence of updates to be followed to ensure a smooth transition between OS major versions.

The steps one is expected to follow for upgrading Torizon OS from 6.x.y to 7.x.y are:

  1. Upgrade to the latest version of the OS within the same series. For example, if your device is currently running Torizon OS 6.6.0, you should first update it to 6.8.0+.
  2. Upgrade the bootloader to the appropriate version for the major transition.
  3. Upgrade the OS to the new major (7.x.y).

On the other hand, for downgrading Torizon OS from 7.x.y back to 6.x.y one should:

  1. Downgrade the OS to the latest version of the OS in the 6.x.y series.
  2. Downgrade the bootloader to the appropriate version for the major transition.
  3. Downgrade the OS to the desired version within the 6.x.y series. Notice, however, that downgrading the OS is not generally recommended or tested by Toradex. The limitations & known issues section has more information relevant to this topic.

As a last point, Torizon OS has a feature where the OS and the application can be updated simultaneously, the so-called synchronous update. Bootloader updates are not covered by that feature and must be always done as a single independent update.

Technical Details About Bootloader Packages​

  • The bootloader update feature uses an A/B partitioning scheme where a new bootloader is written into an inactive boot partition; after checking the data was correctly written, the inactive partition is made the active one using an atomic hardware switch (provided by the eMMC device).
  • The bootloader packages available through the Torizon Cloud are always single binaries. This is unlike the form they are present within the Toradex Easy Installer image of some devices where the program is split into two binaries (SPL (Secondary Program Loader) and main bootloader binary). This ensures both parts of the bootloader are always updated in tandem.

Custom Bootloader Updates​

In some cases it might be needed to upload your own bootloader package to use in a bootloader update. Examples of such cases include, bootloaders that have been customized in some way, or a bootloader that have been signed for secure-boot purposes. In any case, if it is needed to update the bootloader on your devices with some bootloader not from the Toradex provided package source, then you need to know how to upload your own bootloader package.

Custom Bootloader Prerequisites​

Uploading Your Bootloader Package​

From your Yocto build you need two files. Both can be found in the deploy/images/<MACHINE> directory of your build environment:

  • u-boot-ota.bin (*): This is the bootloader binary file to be uploaded.
  • u-boot-ota.json (*): This file contains information that must be uploaded with the preceding binary.

(*) For SoMs based on TI SoCs (for example verdin-am62), there are actually multiple bootloader binaries generated from a build, each targeting a different device type, namely:

  • u-boot-ota-gp.bin: Targeting General Purpose devices.
  • u-boot-ota-hs-fs.bin: Targeting High-Security Field-Securable devices (secure devices in the "open" state in terms of Secure Boot).
  • u-boot-ota-hs.bin: Targeting High-Security Security-Enforced devices (secure devices in the "closed" state in terms of Secure Boot).

The information file in these cases has the same name of the binary, but the .json extension. In the text that follows, when this article mentions u-boot-ota.bin/u-boot-ota.json, please replace those names with the appropriate binary/json pair for the desired device type.

With your json and binary files in hand, using TorizonCore Builder you can upload your bootloader binary with the following command:

$ torizoncore-builder platform push-bootloader --credentials credentials.zip --hardwareid <MACHINE>-bootloader --uboot-json u-boot-ota.json u-boot-ota.bin

Optionally, you can also use the --package-name and --package-version flags with the preceding TorizonCore Builder command. This way you can control the name and version this package shows up as in the Torizon Cloud web UI.

Update Process​

Once your bootloader package has been uploaded to Torizon Cloud, you can use it to perform bootloader updates using the same process as described in the "Performing a Bootloader Update" section. Finally, it is important to test bootloader updates with any custom uploaded bootloader packages. The packages from Toradex have been tested to make sure they do not cause any major issues during an update. Therefore, bootloader packages uploaded via this method should be tested to ensure they do not cause issues on your devices.

Limitations & Known Issues​

  • No rollback is currently supported; if the device fails to boot with the new bootloader, recovery probably involves some intervention on the device. Bootloader packages provided and tested by Toradex, are very unlikely to cause a failure to boot.
  • The update is not generally robust to hardware resets/power cuts, so if such an event happens during some critical periods of the process, the device may be left in a state where recovery would require some kind of intervention (most likely remote). The chances of the device being "bricked" are very low though due to A/B partitioning scheme used at the low-level implementation.
  • Because the bootloader installation requires a reboot, the Aktualizr logs show a message that may be wrongly interpreted as a problem, as can be seen following: 
    Aug 25 19:17:21 colibri-imx7-emmc-06700281 aktualizr-torizon[840]: Action-handler "/usr/bin/bl_actions.sh" message: rebooting soon
    Aug 25 19:17:21 colibri-imx7-emmc-06700281 aktualizr-torizon[840]: Event: InstallTargetComplete, Result - Error
    Aug 25 19:17:21 colibri-imx7-emmc-06700281 aktualizr-torizon[840]: Event: AllInstallsComplete, Result - NEED_COMPLETION
    Aug 25 19:17:21 colibri-imx7-emmc-06700281 aktualizr-torizon[840]: Update install completed. Releasing the update lock...
  • To perform a bootloader update, Torizon OS switches the active boot partition through the eCSD registers of the eMMC device; Toradex Easy Installer version 5.7.1 and following do not reset the active boot partition which means that if a device underwent a bootloader update it may not boot from the proper boot partition even after an installation with the installer. Version 5.7.2 and newer of the installer already include a fix for this issue.
Send Feedback!