Is this page helpful?

Bootloader Updates in Torizon OS

Introduction

In this article you will learn why, when and how to perform bootloader updates with Torizon. It covers the preparation and update procedures, its limitations, known issues and technical details, including how bootloader updates relates to major upgrades of Torizon OS.

Bootloader in Torizon OS

Bootloader is the piece of software that loads the operating system into memory for execution along with other artifacts required by the OS to start its operation. Toradex System on Modules running Torizon OS as their OS employ U-Boot as bootloader.

Bootloader, OS and applications are usually first installed on a device in a production line as described in Production Programming in Torizon. Toradex also provides mechanisms to allow the update of any of these components after the device is out in the field, something that is made possible by means of the Torizon Cloud update features.

While updating the OS or the application in the field is a common and even recommended operation (e.g. to keep the system free of security vulnerabilities), updating the bootloader is not usually required nor recommended unless strictly needed; this is due to the fact that such an operation is generally deemed more risky in that some failures might leave a device in a state where recovery could require physically accessing it.

danger

Bootloader updates are not usually recommended — do it only when strictly needed.

Why Update the Bootloader

Despite the reservations against it, there are legitimate reasons one might need to update the bootloader, e.g.:

• When upgrading to a version of Torizon OS requiring a new bootloader: this would be a situation well advertised by Toradex and only expected to happen upon switches of the major version of the OS.
• When some feature provided within the bootloader is required by the customer: this could happen upon any release of Torizon OS but, again, it would be advertised as part of the OS release documentation.
• A security vulnerability in the Bootloader affecting the security of the system

Both situations are expected to be rare, but it is worth explaining why they are even possible to occur. The main reason is that the bootloader binary sometimes contains more than the just the code to load the operating system. For example, devices based on the i.MX 8 SoC have a bootloader binary that is actually a container holding multiple pieces of firmware and/or configuration data such as FDR memory timings, the System Controller Unit (SCU) firmware, the ARM Trusted Firmware (ATF) and any potential Cortex-M4 auxiliary firmware. When any of these are updated they may add new functionality and/or improve existing low-level functionality to be leveraged by the OS.

Disclaimer

Currently, not all risks of bootloader updates are mitigated by the Torizon Bootloader Update feature. The pros of keeping Torizon OS up-to-date with the latest software outweigh the risks described in the limitations & known issues.

Toradex will specifically recommend when and why to perform a bootloader update. While you are encouraged to perform the updates when recommended by Toradex, you are also encouraged to do so only when strictly required.

info

Currently Torizon Cloud provides support only for bootloader packages (binaries) built by Toradex. In the future, custom bootloaders may also be supported. If you are interested in such a feature, please contact us.

Prerequisites

• Device running Torizon OS 6 (see the Preparation section for more information).
• Device must have been provisioned to the Torizon Cloud.
• Basic knowledge of Torizon Updates.

In this article we focus on remote updates; please refer to First Steps with Torizon Remote Updates if you need to know more about the process.

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 TorizonCore 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, click show filters and click on the gears icon on the Package Sources pane.

2. On the Manage Package Sources dialog, hit the Add new package source button.

3. On the next dialog, enter the following Package source data URL:

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

4. The configuration to access the package source should be imported and shown in the dialog that follows; simply hit Add package source to confirm.

5. Back to the Package Sources pane, click on the refresh icon beside the newly added tdx-bootloader source. At this point, by enabling that package source you should be able to see the list of available bootloader packages.

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.

Purpose	Machine	Package version to use
OS major upgrade: 6.x.y → 7.x.y	apalis-imx6, colibri-imx6, colibri-imx6ull-emmc, colibri-imx7-emmc, verdin-imx8mm	2024.07-7.0.0+git.3f772959501c-r1
OS major upgrade: 6.x.y → 7.x.y	apalis-imx8	2024.04-7.0.0-devel+git.22d100d163d8-m1
OS major upgrade: 6.x.y → 7.x.y	colibri-imx8x	2024.04-7.0.0+git.22d100d163d8-r1
OS major downgrade: 7.x.y → 6.x.y	apalis-imx6, colibri-imx6, colibri-imx6ull-emmc, colibri-imx7-emmc	2022.07-6.8.0+git.e092e3250270-r22
OS major downgrade: 7.x.y → 6.x.y	apalis-imx8, colibri-imx8x, verdin-imx8mm, verdin-imx8mp	2022.04-6.8.0+git.a1eb18d157f4-r22

info

The bootloader package required for upgrading the verdin-imx8mp machine from Torizon OS 6.x.y to 7.x.y is currently unavailable due to issues that are under investigation. In the mean time, users can perform the OS upgrade without performing the bootloader update.

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 will be in the form <MACHINE>-bootloader (e.g. for an Colibri iMX.6 the actual name will be colibri-imx6-bootloader) and hit Continue.

3. Enable the appropriate package source (i.e. 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.c 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 in order to ensure a smooth transition between OS major versions.

The steps one is expected to follow for upgrading TorizonCore 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 TorizonCore 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.

Limitations & Known Issues

• No rollback is currently supported; if the device fails to boot with the new bootloader, recovery will probably involve some intervention on the device. Notice though, since we currently only support bootloader packages provided and tested by Toradex, a failure to boot is very unlikely to happen.
• 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 will show a message that may be wrongly interpreted as a problem, as can be seen below:

  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 below 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.