swupdate

meta-swupdate-kch

Our Yocto layer meta-swupdate-kch allows the easy integration of the SWUpdate project on our boards. The layer is an extension to the existing Yocto layer meta-swupdate. Below is a short description of the extensions.

swu-image.bbclass

The class helps to generate a SWU file. The class supports the following images/artifacts:

Name	Beschreibung
rootfs	Creates the rootfs in the block device /dev/mmcblk0p2. First an ext4 filesystem is created with the label 'rootfs', then tar.gz file is unpacked into the newly created filesystem.
rescue	Creates the rescue system in the block device /dev/mmcblk0p1. First an ext4 filesystem is created with the label 'rescue', then tar.gz file is unpacked into the newly created filesystem. The image is only installed if the version of the image to be installed is more recent than the version already installed.
bootloader	Updates the boot loader in the mtd partition 'u-boot'. The image is only installed if the version of the image to be installed is more recent than the version already installed.
bootenv	Overwrites the boot variables with the added script file. The fw_setenv tool is used for the initialization. The image is only installed if the version of the image to be installed is more recent than the version already installed.
extra	The tar.gz file is extracted during the update process into the root directory of the filesystem of the partition defined with the variable SWUPDATE_IMAGES_SPEC[extra].

The image will be added to the SWU file only if the corresponding variable SWUPDATE_IMAGES_FILENAME[<name>] is defined.

The template for a recipe to create a SWU file using the class:

DESCRIPTION = "Example recipe generating SWU file"

inherit swu-image

# images to build before building swupdate image
IMAGE_DEPENDS = "image-kontron-base image-rescue-gui virtual/bootloader"

# add rootfs artifact to swu file
SWUPDATE_IMAGES_FILENAME[rootfs] = "image-kontron-base-${MACHINE}.tar.gz"
SWUPDATE_IMAGES_VERSION[rootfs] = "1.0.0"

# add rescue artifact to swu file
SWUPDATE_IMAGES_FILENAME[rescue] = "image-rescue-gui-boot-${MACHINE}.tar.gz"
SWUPDATE_IMAGES_VERSION[rescue] = "1.0.0"

# add bootloader artifact to swu file
# use string with only whitespaces to create the image automatically.
SWUPDATE_IMAGES_FILENAME[bootloader] = " "
SWUPDATE_IMAGES_VERSION[bootloader] = "1.0.0"

# add bootenv artifact to swu file
SWUPDATE_IMAGES_FILENAME[bootenv] = "u-boot-initial-env-${MACHINE}"
SWUPDATE_IMAGES_VERSION[bootenv] = "1.0.0"

# add extra artifact to swu file
SWUPDATE_IMAGES_FILENAME[extra] = "/path/to/custom.tar.gz"
# extract extra archive in the data partition
SWUPDATE_IMAGES_SPEC[extra] = "LABEL=data"
SWUPDATE_IMAGES_VERSION[extra] = "1.0.0"

Procedure Update process of SWUpdate

The SWUpdate update process for a SWU file created with the swu-image class:

sw-description unpack and, if signing is enabled, verify it
Check hardware and software compatibility.
Parse sw-description to determine which SW artifacts are needed.
Run Embedded Script. In our case, the script performs the following tasks:
1. The bash script preinit.sh embedded in the embedded script copy to RAM
2. run preinit.sh with parameter 'init:
  1. Run all custom pre-install apps/scripts in /run/media/data/swu/install.d directory with 'preinst' parameter
  2. TODO: Create partitions if not already available
3. For all SW artifacts with a defined hook function, this function is executed, even if the artifact is not installed afterwards because of the SW version check.
  In our case the hook function preinst.sh is executed, but only if the corresponding artifact is installed. The passed parameters depend on the hook function.
  If preinit.sh could be executed without errors, the temporary file sw-versions.new is extended accordingly.
Execute pre update command (swupdate option -P). Not used by us.
If defined, the partition handler is executed, Not used by us.
Execute all handlers for all artifacts marked 'installed-directly', artifacts without this mark will be copied to a temporary location.
Run all pre-install scripts. Not used by us.
Run all image handlers. Not used by us.
Execute all file handler.
Run all post-install scripts. In our case the postinstall.sh script is executed with the following tasks:
1. If bootenv artifact exists, update boot environment accordingly.
2. Update sw-versions in the swu partition. Thereby the installed SW versions are taken over from the file sw-versions.new into the file sw-versions.
3. Run all custom post-install apps/scripts in /run/media/data/swu/install.d directory with 'postinst' parameter.
Execute all bootenv handler.
Execute post update command (swupdate option -p). Not used by us.

Variables of the class swu-image

SWUPDATE_BORDNAME

