Bootstrap & OTA

Bootstrap

To enroll your device in EdgeScale, the bootstrap image needs to be programmed first and then reboot the board. After the device is authenticated, the OTA process will start to install corresponding solution image associated with the device model.

This guide will introduce you how to build and flash the bootstrap image for the device to finish the enrollment in EdgeScale.

The current OTA uses single boot source. Only booting from QSPI/NOR/Flexspi-NOR flash is supported for LayerScape platforms.

For OTA support, SD card is needed. OTA control logic is in the BL2 stage of the boot process. Specifically it is in the bl2_<boot_mode>.pbl and programmed on the first 1MB area of QSPI/NOR/Flexspi-NOR flash. Bootstrap images except bl2_<boot_mode>.pbl are installed on SD card. Solution firmware image is installed on QSPI/NOR/Flexspi-NOR flash and OS images are installed on SD card partitions.

For recovery, watchdog timer is enabled in BL2 stage, and monitors the system until Linux kernel watchdog timer takes over with new configuration. During the period, it will automatically reboot hanged systems. Then the bootstrap image will start and roll back to previous working solution image.

Boot mode on each platforms

PLATFORM QSPI NOR Flexspi-NOR
ls1012ardb yes    
ls1012afrwy yes    
ls1028ardb     yes
ls1043ardb   yes  
ls1046ardb yes    
ls1046afrwy yes    
ls1088ardb yes    
ls2088ardb   yes  
lx2160ardb     yes

For ls1021atwr, single boot source OTA is not available and dual boot source OTA is still used.

For i.MX platforms, single boot source is also used for OTA. Booting from SD or Flexspi-NOR flash is supported. OTA control logic is in the SPL stage of the boot process. Secure Boot is not supported yet.

Build the bootstrap image

Below is an example for how to build bootstrap image from source. Currently the bootstrap image is built with yocto environment.

  • Supported boards

ls1012ardb ls1012afrwy ls1028ardb ls1043ardb ls1046ardb ls1046afrwy ls1088ardb-pb ls2088ardb lx2160ardb ls1021atwr

  • Setup the Yocto project

Follow below guide to get your build host ready:yocto

  • Install the repo utility
# mkdir ~/bin
# curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
# chmod a+x ~/bin/repo
  • Download the metadata
#export PATH=${PATH}:~/bin
#mkdir yocto-sdk
#cd yocto-sdk
#repo init -u https://source.codeaurora.org/external/qoriq/qoriq-components/yocto-sdk -b refs/tags/yocto_2.6_es_1909
#repo sync --no-clone-bundle
  • Build the image

Take ls1012ardb as an example:

1.Setup build environment

#. ./setup-env -m ls1012ardb

Note

To build single bootstrap images need to add following line to build_ls1012ardb/conf/local.conf

DISTRO_FEATURES_append = " single-boot"

2.Build EdgeScale bootstrap image

#bitbake single-source-bootstrap

Note

EdgeScale bootstrap images will be found under tmp/deploy/images/ls1012ardb/single-source-bootstrap/. To build images with optee, need to add following line to build_ls1012ardb/conf/local.conf

DISTRO_FEATURES_append = " optee"

Note

To enable the ima_evm feature, need to add following line to build_ls1012ardb/conf/local.conf

DISTRO_FEATURES_append = " ima-evm"

Note

To enable the Manufacture, need to add following line to build_ls1012ardb/conf/local.conf

DISTRO_FEATURES_append = " mft"

Note

To enable the secure model, need to add following line to build_ls1012ardb/conf/local.conf

DISTRO_FEATURES_append = " secure"
ROOTFS_IMAGE = "fsl-image-edgescale"
KERNEL_ITS = "kernel-all.its"

Note

Key pairs and files required for the EdgeScale secure bootstrap images will be found under tmp/deploy/images/ls1012ardb/.

Without setting the specified key path, the generated key is random

