Skip to main content

Update modules

EFI dual-partition module (efidualpartmodule)​

The EFI dual-partition module is designed to update boot partitions using a two-partitions approach. One partition is used for the update operation while another is used for reverting. Selecting which partition is used for the current boot is done by EFI. The update image is an archived partition dump. It is applied by copying raw data to the selected partition. Two partitions are used both for the update procedure and to increase boot redundancy. For example, if the active partition is corrupted or malfunctions, the system can boot from the second partition and try to restore the corrupted one.

Structure​

The following components are included in the boot partition update:

  • EFI – controlled by the update module and selects the boot partition.
  • boot partition A, boot partition B – the boot partitions used to update, revert and boot.
  • rootfs partition – the partition where UM and the EFI dual-partition modules reside.
  • efidualpart – the EFI dual-partition update module.
  • data partition – the partition where the update image is stored.
  • update image – update data that must be applied to the boot partition on update.

Unknown macro: diagram. Click on this message for details.

Implementation​

From the implementation point of view, the EFI dual-partition module consists of two packages:

  • dualpartmodule – implements copying the image data to the partition and controls EFI using StateController interface.
  • eficontroller – implements the stateController interface; controls EFI using EFI variables.

Unknown macro: diagram. Click on this message for details.

stateController interface:

  • GetCurrentBoot - returns the index of the partition from which the system was boot.
  • GetMainBoot - returns the index of the partition that was selected to boot first.
  • SetMainBoot - sets partition to boot first.
  • SetBootOK - confirms that the current boot is successful.
  • Close - closes resources allocated by the controller.

EFI controller​

EFI controller controls EFI using the EFI variables:

  • reads BootCurrent to get current boot partition index;
  • reads BootOrder to determine main boot partition index;
  • writes BootOrder to set the main boot partition index and confirm the boot is successful.

Vendor version​

The vendor version of the current boot partition image is located on the file system in the dedicated file. The path to this file is configured with the versionFile parameter in the UM configuration module. The boot partition is not mounted to rootfs. Thus to retrieve the vendor version information, the module mounts the dedicated boot partition and then reads the vendor version from file.

Sequence diagram​

On the boot, EFI selects boot partition A. Then the image is stored on a data partition (can be any suitable storage). The module copies the image data to boot partition B and instructs EFI to temporarily select partition B for the next boot and reboots the system. EFI boots partition B. The module checks if the boot is successful, copies the same image data into partition A and permanently selects partition B for booting.

See below a sequence diagram.

stateControllerstateControllerupdatehandlerupdatehandlerefidualpartefidualpartpartition Apartition Apartition Bpartition BBootInitSetBootOKOKPrepareOKUpdateCopy update imageSetMainBoot(B)rebootRequired, OKRebootsystem reboot =BootInitSetBootOKOKUpdateOKApplyCopy update imageOK

See below a sequence diagram for cases when booting from an updated partition fails.

stateControllerstateControllerupdatehandlerupdatehandlerefidualpartefidualpartpartition Apartition Apartition Bpartition BBootInitSetBootOKOKPrepareOKUpdateCopy update imageSetMainBoot(B)rebootRequired, OKRebootsystem reboot =BootFailedBootInitSetBootOKOKUpdateErrorRevertRestore part BOK

Overlay update module (overlaymodule)​

The overlay update module is designed to update a disk partition using overlay FS. This module performs the update using one working partition. It provides the possibility to try the update before applying it. This is implemented using a special script in initramfs. To achieve consistency and to increase the overall stability, the updated partition should be mounted in RO mode. The update image is deployed in the SquashFS format. The overlay update module supports full and incremental updates. In the case of the incremental update, only files that were changed compared to the previous version are included in the update image.

Structure​

The overlay update module includes the following parts to perform the partition update:

  • initrams – normally resides on the boot partition, it mounts the update image during update attempt and merges SquashFS image with the update partition’s FS upon updating.
  • overlaymodule – the update module which performs the partition update, may reside on the update partition or any other system partition.
  • update partition – a RO partition for module updates.
  • data partition – a RW partition used for storing the update image; communicates with the update module and initramfs.

Unknown macro: diagram. Click on this message for details.

Vendor version​

The vendor version is located in the dedicated file located on the updated partition. Path to this file is configured with versionFile parameter in the module configuration. The module reads this file to retrieve the current vendor version of the update partition.

Sequence diagram​

The basic update flow is like follows:

  1. The update image is stored on the data partition.
  2. The update module sets the update flag on the data partition (creates a do_update file that contains the update type, full or incremental.
  3. The system is rebooted.
  4. initramfs mounts the whole SquashFS image in case of a full update or mounts the SquashFS image over the update partition FS in case of incremental updating. Then initramfs sets the updated flag (creates an updated file) on the data partition to indicate that the update image is mounted. Then the system is launched using the mounted update image instead of the update partition.
  5. The update module checks if the mounted image has no errors and sets the apply flag for the data partition (creates a do_apply file).
  6. The system is rebooted.
  7. initramfs merges the SquashFS image to the update partition.

updatehandlerupdatehandleroverlaymoduleoverlaymoduledata partitiondata partitioninitramfsinitramfsPrepare(updateType)OKUpdatedo_update flagrebootRequired, OKRebootsystem reboot =do_updata flagMount squashfs imageupdated flagUpdateupdated_flagOKApplydo_apply flagrebootRequired, OKRebootsystem reboot =do_apply flagMerge squashfs imageApplyOK

U-Boot dual-partition module (ubootdualpart)​

The U-boot dual-partition module is designed to update the boot partition using a two-partitions approach. This module is similar to efidualpart but is controlled by U-Boot.

Structure​

The update of the boot partition includes the following components:

  • U-Boot – controlled by the update module with the ENV partition; selects the boot partition.
  • env partition – the partition where U-Boot environment variables are located.
  • boot partition A, boot partition B – the boot partitions used for updating, reverting and booting.
  • rootfs partition – the partition where UM and the EFI dual-partition module reside on.
  • ubootdualpart – the U-Boot dual-partition module.
  • data partition – the partition where the update image is stored.
  • update image – the update data to be applied to the boot partition upon updating.

Unknown macro: diagram. Click on this message for details.

Implementation​

The module uses the dualpartmodule package to update the boot partition and controls U-Boot through the stateController interface implemented by UbootController.

Unknown macro: diagram. Click on this message for details.

U-Boot controller​

U-Boot controls the U-Boot environment variable. It is stored on a disk partition accessible to both U-Boot and the U-boot dual-partition module. The following environment variables are implemented:

  • aos_boot1_ok, aos_boot2_ok – used to indicate a successful boot.
  • aos_boot_part – indicates the current boot partition’s index.
  • aos_boot_main – sets the main boot partition’s index.