.. include:: /keyword.rst ==================== 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. .. figure:: /_asset/sw_yocto_ab-part_flow.png :align: center :width: 900px |IOT-YOCTO| supports the **bootloader updates** called firmware updates in these sections. The following sections describe A/B firmware updates provided by |IOT-YOCTO|. .. contents:: Sections :local: :depth: 1 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 |G1200-EVK| is shown below: * You can refer to the image GUID defined in the `mt8195.h `_ of the U-Boot to add your definition: .. code:: #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 `_: .. code:: FWUPDATE_TFA_ID="a4a60c91-ffa3-4cb8-9b2a-4ff813620d22" * The FWUPDATE_FIP_ID is defined for BL3x images in the `trusted-firmware-a-mtk.inc `_: .. code:: 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: .. prompt:: bash # auto # openssl req -x509 -sha256 -newkey rsa:3072 -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|: .. prompt:: bash $ 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: .. prompt:: bash # auto # mkeficapsule --private-key u-boot-cap.key --certificate u-boot-cap.crt --monotonic-count 1 --instance 0 --index --guid 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. :ref:`sw/yocto/part-layout: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: .. prompt:: bash # auto => 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: .. code:: text Applying capsule ##### succeeded. That means the firmware update is successful. The device will boot from the slot updated for BL3X and try to reboot.