This document describes the high-level blocks present in SysOTA.

As of v0.1.0 SysOTA uses a service model, with sysotad presenting a set of D-Bus interfaces that the sysotactl and other programs interact with.

Boot Protocol

Boot protocol defines how SysOTA interacts with the boot system. The protocol assumes the A/B update system.

The protocol defines the following operations

1. Query: Check if A or B is currently active for booting.
2. Try: prepare the inactive slot for one-off boot.
3. Commit: make the inactive slot active.
4. Rollback: clean up files prepared by Try.

It is important to note that Rollback is only about the cleanup process and does not affect correctness. The Try operation allows the inactive slot to boot exactly once and the system returns to booting the active slot automatically.

Pi Boot

Pi Boot is an implementation of the boot protocol. This module relies on the mutable boot partition and on the tryboot.txt feature offered by the platform firmware. The boot directory is used as follows:

The slot-a/ and slot-b/ directories contain boot assets specific to each slot. The config.txt and tryboot.txt files are read and modified automatically to use the slot directories. This is done with the os_prefix=slot-{a,b}/ parameter.

The pre-install handler copies the boot assets to the slot-specific directory. The kernel command line file is also modified. The try operation creates tryboot.txt based on slot-specific config.txt. The post-install handler reboots the system with the "0 tryboot" argument to trigger the one-time-boot behavior. The commit operation renames tryboot.txt to config.txt. The rollback operation removes both tryboot.txt and the slot-specific directory corresponding to the inactive slot.

Other boot assets in the root of the boot partition are not updated since this presents atomicity challenges. This affects bootcode.bin, start.elf and fixup.dat. It does not affect the overlays as those participate in the os_prefix= mechanism.

The boot partition contains stale boot assets that are not used after the first update. Those are not removed yet.

RAUC Adapter

This component bridges the concrete implementation of the boot protocol with RAUC. It is visible as a set of RAUC handlers (bootloader, pre-install and post-install) that all call into SysOTA service.

This component is stateful. It remembers the boot mode (try or normal) that the system is in. Note that this is to allow detecting automatic rollback and performing cleanup, not for correctness of the boot protocol atomicity guarantees.

NetOTA Client

This component interacts with a NetOTA repository and allows performing the upgrade if the local package name and source revision are different to what is published online. This component is both stateful and configurable. State consists of the installed package name, installed package version and source revision. Configuration consist of the URL of the NetOTA server, package name and stream name.