Defines the name of the board. The name is stored in the /etc/hwrevision and sw-description files. SWUpdate uses the values for the compatibility check of the SWU file.

SWUPDATE_BORDREV

Definiert der Revision vom Board. Die Revision wird in den Dateien /etc/hwrevision und sw-description gespeichert. SWUpdate verwendet die Werte für den Kompatibilitätscheck der SWU Datei.

SWUPDATE_HWCOMPATIBILITY

Defines the revision of the board. The revision is stored in the /etc/hwrevision and sw-description files. SWUpdate uses the values for the compatibility check of the SWU file.

SWUPDATE_IMAGES_FILENAME[{extra|rootfs|rescue|bootloader|bootenv}]

Defines the filename to be used for the corresponding artifact. The filename can be an absolute path or a relative path related to the deploy directory.
Additional function has the variable SWUPDATE_IMAGES_FILENAME[bootloader], if the value is equal to a string only with spaces (e.g. " ", not an empty string), then the bootloader image will be created automatically by the class from the u-boot and spl image.

SWUPDATE_IMAGES_VERSION[{extra|rootfs|rescue|bootloader|bootenv}]

Defines the semantic version of the corresponding artifact.

SWUPDATE_IMAGES_SPEC[extra]

This variable defines into which partition the extra archive should be unpacked. The value of the variable corresponds to the token of the -t option of the blkid command.

Variables of the class swupdate (Layer meta-swupdate)

SWUPDATE_PRIVATE_KEY

This variable defines the pathname of the file with the private key. The key is needed when creating the signed .swu files. The following command generates the file priv.pem, the passphrase is read from the file passphrase.txt:

openssl genrsa -aes256 -passout file:passphrase.txt -out priv.pem

If this variable is not defined, the .swu files are not signed and the SWU files are not checked during SWUpdate. For security reasons, it is not possible to disable or enable the check at runtime.

SWUPDATE_PUBLIC_KEY

This variable defines the pathname of the public key file. The public key is used before installing swupdate to verify the .swu file.

The following command generates the file public.pem with the public key from the private key from priv.pem, the passphrase is read from the file passphrase.txt:

openssl rsa -in priv.pem -passin file:passphrase.txt -out public.pem -outform PEM -pubout

SWUPDATE_PASSWORD_FILE

This variable defines the pathname of the file with the passphrase.

Recipes

u-boot-bootscripts.bb

Extends the standard images (image-kontron-base, ...) with the submarine startup scripts needed for the SWU system.

libubootenv_%.append

Libubootenv is used by the swupdate tool instead of u-boot-fw-utils. Extends the recipe with the fw_config service.

rescue-core.bb

Contains various extensions for the Rescue System:

U-Boot Startup Skript vom Rescue System
Rescue Konfiguration Service
Der Service mountet die data Partition unter /run/media/data und führt alle ausführbaren Dateien im Verzeichnis /run/media/data/rescue/config.d/ in alphabetisch Reihenfolge aus. Dies ermöglicht die Konfiguration von z.B. der Netzwerkparameter.
Autostart Service
Der Service wird nach den Recue Konfiguration Service ausfgeführt und startet alle ausführbaren Dateien im Verzeichnis /run/media/rescue/autostart.d und /etc/autostart.d in alphabetisch Reihenfolge aus. Existiert ein Dateiname in beiden Verzeichnissen, wird nur due Datei im Verzeichnis /run/media/rescue/autostart.d ausgeführt.

rescuegui_%.bbappend

siehe SWUpdate RescueGUI

swupdate_%.bbappend

Erweiterung vom swupdate Paket:

Build configuration customized for with/without signing
Web server appearance customized
Create /etc/hwrevision using the SWUPDATE_BORDNAME and SWUPDATE_BORDREV variables.
SWUpdate service configuration for Rescue System adapted
Port from web server configurable with variable SWUPDATE_WEBSERVER_PORT, default is 8081

image-rescue-*.bb

Creates the image files for Rescue System.

Rezept	Beschreibung
image-rescue-base	minimal rescue system
image-rescue-dev	Rescue system with helpful tools for development
image-rescue-gui	minimal rescue system with GUI
image-rescue-gui-dev	Rescue system with helpful tools for development with GUI

The recipes image-rescue-*.bb create the following image files:

image-rescue-*-<MACHINE>-<DISTRO_CODENAME>-v<DISTRO_VERSION>-<YYYYMMDD>.rootfs.wic.gz
The image contains the u-boot, boot partition with the boot files (contents of image-rescue-*.boot.tar.gz) from the Rescue OS. The image can be used to create a bootable SD card.
image-rescue-*-<MACHINE>-v<DISTRO_VERSION>-<YYYYMMDD>.boot.tar.gz
Archive with the boot files. Contents can be extracted to the Rescue partition. The image is included in the SWU file.

