Skip to content
This repository has been archived by the owner on Jun 7, 2023. It is now read-only.

Latest commit

 

History

History
238 lines (161 loc) · 8.68 KB

UPDATE.md

File metadata and controls

238 lines (161 loc) · 8.68 KB
Raw

Update

This documents describes how to create an update bundle. The update bundle contains update images for all system components. Current system consists of following components:

  • dom0: disk partition on which boot and Dom0 initramfs are located;
  • domd: DomD rootfs;
  • domf: DomF rootfs.

Prerequisites

  1. Update variables are configured in the build configuration file (INSTALL.md)

    In most cases only this variable should be set in the configuration file:

    • BUNDLE_OSTREE_REPO - indicates where ostree repo should be located.

      ostree is an analog of git for the binary files. It is used by the update generator to make incremental updates. The ostree repo should be persistent between different version builds. That's why it should be put outside workspace_base_dir. Because workspace_base_dir is removed on the new version build.

    Others optional update configuration variables:

    • BUNDLE_DIR - indicates where update bundles should be located.

      By default, update bundles are located in ${workspace_base_dir}/build/deploy/update.

    • BUNDLE_DOM0_TYPE - update type for Dom0:

      • "full" - to generate full Dom0 update (Dom0 supports only full update);
      • "" - empty value to do not include Dom0 update into the update bundle.

      By default it is set to "full".

    • BUNDLE_DOMD_TYPE - update type for DomD:

      • "full" - to generate full DomD update ;
      • "incremental" - to generate incremental DomD update;
      • "" - empty value to do not include DomD update into the update bundle.

      By default it is set to "full".

    • BUNDLE_DOMF_TYPE - update type for DomF:

      • "full" - to generate full DomF update ;
      • "incremental" - to generate incremental DomF update;
      • "" - empty value to do not include DomF update into the update bundle.

      By default it is set to "full".

    Each system component has its own vendor version. The default vendor versions values are defined in xt_shared_env.inc. If overriding default component versions is required, the following variables shall be set:

    • BUNDLE_IMAGE_VERSION - used as suffix to the update bundle name in ${BUNDLE_DIR}';
    • DOM0_IMAGE_VERSION - Dom0 vendor version;
    • DOMD_IMAGE_VERSION - DomD vendor version;
    • DOMF_IMAGE_VERSION - DomF vendor version;

    The incremental update requires reference vendor version to compare current rootfs snapshot with. Reference vendor versions can be overridden by the following variables:

    • DOMD_REF_VERSION - DomD reference vendor version;
    • DOMF_REF_VERSION - DomF reference vendor version;

    Example build configuration:

    [path]
# this shall be fast drive for doing most of the build on
workspace_base_dir = /builds/prod-aos-h3ulcb

# place where we store files which can be re-used, artifacts storage
workspace_storage_base_dir = /builds

# place where we store SSTATE_DIR and ccache
workspace_cache_base_dir = /builds/tmp

[local_conf]
# correct path to the eva archives set
# XT_RCAR_EVAPROPRIETARY_DIR = "/path/to/eva/archives"
# guests domains which to be built and installed
XT_GUESTS_INSTALL = "domf"
XT_GUESTS_BUILD = "domf"
# aos specific local.conf configuration
BBMASK = "../meta-aos/recipes-aos"
BUNDLE_OSTREE_REPO = "/builds/ostree/prod-aos-h3ulcb"

  2. The board U-Boot environment is configured according to (u-boot-env.txt)[doc/u-boot-env.txt] "Load uEnv.txt from eMMC" section

    This is required to perform Dom0 update. Dom0 update uses dual partition update approach. Selection active partition is done by U-Boot based on environment variables stored in the special file on the dedicated partition.

  3. The image for specific machine is successfully build according to instructions described in (INSTALL.md)[install.md]

  4. The appropriate board configuration file deployed to the target: boardconfig.json

Generating update bundle

After successful image build, the update bundle which contains update images for the configured system components can be generated by the following command:

python ./build_prod.py --build-type dailybuild --machine MACHINE_NAME --product aos \
--with-local-conf --config xt-prod-aos.cfg --generate-update

