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: SYNC, SWAP and SWAP&SYNC.

  • SWAP 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_DualSysSwap.svg
  • SYNC operation consists in a copy of ACTIVE system into UPDATE one by APPS. No new downloads are possible without a successful SYNC issued previously. So it means that in a stable situation, both systems are identical (same version N).
le_fwupdate_DualSysSync.svg
  • SWAP&SYNC 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_DualSysSwapAndSync.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_DualSysSwap(), 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_DualSysSync() 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_DualSysSyncState() 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_DualSysSwap() (accept the upate) or the le_fwupdate_DualSysSync() (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_DualSysSwap()) 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_DualSysSyncState() 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 a SYNC operation by calling le_fwupdate_DualSysSync().

Reset APIs

The user can use a reset API to initiate a partition swap or a swap and synchronization. See le_fwupdate_DualSysSwap() and le_fwupdate_DualSysSwapAndSync().

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(N/A)"
    • "MIBIB(N/A)"
    • "Reserved1 - "SEDB(N/A)" - "Reserved2
    • "TZ(system 1)"
    • "TZ(system 2)"
    • "RPM(system 1)"
    • "RPM(system 2)"
    • "Modem(system 1)"
    • "Modem(system 2)"
    • "LK(system 1)"
    • "LK(system 2)"
    • "Kernel(system 1)"
    • "Kernel(system 2)"
    • "Root file system(system 1)"
    • "Root file system(system 2)"
    • "User data(system 1)"
    • "User data(system 2)"
    • "Customer application(system 1)"
    • "Customer application(system 2)"

Copyright (C) Sierra Wireless Inc.