Update handler (updatehandler)
The update handler manages update modules (plugins) and orchestrates simultaneous updates of multiple components. The update handler implements the principle of atomic updating. This means that if an update image contains updates for several components, all these components must be updated to new versions or reverted to the previous state.
The update procedure is divided into the following stages:
| Stage | Description |
|---|---|
| prepare | each module validates its own part of the update image and performs initial update actions. |
| update | each module tries to update the corresponding system component and checks the update result. Any module can request a reboot operation. Modules can receive either an apply or revert request after this stage. |
| apply | this stage means thatr all components are updated successfully and no further revert will be requested. Any module can request a reboot operation. |
| revert | each module reverts the component to the previous state. Any module may request reboot operation. |
| reboot | each module reboots the corresponding system components. |
State machine
The update handler implements the state machine according to the above stages. Initially, the update handler is in idle state. The state is stored in the database thus after reboot, the update handler stays in the state before reboot.
plantuml37765793039873204.png
Module priorities
The update handler interacts with update modules through the UpdateModuleUpdate modules interface. Each module has its own priority. The priority is defined in the UM configuration file with the updatePriority and rebootPriority parameters. The updatePriority parameter is used for update-related operations (prepare, update, apply, revert), whereas the rebootPriority parameter is used for the reboot operation. Operations for modules with the same priorities are performed in parallel. The operations for higher priority modules are performed before operations for lower priority modules. By default, modules have priority 0 (the lowest) for updating and rebooting. Module initialization
At the start, the update handler calls Init module API for each configured module according to the update priority. At this call, each module should perform its initialization and validation. The update handler sends the current state to SM only after all modules are initialized.
Module operations
On receiving a prepare command from SM, UM prepares each module related to the current update and goes either to the prepared state if all modules are prepared or to the failed state if preparing one of the modules fails. The update handler performs a similar pattern for all commands received from SM: it performs the required operation for all related modules and goes to the next state in case all modules perform the requested operation successfully or to failed state if at least one module operation fails. The update handler returns back to the idle state from error state only by revert operation. The update handler can receive revert requests at any state. It reverts each related module and returns to the idle state.
Prepare
See below a sequence diagram of preparing two components (rootfs and boot).
Update, apply and revert
See below a sequence diagram for updating two components (rootfs and boot).
Any module can request reboot operation. In this case, the update handler calls the module reboot API according to the reboot priority after all modules are updated. Then the update handler calls the update API again for those modules. The module can request rebooting again, and update will be called again until the module doesn’t request rebooting.
The apply and revert operations are performed in the same way.