A/B Firmware Updates

A/B firmware updates ensure the firmware runs from the current slot, and the partition in the unused slot is used for the update. It allows to use two sets of partitions called slots. This approach reduces the chances of devices failing after it processes firmware update.

../../_images/sw_yocto_ab-part_flow.png

IoT Yocto supports the bootloader updates called firmware updates in these sections. The following sections describe A/B firmware updates provided by IoT Yocto.

About A/B Firmware Updates

IoT Yocto supports the updates via UEFI implementation in U-Boot to meet the requirements described in the Embedded Base Boot Requirements (EBBR) Specification. IoT Yocto provides the update support of slot A and slot B for BL3x images which includes TF-A (BL31), OP-TEE (BL32) and U-Boot (BL33).

Important

Please make sure the device is running stably when updating TF-A (BL2). IoT Yocto only supports a single partition for TF-A (BL2). Therefore, when updating TF-A (BL2) fails, it cannot be recovered and cannot be turned on.

  • If you want to update TF-A (BL2), make sure TF-A (BL2) and BL3x images are updated at the same time to ensure the consistent boot slot.

  • After applying the firmware updates, the device will change the slot to the one updated and try to reboot. If the device fails to boot and the number reaches the maximum retry value, it will roll back to the old slot to ensure that the firmware is available.

  • If the firmware updates request fails (for example, the update process was interrupted) for BL3x images, the device will not be affected. It will continue to boot from the old BL3x images until the next update.

Note

After applying the firmware updates successfully, please make sure that the device is booted into the kernel normally, otherwise the retry value will continue to increase.

Configure Firmware Images

The firmware images updated are called capsule files. It defines the GUID value, image index value and the name of the image to be updated by the Firmware Updates feature. You should create your own GUID for manufacturing and can also add your firmware partition updated for Firmware Updates.

An example of firmware GUID setting for Genio 1200-EVK is shown below:

  • You can refer to the image GUID defined in the mt8195.h of the U-Boot to add your definition:

#define GENIO_1200_EVK_FIP_IMAGE_GUID \
    EFI_GUID(0x39961e72, 0x5a8e, 0x445a, 0x90, 0xfe, \
        0xed, 0x68, 0x33, 0x07, 0x44, 0xec)

#define GENIO_1200_EVK_BL2_IMAGE_GUID \
    EFI_GUID(0xa4a60c91, 0xffa3, 0x4cb8, 0x9b, 0x2a, \
        0x4f, 0xf8, 0x13, 0x62, 0x0d, 0x22)

For example, add NEW_BOARD_BL2_IMAGE_GUID and NEW_BOARD_FIP_IMAGE_GUID for your new boards GUIDs. And then add the GUIDs to FWUPDATE_TFA_ID and FWUPDATE_FIP_ID for generating BL2 and BL3x capsule files using IoT Yocto.

  • The FWUPDATE_TFA_ID is defined for BL2 image in the bl2_2.6.bb:

FWUPDATE_TFA_ID="a4a60c91-ffa3-4cb8-9b2a-4ff813620d22"

FWUPDATE_FIP_ID="39961e72-5a8e-445a-90fe-ed68330744ec"

Note

The values must be set for all firmware images to be updated via the Firmware Updates mechanism.

Capsule Authentication

The UEFI specification defines the authentication method to ensure the secure update by capsule files. By default, IoT Yocto provides the development key and adds the firmware signatures to capsule files in IoT Yocto building system.

  • Please use the following commands to generate own key for manufacturing:

openssl req -x509 -sha256 -newkey rsa:2048 -subj /CN=CRT/ -nodes -days 365 -keyout u-boot-cap.key -out u-boot-cap.crt
cert-to-efi-sig-list u-boot-cap.crt u-boot-cap

Put the keys generated to the key files folder and then build all images using IoT Yocto:

DISTRO=rity-demo bitbake rity-demo-image

  • You can also use the tool mkeficapsule to create capsule files yourself without building system, as the following command:

mkeficapsule --private-key u-boot-cap.key --certificate u-boot-cap.crt --monotonic-count 1 --instance 0 --index <index> --guid <firmware_GUID> <firmware_file_name> <capsule_file_name>

The tool mkeficapsule can be built from U-Boot and you can enable the CONFIG_TOOLS_MKEFICAPSULE=y to build this tool.

Perform Firmware Updates

Capsule files are not passed to the firmware via the UEFI update service. It is used to obtain capsule files from the ESP partition by placing capsule files under the /EFI/UpdateCapsule directory. Check for capsule files in the directory only within the EFI partition on the device specified in the active boot option. IoT Yocto provides the partition called ESP partition for Firmware Updates feature. Partitions in detail describe more partition layouts for IoT Yocto.

Note

The capsule files in the ESP partition will be updated in the alphabetical order by filename.

Perform the firmware update as the following sequence of steps:

  • Put the capsule files to the specific directory /EFI/UpdateCapsule within the ESP partition.

  • Run the following commands to determine boot option in U-Boot mode:

=> efidebug boot add -b 0 0 mmc 0:8 fw.cap
=> efidebug boot next 0

Note

You should determine the boot option based on the storage device you used and the ESP partition in your partition layout.

The boot variable will be written to ubootefi.var located on the ESP partition to determine the boot option in BootNext. If the capsule file exists in the ESP partition and CONFIG_EFI_CAPSULE_ON_DISK_EARLY is enabled, on the next reboot, the Firmware Updates will start to write data until the following message appears:

Applying capsule ##### succeeded.

That means the firmware update is successful. The device will boot from the slot updated for BL3X and try to reboot.