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

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​

Bootloader Updates is a new feature in Torizon OS. We are collecting customer feedback and plan to make improvements over time.

Currently, some of the inherent risks to bootloader updates are not 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 provide 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​

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:

  • Upgrade to a version of Torizon OS supporting bootloader updates.
  • Ensure the bootloader packages provided by Toradex are accessible on their 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 first version of TorizonCore supporting bootloader updates is 5.7.2.

If the device is running a version of TorizonCore prior to 5.7.2, then it must be updated to a version having support for the bootloader update feature. In this case, the recommended approach is to update the OS to the latest version in the same series (5.x.y).

tip

If the device is running an older version of the OS then it must be updated to a version supporting the feature within the same major version currently installed.

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.

PurposeMachinePackage version
to use
OS major upgrade: 5.x.y → 6.x.yapalis-imx6, colibri-imx6, colibri-imx6ull-emmc, colibri-imx7-emmc2022.07-6.2.0-devel+git.e092e3250270-n216
OS major upgrade: 5.x.y → 6.x.yapalis-imx8, colibri-imx8x, verdin-imx8mm, verdin-imx8mp2022.04-6.2.0-devel+git.0e1f11392251-n216
OS major downgrade: 6.x.y → 5.x.yapalis-imx6, colibri-imx6, colibri-imx6ull-emmc, colibri-imx7-emmc2020.07-5.7.2-devel+git.1cbeecee44a8-n715
OS major downgrade: 6.x.y → 5.x.yapalis-imx8, colibri-imx8x, verdin-imx8mm, verdin-imx8mp2020.04-5.7.2-devel+git.33bb8e968332-n715

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 muiltiple pieces of firmware and newer versions of the OS may require those firmware to be installed to boot up propertly. 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 5.x.y to 6.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 5.6.0, you should first update it to 5.7.2+.
  2. Upgrade the bootloader to the appropriate version for the major transition.
  3. Upgrade the OS to the new major (6.x.y).

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

  1. Downgrade the OS to the latest version of the OS in the 5.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 5.x.y series. Notice, however, that downgrading the OS is not generally recommended or tested by Toradex at the moment. 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 and TPL — Secondary and Tertiary program loaders). This ensures both parts of the bootloader are always updated in tandem.

Limitations & Known Issues​

  • Offline bootloader updates are still not supported. There are plans to add support.

  • 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 that 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...
  • TorizonCore 5.7.2 introduces a new component to TorizonCore which is the one responsible to receiving bootloader updates. When a device is updated to version 5.7.2+ this new component is registered to the Platform Services and, if the OS is downgraded to a version before 5.7.2, the same component gets unregistered from the Platform. If one tries to upgrade the OS a second time then the registration of the same component will be denied by the Platform due to security reasons. Because of this, we strongly discourage downgrading the OS to a version before 5.7.2 once that version (or later) is installed. Adding to this, there is also an issue on the device-side as described in the next section.

  • Related to the limitation above, if one tries to upgrade the OS to version 5.7.2+ for a second time after having downgraded to a version before 5.7.2, the attempt to register the component that deals with bootloader updates will be denied by the Platform. Unfortunately, this situation is not currently handled gracefully by the device-side which will enter a loop repeating the attempts and the OS update will never end. The Aktualizr logs will display something like this:

    Feb 23 19:25:05 colibri-imx7-emmc-06700281 aktualizr-torizon[730]: Not provisioned yet: Device was not able provision on-line

    To leave this state, run the following command on the affected device:

    # rm -rf /var/sota/storage/bootloader
  • 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. At the time of writing, the fix for this issue is present only on nightly pre-release versions of the installer after 2022-12-14 (inclusive). When version 5.7.2 of the installer becomes available it will include the fix.



Send Feedback!