To use the specified key pair,need to modify following lines to ../sources/meta-qoriq-demos/recipes-devtools/cst/cst_git.bbappend

#SECURE_PRI_KEY = "/path/srk.pri"
#SECURE_PUB_KEY = "/path/srk.pub"

Note

ls1021atwr bootstrap image doesn’t support single bootstrap,It can only be compiled with “bitbake edgescale-bootstrap” to build images . you need to add following line to build_ls1021atwr/conf/local.conf

DISTRO_FEATURES_append = " ota"

Build the bootstrap with docker

EdgeScale bootstrap images can be built using the docker which includes all the yocto build environment in the container.

Run the following command to build the cross-build yocto environment:

$ docker build \
  --build-arg http_proxy=$http_proxy \
  --build-arg https_proxy=$https_proxy \
  --build-arg host_uid=$(id -u) \
  --build-arg host_gid=$(id -g) \
  --no-cache \
  -t edgescale-bootstrap:v1 .

Note

If the proxy is required, please set the proxy using the following commands:

$ export http_proxy=”xxxxxxxxx”

$ export https_proxy=”xxxxxxxxx”

Once the building container is ready, we can start it to build the target image. Take ls1046ardb as an example:

$ mkdir -p yocto/build_ls1046ardb yocto/downloads yocto/sstate-cache
$ docker run -it  --name edgescale-bootstrap-ls1046ardb \
  -v $PWD/yocto/build_ls1046ardb:/home/edgescale/yocto-sdk/build_ls1046ardb \
  -v $PWD/yocto/downloads:/home/edgescale/yocto-sdk/downloads \
  -v $PWD/yocto/sstate-cache:/home/edgescale/yocto-sdk/sstate-cache edgescale-bootstrap:v1

Note

you can get the bootstrap images from the following two locations:

inside docker container:
/home/edgescale/yocto-sdk/build_ls1046ardb/tmp/deploy/images/ls1046ardb/single-bootstrap/
outside docker container(local host):
$PWD/yocto/build_ls1046ardb/tmp/deploy/images/ls1046ardb/single-bootstrap/

Image Download

Download the pre-built bootstrap images according to the following table. Only work with LSDK1909 solution image. Images for previous LSDK release versions are not available.

Bootstrap Image

Version Platform Images
v1909 LS1012ARDB ls1012ardb-qspi.img
v1909 LS1012ARDB bl2_qspi_ls1012ardb.pbl
v1909 LS1012AFRWY ls1012afrwy-qspi.img
v1909 LS1012AFRWY bl2_qspi_ls1012afrwy.pbl
v1909 LS1043ARDB ls1043ardb-nor.img
v1909 LS1043ARDB bl2_nor_ls1043ardb.pbl
v1909 LS1046ARDB ls1046ardb-qspi.img
v1909 LS1046ARDB bl2_qspi_ls1046ardb.pbl
v1909 LS1046AFRAWY ls1046afrwy-qspi.img
v1909 LS1046AFRAWY bl2_qspi_ls1046afrwy.pbl
v1909 LS1088ARDB_PB ls1088ardb-pb-qspi.img
v1909 LS1088ARDB_PB bl2_qspi_ls1088ardb-pb.pbl
v1909 LS2088ARDB ls2088ardb-nor.img
v1909 LS2088ARDB bl2_nor_ls2088ardb.pbl
v1909 LS1021ATWR ls1021atwr-nor.img
v1909 LS1028ARDB lS1028ardb-xspi.img
v1909 LS1028ARDB bl2_xspi_ls1028ardb.pbl
v1909 LX2160ARDB lx2160ardb-xspi.img
v1909 LX2160ARDB bl2_xspi_lx2160ardb.pbl
v1909 IM6 imx6qsabresd-sdboot.img
v1909 IMX8MQ imx8mqevk-sdboot.img
v1909 IMX8MM-SD imx8mmevk-sdboot.img
v1909 IMX8MM-NOR imx8mmevk-norboot.img