This command should generate the update bundle located at ${BUNDLE_DIR} and commit DomD, DomF rootfs in ostree repo in BUNDLE_OSTREE_REPO folder:

${workspace_base}/build/deploy/
   └── update
       └── xt-update-h3ulcb_1.0.0.tar

This bundle can be deployed to the target supported OTA update.

Generating updates flow

This update bundle version is 1.0.0. It has following component vendor versions:

  • Dom0 - 1.0.0;
  • DomD - 1.0.0;
  • DomF - 1.0.0.

This update can't be deployed to the board using OTA because currently installed software doesn't support or not compatible with the update bundle. This particular image should be flashed to SD card using mk_sdcard_image.sh script.

It is very important to have BUNDLE_OSTREE_REPO configured outside workspace_base_dir for generating further incremental update. The BUNDLE_OSTREE_REPO folder should remain persistent between new image generations.

Further updates can be delivered to the target using OTA update mechanism and has the following flow:

  • build the new image according to INSTALL.md

    It will remove workspace_base_dir and build new image version (1.0.1 for example).

  • generate the new update bundle version 1.0.1 see

    This step should be performed any case, even if currently there is no devices on which this update should be delivered. It is required to commit current DomD, DomF rootfs's in order to be able to generate further incremental updates. Except committing DomD, DomF rootfs to ostree repo, it will generate the new update bundle version 1.0.1.

  • deliver the update bundle version 1.0.1 to the target OTA.

Test OTA updates

This sections describe how to play with OTA updates if there is no new updates available. This is not normal update flow, that's why this functionality is not included into the build scripts and required to input set of bitbake commands directly to the console.

At this example we will add nano editor to the Dom0, DomD and DomF rootfs's.

  1. Once the image with OTA update is successfully built, it should be flashed to the device by mk_sdcard_image.sh. After that, the device should be provisioned and connected to the cloud.

  2. Generate the current update bundle version 1.0.0 if it is not yet generated.

  3. Add the following update configuration variables to the end of the upper yocto local config ${workspace_base_dir}/build/conf/local.conf:

    # Update bundle

BUNDLE_IMAGE_VERSION = "1.0.1"

BUNDLE_DOM0_TYPE = "full"
DOM0_IMAGE_VERSION = "1.0.1"

BUNDLE_DOMD_TYPE = "incremental"
DOMD_IMAGE_VERSION = "1.0.1"
DOMD_REF_VERSION = "1.0.0"

BUNDLE_DOMF_TYPE = "incremental"
DOMF_IMAGE_VERSION = "1.0.1"
DOMF_REF_VERSION = "1.0.0"

    These variables override current bundle build configuration and set bundle verstion to 1.0.1, Dom0, DomD, DomF vendor versions to 1.0.1 accordingly, and set update incremental update type for DomD and DomF. Incremental update wll be generated based on vendor versions 1.0.0.

  4. Add nano editor to the image for Dom0, DomD, DomF:

    • for Dom0: append ${workspace_base_dir}/meta-xt-prod-aos/recipes-dom0/dom0-image-thin-initramfs/files/meta-xt-prod-extra/recipes-core/images/core-image-thin-initramfs.bbappend file by following variable:
    IMAGE_INSTALL_append = " \
    nano \
"
    • for DomD: append ${workspace_base_dir}/meta-xt-prod-aos/recipes-domd/domd-image-minimal/files/meta-xt-prod-extra/recipes-core/images/core-image-minimal.bbappend file by following variable:
    IMAGE_INSTALL_append = " \
    nano \
"
    • for DomF: append ${workspace_base_dir}/meta-xt-prod-aos/recipes-domu/domu-image-fusion/files/meta-xt-prod-extra/recipes-core/images/core-image-minimal.bbappend file by following variable:
    IMAGE_INSTALL_append = " \
    nano \
"

  5. Build the new image manually:

    Go to ${workspace_base_dir} folder:

    cd ${workspace_base_dir}

    and perform following commands:

    source xt-distro/oe-init-build-env

  6. Generate the new update bundle manually:

    bitbake xt-update -c clean
bitbake xt-update

  7. Deploy the new update bundle 1.0.1 to the cloud OTA