Welma Delta Update¶

Welma provides delta update support to reduce the size of software update artifacts and the amount of data transferred to the target. Instead of distributing complete new versions of software modules, a delta update contains only the data required to reconstruct the new versions from specific reference versions.

Delta updates rely on the Welma Software Version Control feature to identify the module versions from which the deltas were generated and to ensure that each delta is only applied to the expected version of the corresponding running module.

Overview¶

A delta update is generated from one or more pairs of module images. Each pair contains:

a reference module, representing the version expected to be installed on the target;
a new module, representing the version to be installed.

For example:

       Reference modules     New modules
       +----------------+    +--------+-------+
       |  appro v1.0.0  |    |  appro v2.0.0  |
       |  sysro v3.0.0  |    |  sysro v4.0.0  |
       +--------+-------+    +--------+-------+
                │                     │
                +----------+----------+
                           |
             +-------------v-------------+
             |  welma-delta-update-tool  |
             +-------------+-------------+
                           |
                   +-------v--------+
                   |   update.swu   |
                   +-------+--------+
                           │
               +-----------+-----------+
               |                       |
  +------------v----------+ +----------v------------+
  | appro v1.0.0 → v2.0.0 | | sysro v3.0.0 → v4.0.0 |
  +-----------------------+ +-----------------------+

Each reference/new pair produces a delta patch. All generated patches are packaged into a single standard Welma SWU artifact.

For example, a bundle containing a delta for appro from version 1.0.0 to 2.0.0 and a delta for sysro from version 3.0.0 to 4.0.0 can only be installed if the running versions of both modules match their respective reference versions.

The generated bundle is a standard Welma SWU artifact and can therefore be installed through the regular Welma software update interface.

Delta updates currently have the following characteristics:

Only A/B modules are supported.
Only the SWUpdate backend is supported.
A delta artifact can contain one or more module delta patches.
Each delta is generated between two different versions of the same module.
The currently supported delta algorithm is rsync, using the rdiff support provided by SWUpdate.

Runtime architecture¶

Delta Update extends the version information provided by the Software Version Control feature with a reference version.

For each module contained in a delta update, the module tag identifies both the version to install and the version from which the delta was generated.

For example:

Name: appro
Version: 2.0.0
RefVersion: 1.0.0

The reference version (refVersion) is not a module dependency. It identifies the exact version required as the input for reconstructing the new module.

Delta information in version tags¶

Welma version tags have a fixed size of 2048 bytes and reserve space for up to 30 compatibility rules of 64 bytes each. Delta information is stored immediately after the reserved compatibility rules area.

For more details about tag structure, please refer to Version Control - Tag Structure.

For a delta update, this area contains:

Size      Field                Description
----      -----                -----------
4         DELTA MAGIC          "DLTA"
30        Reference Version    Reference module version

The DELTA MAGIC field identifies that the tag contains delta update information.

The reference version uses the same format as the standard module version field.

A regular module does not contain a delta reference version. The presence of valid delta information in the tag therefore allows Welma to identify a module update as a delta update.

When welma-delta-update-tool generates a delta, it uses welma-tagtool to read the module tags and add the corresponding reference version information to the update module tag.

For more details about welma-tagtool, please refer to Version Control - welma-tagtool.

Delta update validation¶

Before a delta artifact is submitted for installation, the updated daemon verifies that each delta contained in the artifact can be applied to the corresponding running module.

For each module delta, updated reads the reference version from the artifact and compares it with the version stored in the tag of the corresponding running module.

The validation sequence can be summarized as follows:

                 +--------------------+
                 |  Delta SWU bundle  |
                 +---------+----------+
                           │
                 +---------v----------+
                 |      updated       |
                 +---------+----------+
                           │
              +------------v--------------+
              | Parse module version tags |
              +------------+--------------+
                           │
             +-------------v---------------+
             | Validate reference versions |
             +-----------------------------+
                           │
             +-------------+------------+
             │                          │
  +----------v-----------+    +---------v----------+
  | All references match |    | Reference mismatch |
  +----------+-----------+    +---------+----------+
             |                          │
  +----------v-----------+       +------v-------+           
  | Compatibility checks |       |    Reject    |
  +----------+-----------+       +--------------+
             │
+------------v--------------+
| Submit bundle to SWUpdate |
+------------+--------------+
             │
+------------v---------------+
| Delta handler installation |
+------------+---------------+
             │
 +-----------v-------------+
 |Verify installed versions|
 +-------------------------+

For example, consider a bundle containing:

appro:  reference 1.0.0 --> new version 2.0.0
sysro:  reference 3.0.0 --> new version 4.0.0

If the running system contains:

appro 1.0.0
sysro 3.0.0

the reference version checks succeed and the normal Software Version Control compatibility checks are performed.

If one of the running modules does not match its reference version, the delta update is rejected.

For example:

Artifact                       Running system

appro 1.0.0 --> 2.0.0          appro 1.0.0    OK
sysro 3.0.0 --> 4.0.0          sysro 3.1.0    KO