Bootstrap Image with mft-agent

Version Platform Images
v1909 LS1012ARDB mft_ls1012ardb-qspi.img
v1909 LS1012ARDB bl2_qspi_ls1012ardb.pbl
v1909 LS1012ARDB kernel-fsl-ls1012a-rdb.itb
v1909 LS1012AFRWY mft_ls1012afrwy-qspi.img
v1909 LS1012AFRWY bl2_qspi_ls1012afrwy.pbl
v1909 LS1012AFRWY kernel-fsl-ls1012a-frwy.itb
v1909 LS1043ARDB mft_ls1043ardb-nor.img
v1909 LS1043ARDB bl2_nor_ls1043ardb.pbl
v1909 LS1043ARDB kernel-fsl-ls1043a-rdb.itb
v1909 LS1046ARDB mft_ls1046ardb-qspi.img
v1909 LS1046ARDB bl2_qspi_ls1046ardb.pbl
v1909 LS1046ARDB kernel-fsl-ls1046a-rdb.itb
v1909 LS1046AFRAWY mft_ls1046afrwy-qspi.img
v1909 LS1046AFRAWY bl2_qspi_ls1046afrwy.pbl
v1909 LS1046AFRAWY kernel-fsl-ls1046a-frwy.itb
v1909 LS1088ARDB_PB mft_ls1088ardb-pb-qspi.img
v1909 LS1088ARDB_PB bl2_qspi_ls1088ardb-pb.pbl
v1909 LS1088ARDB_PB kernel-fsl-ls1088a-rdb.itb
v1909 LS2088ARDB mft_ls2088ardb-nor.img
v1909 LS2088ARDB bl2_nor_ls2088ardb.pbl
v1909 LS2088ARDB kernel-fsl-ls2088a-rdb.itb
v1909 LS1028ARDB mft_lS1028ardb-xspi.img
v1909 LS1028ARDB bl2_xspi_ls1028ardb.pbl
v1909 LS1028ARDB kernel-fsl-ls1028a-rdb.itb
v1909 LX2160ARDB mft_lx2160ardb-xspi.img
v1909 LX2160ARDB bl2_xspi_lx2160ardb.pbl
v1909 LX2160ARDB kernel-fsl-lx2160a-rdb.itb

Flash bootstrap image

Precondition

  • Setup the tftp server.
  • Copy the bootstrap image to tftp server.
  • Configure network for the board to ensure it can connect to the tftp server.

LS1012ARDB/LS1012AFRWY/LS1028ARDB/LS1046ARDB/ls1046AFRWY

LS1088ARDB/LX2160ARDB

  • Create device in EdgeScale dashboard and download the identification image.
  • Program the identification image to SD on a Linux PC:
$ sudo fdisk -l         # find the /dev/sdx for the SD card e.g. /dev/sdb
$ sudo umount /dev/<sdx>
$ sudo ./bootstrap-enroll-<deviceID>.sh /dev/<sdx>
  • Boot up the board with a working boot-loader, then run the following commands in u-boot prompt to flash the bootstrap BL2 image:
=> tftp 0xa0000000 /tftpboot/bl2_qspi_<ls1012ardb/ls1012afrwy/ls1046ardb/ls1046afrwy/ls1088ardb-pb>.pbl/bl2_xspi_<ls1028ardb/lx2160ardb>.pbl
=> sf probe 0:0
=> sf erase 0 0x3e00000        # for ls1012afrwy, sf erase 0 0x100000
=> sf write 0xa0000000 0 0x100000
  • Program the bootstrap Firmware image to SD on a Linux PC or in u-boot prompt:
$ dd if=firmware_<ls1012ardb/ls1012afrwy/ls1046ardb/ls1046afrwy/ls1088ardb-pb>_uboot_qspiboot.img/firmware_<ls1028ardb/lx2160ardb>_uboot_xspiboot.img of=/dev/<sdx> bs=1k seek=0