swu-tools.bb

swu-start

With swu-start an update process is started. The tool performs the following steps:

Configure Rescue System (Network, SWUpdate Public Key)
Define Autostart of Rescue System (start SWUpdate via Autostart)
Rescue System starten (bootentry = rescue, reboot)

update-rescue-config

Tool to configure the rescue system via data partition. The tool performs the following steps:

Network configuration
Provide public key for SWUpdate

Further adjustments for a SWU system

The following describes the additional customizations required for a SWU system outside of the meta-swupdate-kch layer.

Variable CONFIG_SWU_SYSTEM

This variable defines the used SWU strategy:

"0" or not defined
System without SWU strategy, i.e. no SWU system/layout
"1"
Single copy strategy, i.e. system with resuce system in partition 1 and RootFS from main system in partition 2. The following changes compared to "0":
- packages u-boot-bootscripts and swu-tools are included
- ptool: flash_emmc creates the partitions and flashes the rescue and rootfs partition
- u-boot Environment extended for SWU

If in local.conf the variable CONFIG_SWU_SYSTEM = "1", the recipes image-kontron-x.bb (x stands for the image type: base, codesys, ...) creates the files for the rootfs of the SWU system:

image-kontron-base-<MACHINE>-<DISTRO_CODENAME>-v<DISTRO_VERSION>-<YYYYMMDD>.rootfs.wic.gz
The image contains the U-Boot, boot partition and rootfs partition. The image can be used to create a bootable SD card.
image-kontron-base-<MACHINE>-<DISTRO_CODENAME>-v<DISTRO_VERSION>-<YYYYMMDD>.rootfs.tar.gz
The archive contains the rootFS of the main OS, the files can be unpacked in the rootfs partition.

ptool

The ptool can be used to initialize the eMMC. Running 'ptool emmc_flash' performs the following steps:

Partitioning of the eMMC according to the configuration in /usr/share/production/swu-env.sh
Unpack the archive image-rescue.boot.tar.gz into the rescue partition of the eMMC (partition with FS label rescue, usually partition 1)
Unpack the archive rootfs.tar.gz into the rootfs partition of the eMMC (partition with FS label rootfs, usually partition 2)

Default eMMC Partition scheme

Single Copy

U-Boot

Bootscript

U-boot tries to boot from the list of devices defined in the boot_targets variable. U-boot starts from the first device in the list. If the device is not present, the device does not have a startup.sh boot script, or the boot script exits, U-boot attempts to boot from the next device in the list.

Variablen

Name

Default

Beschreibung

bootentry_next Normally set by the OS. The variable defines the system to boot at the next boot. When U-Boot boots, this variable is used to set the bootentry variable that the boot scripts use to perform the correct function.

recovery_status

SWUpdate sets this variable to 'in_progress' before the update, and clears it again after a successful update or sets it to 'failed' if an error was detected during the update.

ustate

ustate is set to 1 (INSTALLED) by SWUpdate after a successful update. This indicates to the bootloader that the new SW is now tested and the FALLBACK is to be set up (start watchdog). If the new SW does not run correctly (detected with bootcount), the bootloader sets ustate to 3 (FAILED).
If the new installed SW starts, the app (or init script of SWUpdate) must check the new installation and after successful check ustate must be changed from 1 to 0.

altbootcmd

U-Boot executes the contents of altbootcmd if bootcount > bootlimit. By default, the following script is executed

setenv bootentry "${altbootentry_next}"
for target in ${altboot_targets}
do
run bootcmd_${target}
done

bootcount

This variable is automatically created by U-Boot and incremented by one after each reboot.
Because bootcount is stored as an environment variable, bootcount is incremented only when upgrade_available=1.

It is the responsibility of an application code (usually a Linux application) to reset the bootcount variable, allowing more boot cycles.

bootlimit 3 If this variable exists, its contents are taken as the maximum number of reboot cycles allowed. Normally, U-Boot executes the stored commands in the bootcmd variable at each boot, but if the maximum number of reboot cycles allowed is exceeded, U-Boot executes the stored commands in the altbootcmd variable.

upgrade_available

0

"bootcount" wird in der Umgebung gespeichert. Um ein saveenv bei allen Neustarts zu verhindern, wird die Umgebungsvariable "upgrade_available" verwendet. Wenn "upgrade_available" 0 ist, ist "bootcount" immer 0, wenn "upgrade_available" 1 ist, wird "bootcount" in der Umgebung erhöht. Die Userspace-Anwendung muss also die Variablen "upgrade_available" und "bootcount" auf 0 setzen, wenn ein Bootvorgang erfolgreich war.

Bootprocess