Dual System mechanism

Note
Please refer to the Product Technical specification document of your platform for further details.

The dual system consists in managing 2 copies of most code areas, for reliability and stability purposes. One copy is a backup in case the other one is corrupted or not running properly. The running system is called ACTIVE and the other system (not running) is called UPDATE. One cannot write in ACTIVE system. Only UPDATE system is in RW mode. In the next figure, this dual-system architecture is detailled. Some partitions are duplicated, for dual-system purpose, and some other are shared between the two systems (mainly data).

le_fwupdate_DualSys_Summary.svg

There are 3 operations to manage the dual system: MARKGOOD, INSTALL and INSTALL&MARKGOOD.

  • INSTALL operation consists in a reboot, followed by a switch between ACTIVE & UPDATE systems. Legato will mark the ACTIVE system as UPDATE one, the UPDATE system as ACTIVE one and then it will load the ACTIVE system.
le_fwupdate_Install.svg
  • MARKGOOD operation consists in a copy of ACTIVE system into UPDATE one by APPS. No new downloads are possible without a successful MARKGOOD issued previously. So it means that in a stable situation, both systems are identical (same version N).
le_fwupdate_MarkGood.svg
  • INSTALL&MARKGOOD operation consists in a reboot, followed by a switch between ACTIVE & UPDATE systems in Legato, followed immediately by a copy of ACTIVE system into UPDATE system.
le_fwupdate_InstallAndMarkGood.svg

System update

The user is able to update a whole system by downloading a package and accepting the update. Using this mechanism, the user can update the UPDATE system. Then, by calling le_fwupdate_Install(), the user can request to swap to the new downloaded system.

Package download

To launch a package download, the service user can call the le_fwupdate_Download() API which is a blocking API. When the package download is over and succeeds, this API returns LE_OK.

Warning
If any Legato reset happens during the package download, a new download will be required at next startup. If any issue occurs during the le_fwupdate_Download() API treatment, this API returns LE_FAULT and the application will need to synchronize partitions by calling le_fwupdate_MarkGood() API which occurs a device reboot. Synchronizing partitions is necessary before calling again the le_fwupdate_Download() API. To know if both systems are synchronized, the le_fwupdate_IsSystemMarkedGood() API can be called.

Update request

Once the package download is over (meaning that le_fwupdate_Download() API returns LE_OK), the user is able to accept or cancel the FW update. To do that, the le_fwupdate_Install() (accept the update) or the le_fwupdate_MarkGood() (refuse the update) API can be used.

Warning
If any Legato reset happens before accepting the FW update, a new download will be required at next startup. Accepting a FW update (le_fwupdate_Install()) will initiate a device reboot without returning any result. Rejecting a FW update will initiate a synchronization without any device reboot.

Partition synchronization

The user can check if the ACTIVE and UPDATE partition are synchronized by calling the le_fwupdate_IsSystemMarkedGood() API. This API can be used before calling le_fwupdate_Download() in order to check that the download can be treated. The user can request an INSTALL operation by calling le_fwupdate_Install().

Reset APIs

The user can use a reset API to initiate an installation or an installation and mark good. See le_fwupdate_Install() and le_fwupdate_InstallAndMarkGood().

GetUpdateStatus APIs

The statusLabel string returns by le_fwupdate_GetUpdateStatus() can be:

  • A general status (see le_fwupdate_UpdateStatus_t):
    • "No bad image found"
    • "Download in progress"
    • "Download failed"
    • "Download timeout"
    • "Unknown status"
  • The partition name where the first error has been encountered:
    • "sbl"
    • "mibib"
    • "Reserved1"
    • "sedb"
    • "Reserved2"
    • "tz_1"
    • "tz_2"
    • "rpm_1"
    • "rpm_2"
    • "modem_1"
    • "modem_2"
    • "aboot_1"
    • "aboot_2"
    • "boot_1"
    • "boot_2"
    • "system_1"
    • "system_2"
    • "lefwkro_1"
    • "lefwkro_2"
    • "customer0"
    • "customer1"

Copyright (C) Sierra Wireless Inc.