4.2 KiB
ADR-014: Trial Boot and Confirmation for System Updates
Context
A new system image can install correctly and still fail to start or run the main application. If the new system cannot start the OTA manager, that manager cannot request recovery.
This example assumes that the device can keep a previous working system while preparing a new one. Its boot control can select either system and read saved update state. An A/B layout, with two system slots, is one way to meet these conditions.
The device can check its essential functions locally. Installation, startup checks, and recovery must not require a continuous server connection.
Decision
Start a new system as a trial. Keep the previous working system available until the new system passes its required checks.
Boot control records each trial attempt before handing control to the new system. Allow a limited number of unconfirmed attempts. The platform design must set this limit and explain how an interrupted state write is handled.
Once the new system starts, local health checks test its essential functions within a defined time limit. Linux starting alone is not enough. If the checks pass, save confirmation and make the new system the normal boot choice.
If the checks fail, request a return to the previous system. If the new system never reaches the checks, boot control must select the previous system after the trial attempts are used up.
A hang must lead to a reset through a watchdog or another defined mechanism. A watchdog is a timer that can reset the device when software stops showing that it is alive. Its coverage must include the startup stages where the design requires automatic recovery.
After returning to the previous system, check its essential functions too. Save the outcome and report it when a connection is available. If the previous system also fails, follow a separately defined recovery policy rather than endlessly switching between versions.
Decision Drivers
- The device must recover even when the new system cannot start the OTA manager.
- A successful installation does not prove that the system works.
- Trial attempts must end within a defined limit.
- Local recovery must remain possible while the device is offline.
Alternatives Considered
Select the New System Permanently After Installation
This needs less boot state, but installation checks cannot detect all startup and application failures. It does not provide the required automatic return to a working system.
Let the OTA Manager Handle Every Failure
The manager can handle failures after it starts. It cannot handle a failure that prevents its own startup.
Wait for Server Confirmation
Server approval may be useful for some products. It is not used here because these devices can check their essential functions locally and must recover without a server connection.
Consequences
Positive
- Early boot failures can trigger recovery without the OTA manager.
- The device keeps a previous system until the new one passes its checks.
- Offline devices can finish the trial and report later.
Negative
- Boot control, health checks, and reset behavior must work together.
- Saved attempt and confirmation state must survive power loss.
- Storage is needed for the previous system.
- Poor checks can accept a broken system or reject a working one.
- The previous system may fail if the new version changed shared data.
Applicability and Limits
Use this approach when the platform supports selection of a retained system, reliable boot state, and a reset path for the failures being covered.
Retaining an old image does not guarantee recovery from damaged storage, failure of shared boot components, or incompatible data changes. Those cases need their own recovery design.
The platform must define the attempt limit, check time limit, confirmation owner, watchdog coverage, and behavior when recovery also fails. The exact storage format and bootloader commands belong in the platform example.