The entire artifact is rejected because the sysro delta was generated from version 3.0.0 and therefore cannot be applied to version 3.1.0.

This check is required even if the versions would otherwise be compatible according to their dependency rules. A delta is generated from the binary contents of a specific reference module and must therefore only be applied to that reference.

Once all reference versions have been validated, the standard Software Version Control compatibility checks are performed. If they succeed, the artifact is submitted to SWUpdate.

For the rsync algorithm, each delta is handled using the rdiff support provided by SWUpdate.

After installation, updated performs the same version verification as for a regular update and checks that the installed module versions match the versions announced by the update artifact.

Delta update generation¶

Welma provides the welma-delta-update-tool command-line tool to generate delta update artifacts outside of the regular Yocto build.

The tool accepts one or more pairs of tagged module images and generates a single Welma SWU bundle containing the corresponding delta patches.

Requirements¶

welma-delta-update-tool requires welma-tagtool to read and manipulate Welma version tags.

The path to welma-tagtool can be specified through the WELMA_TAG_TOOL environment variable:

WELMA_TAG_TOOL=/path/to/welma-tagtool

If the variable is not specified, welma-delta-update-tool searches for welma-tagtool in PATH.

Basic syntax¶

WELMA_TAG_TOOL=<welma-tagtool> welma-delta-update-tool \
    -b BACKEND \
    -d REF_VERSION_MODULE NEW_VERSION_MODULE \
    [-d REF_VERSION_MODULE NEW_VERSION_MODULE ...] \
    -a ALGO \
    -o OUTPUT_PATH \
    [-k KEY]

The -d / --delta option defines one reference/new module pair. It can be specified multiple times to include several delta patches in the same update bundle.

Each occurrence of -d or --delta must be immediately followed by exactly two module paths:

--delta <reference-module> <new-module>

For multiple modules, the option must be repeated:

--delta <reference-1> <new-1> \
--delta <reference-2> <new-2> \
--delta <reference-3> <new-3>

Command-line options¶

Option	Argument	Description
`-b`, `--backend`	`BACKEND`	Backend used to generate the update artifact. Only`swu` is supported currently
`-d`, `--delta`	`REF_VERSION_MODULE NEW_VERSION_MODULE`	Reference and new module images used to generate a delta patch. The option can be specified multiple times
`-a`, `--algo`	`ALGO`	Delta algorithm to use. Currently only `rsync` is supported
`-k`, `--key`	`KEY`	Key used to sign the generated update artifact. Optional
`-o`, `--output`	`OUTPUT_PATH`	Output path of the generated update artifact
`-h`, `--help`		Display the help message

Validation¶

Before generating the update artifact, welma-delta-update-tool validates all module pairs supplied through --delta.

For each pair, the tool ensures that:

both input modules contain valid Welma version information;
the reference and new images belong to the same module;
the reference and new versions are different;
the requested delta algorithm is supported.

The tool uses welma-tagtool to retrieve the version information from each module and to add the corresponding reference version to the tag of the new module.

All input pairs are validated before the final SWU bundle is generated.

Single-module example¶

The following command generates a delta update for the appro module from version 1 to version 2:

WELMA_TAG_TOOL=$SRC/welma-tagtool ./welma-delta-update-tool \
    -b swu \
    --delta appro-v1 appro-v2 \
    -a rsync \
    -o update.swu \
    -k "$SWK1"

This produces a single SWU artifact containing the delta required to update appro from version 1 to version 2.

Multi-module bundle example¶

Multiple --delta options can be used to generate a single update bundle containing several delta patches:

WELMA_TAG_TOOL=$SRC/welma-tagtool ./welma-delta-update-tool \
    -b swu \
    --delta appro-v1 appro-v2 \
    --delta sysro-v3 sysro-v4 \
    --delta config-v1 config-v2 \
    -a rsync \
    -o update.swu \
    -k "$SWK1"

The command generates three independent delta patches:

appro-v1  --> appro-v2
sysro-v3  --> sysro-v4
config-v1 --> config-v2

and packages them into a single artifact:

                         update.swu
                             │
               +-------------+-------------+
               |             |             |
               v             v             v
          appro patch    sysro patch   config patch
           v1 -> v2       v3 -> v4      v1 -> v2

The order of the two arguments following each --delta option is significant: the first argument is always the reference module and the second is always the new module.

The --delta option must be repeated for every module pair. For example, the following syntax is not valid:

--delta appro-v1 appro-v2 sysro-v3 sysro-v4

Instead, use:

--delta appro-v1 appro-v2 \
--delta sysro-v3 sysro-v4

On successful generation, the tool reports:

Delta update module created successfully at <path>

The resulting update.swu is a standard Welma SWU update artifact and can be installed using the regular software update interface.

Yocto configuration¶

No specific Yocto configuration is required to enable Delta Update.

Runtime support in updated and SWUpdate is provided by default when the corresponding Welma software update and Software Version Control components are used.

Delta artifacts are not automatically generated as part of the BitBake build. They are explicitly generated using welma-delta-update-tool from previously built and tagged module images.