or

=> tftp 0xa0000000 /tftpboot/firmware_<ls1012ardb/ls1012afrwy/ls1046ardb/ls1046afrwy/ls1088ardb-pb>_uboot_qspiboot.img/firmware_<ls1028ardb/lx2160ardb>_uboot_xspiboot.img
=> mmc write 0xa0000000 0 $cnt
  • Make sure SD card is inserted and the board is switched to boot from QSPI/FlexSPI-NOR flash, then run the following command in u-boot prompt to start the OTA process:
=> reset

LS1043ARDB

  • Create device in the EdgeScale dashboard and download the identification image.
  • Program the identification image to SD on a Linux PC:
$ sudo fdisk -l         # find the /dev/sdx for the SD card e.g. /dev/sdb
$ sudo umount /dev/<sdx>
$ sudo ./bootstrap-enroll-<deviceID>.sh /dev/<sdx>
  • Boot up the board with a working boot-loader, then run the following commands in u-boot prompt to flash the bootstrap BL2 image:
=> tftp 0xa0000000 /tftpboot/bl2_nor_ls1043ardb.pbl
=> protect off all
=> erase 0x60000000 +0x3e00000
=> cp.b 0xa0000000 0x60000000 0x100000
  • Program the bootstrap Firmware image to SD on a Linux PC or in u-boot prompt:
$ dd if=firmware_ls1043ardb_uboot_norboot.img of=/dev/<sdx> bs=1k seek=0

or

=> tftp 0xa0000000 /tftpboot/firmware_ls1043ardb_uboot_norboot.img
=> mmc write 0xa0000000 0 $cnt
  • Make sure SD card is inserted and the board is switched to boot from NOR flash, then run the following command in u-boot prompt to start the OTA process:
=> reset

LS2088ARDB

  • Create device in EdgeScale dashboard and download the identification image.
  • Program the identification image to SD on a Linux PC:
$ sudo fdisk -l         # find the /dev/sdx for the SD card e.g. /dev/sdb
$ sudo umount /dev/<sdx>
$ sudo ./bootstrap-enroll-<deviceID>.sh /dev/<sdx>
  • Boot up the board with a working boot-loader, then run the following commands in u-boot prompt to flash the bootstrap BL2 image:
=> tftp 0xa0000000 /tftpboot/bl2_nor_ls2088ardb.pbl
=> protect off all
=> erase 0x580000000 +0x3e00000
=> cp.b 0xa0000000 0x580000000 0x100000
  • Program the bootstrap Firmware image to SD on a Linux PC or in u-boot prompt:
$ dd if=firmware_ls2088ardb_uboot_norboot.img of=/dev/<sdx> bs=1k seek=0

or

=> tftp 0xa0000000 /tftpboot/firmware_ls2088ardb_uboot_norboot.img
=> mmc write 0xa0000000 0 $cnt
  • Make sure SD card is inserted and the board is switched to boot from NOR flash, then run the following command in u-boot prompt to start the OTA process:
=> reset

LS1021ATWR

  • Create device in the EdgeScale dashboard and download the identification image.
  • Program the identification image to SD on a Linux PC:
$ sudo fdisk -l         # find the /dev/sdx for the SD card e.g. /dev/sdb
$ sudo umount /dev/<sdx>
$ sudo ./bootstrap-enroll-<deviceID>.sh /dev/<sdx>
  • Insert the SD card to the board, then boot the board to enter u-boot prompt.
  • Run the following commands to flash the bootstrap image:
=> tftp 0xa0000000 /tftpboot/ls1021atwr-nor.img
=> pro off all
=> erase 0x64000000 +$filesize
=> cp.b 0xa0000000 0x64000000 $filesize
  • Run the following command in u-boot environment to start the OTA process:
=> reset

OTA Update Procedure

Precondition

The SD storage range of 63M~64M is reserved to store OTA status information. This area is accessible for both the bootstrap image and the new SD image.

OTA Layout

_images/sd-default-layout.png

Unified 64MiB memory layout of SD media on all Layerscape platforms

_images/sd-64M-memory-layout.png

Unified 64MiB memory layout of NOR/QSPI/Flexspi-NOR media on all Layerscape platforms

_images/flash-64M-memory-layout.png

Unified 2MB memory layout of SD media on Layerscape platforms

_images/sd-2M-memory-layout.png

Unified 2MB memory layout of QSPI media on Layerscape platforms

_images/flash-2M-memory-layout.png

OTA Process

_images/ota-process.png
  • OTA_STATUS_INIT(OTAstatus=NULL): When the board boots up for the first time, the bootstrap image will start. It will get the latest image from the cloud and install the firmware image on flash and the OS image on SD card.
  • OTA_STATUS_INSTALLED(OTAstatus=1): The installed solution image will boot up.
  • OTA_STATUS_ONLINE(OTAstatus=0): The installed solution image boots up successfully. EdgeScale service starts and the device is online.
  • OTA_STATUS_FAILED(OTAstatus=2): The installed solution image fails to boot up.
  • OTA_STATUS_DEPLOY(OTAstatus=8): Deploy a new solution image to the device.
  • OTA_STATUS_INSTALL(OTAstatus=4): The deployed solution image is downloaded and will be installed.
  • OTA_STATUS_IDLE(OTAstatus=3): OTA script will check if there is a new version of the image for the device periodically.

Warning

OTA is a totally automatic process monitored by watchdog timer to avoid the forever hang.

The watchdog is configured in BL2 to monitor the firmware loadinging and running. It expects the Linux kernel to reconfigure and take over in 2~3 minutes.

If you interrupt the auto reboot process by manual operation at U-Boot prompt, please disable the watchdog first. Otherwise, the board will be reset by the BL2 watchdog timer setting.

Run following commands manually in U-Boot prompt to prevent the watchdog reset.

LS1046ARDB/LS1046AFRWY/LS1012ARDB/LS1012AFRWY:
=> mw 0x1ee00c0 0x00420000
LS1043ARDB:
=> mw 0x1ee00c0 0x00460000
LS1028ARDB/LS1088ARDB/LS2088ARDB/LX2160ARDB:

=> mw 0xc000c00 0x1acce551

=> mw 0xc000008 0x0

Procedure

To automatically deploy the solution image to the device, please refer to the work flow below:

_images/user-workflow.png
  • Create device, bind model and build the solution image with EdgeScale agents.

    Please refer to Quick Start Guide.

  • Compress all the software images as a tgz file.

tar czvf edgescale_lsdk1909-ls1046_image_qspiboot.tgz \
    bootpartition_LS_arm64_edgescale_lts_4.14.tgz \
    firmware_ls1046ardb_uboot_qspiboot.img \
    rootfs_ubuntu_bionic_LS_arm64_edgescale.tgz
  • Upload the compressed solution image to a storage server and get the download URL link.

    Currently, EdgeScale will NOT host user’s binary images with the assumption that users have their own public storage.

  • Create the solution image via EdgeScale dashboard:

    Click Create button and go to the solution creating page.

    Model name, solution name and version are required.

    • Model Name: Choose a model for solution
    • Solution Name: The name for solution
    • Version: The version for solution
_images/solution-upload-step1.png
  • Specify solution permission and tag.
    • Private: Can’t be seen by others
    • Public: Can be seen by others
    • Tags: Add tags to the solution
_images/solution-upload-step2.png
  • Specify solution image location (URL link).

    Specify Firmware Location

    A specific firmware address (Image URL).

    Upload Firmware Image

    User can upload a local firmware image.

_images/solution-upload-step3.png
  • Click submit button and finish creating the solution.
  • Download and flash the bootstrap image to the device as introduced in previous “Bootstrap” section.