Introduction

Over-the-air (OTA) programming provides a methodology of updating device firmware remotely via TCP/IP network. For OTA via TCP/IP network, the RTL8721Dx provides solutions to implement OTA firmware upgrade from local server or cloud.

Image Slot

There are two slots for all the images in the Flash layout as shown in below, which named OTA1 and OTA2 respectively. Each image can be chosen to boot from OTA1 or OTA2.

OTA1 and OTA2 position

Version Number

The device boot from OTA1 or OTA2 mainly depends on the version number in certificate and manifest. As shown in the figure below, there is a 2-byte major version and 2-byte minor version in manifest and certificate.

Major and minor version

The combination of major version and minor version is the 4-byte version number. OTA select flow checks the whole version number.

Version number = (Major version << 16) | Minor version

Note

• For bootloader, version number can be 0 to 32767; for application, version number can be 0 to 65535.

As described in Image Slot, there are two slots (OTA1 and OTA2) for all the images in the Flash layout. When reboot after OTA upgrade finished, the device would check the image to determine to boot from OTA1 or OTA2.

The general principle of the OTA scheme is checking the image pattern first and then comparing the version number of OTA1 and OTA2.

The following items must be checked for each image:

1. Check the image pattern for both OTA1 and OTA2.

   • If only one image pattern is valid, boot from the valid image.

   • If both the image pattern are invalid, boot fail.

2. Compare the version number of OTA1 and OTA2.

   • If both OTA1 and OTA2 are valid and with different version numbers, the device will boot from the image with a bigger version.

   • If both OTA1 and OTA2 are valid but with the same version number, the device will boot from OTA1.

   

   OTA selection diagram

Anti-rollback

Anti-rollback is the function to prevent version rollback attack. When the anti-rollback is enabled, the version number in certificate or manifest must not be smaller than the anti-rollback version stored in OTP. Otherwise, this image will be regarded as invalid and the chip will not boot from invalid image. Normally, if OTA update is security-related, user can program a bigger anti-rollback version number in OTP and update image with a bigger major version at the same time to prevent rollback attack.

The anti-rollback flow is shown below. Once the anti-rollback is enabled, the device will compare the major version numbers got from OTA1 and OTA2 images respectively with the anti-rollback version number in OTP. If the major version number in the image is smaller than the anti-rollback version number, this image will be regarded as invalid.

Anti-rollback flow

Bootloader

OTA Image

The KM4 bootloader image named km4_boot_all.bin can be updated through OTA, which can be chosen to boot from OTA1 or OTA2. The layout of KM4 bootloader image is illustrated below.

Layout of KM4 bootloader image

OTA Selection Flow

The KM4 ROM will select OTA image according to the image version number in bootloader manifest.

KM4 bootloader OTA selection flow

Application

OTA Image

The application image named km0_km4_app.bin, including KM0, KM4 non-secure application image and KM4 secure image, can be updated through OTA, which can be chosen to boot from OTA1 or OTA2. The layout of the whole application image is illustrated below.

Layout of application image

OTA Selection Flow

The application image OTA selection flow is illustrated below.

Application image OTA selection flow

Building OTA Image

Modifying Configurations

1. Modify the version number in configuration file manifest.json under {SDK}\amebadplus_gcc_project.

   File	Tag	Description
   manifest.json	boot	Configure major and minor version for KM4 bootloader
   	app	Configure major and minor version for certificate and application

   1. Modify the version number for bootloader.

      "boot":
           {
                  "IMG_ID": "0",
                  "IMG_VER_MAJOR": 1,
                  "IMG_VER_MINOR": 1,
      
                  "SEC_EPOCH": 1,
      
                  "HASH_ALG": "sha256",
      
                  "RSIP_IV": "01020304050607080000000000000000"
           },
      

   2. Modify the version number for certificate and application.

      "app":
           {
                  "IMG_ID": "1",
                  "IMG_VER_MAJOR": 1,
                  "IMG_VER_MINOR": 1,
      
                  "SEC_EPOCH": 1,
      
                  "HASH_ALG": "sha256",
      
                  "RSIP_IV": "213253647586a7b80000000000000000"
           },
      

2. Change the bootloader version of anti-rollback and enable anti-rollback if necessary.

   1. Change the bootloader version of anti-rollback

      By default, all images use the same anti-rollback version in OTP as threshold to prevent anti-rollback attack.

      Name	OTP address	Length	Description
      BOOTLOADER_VERSION	Physical 0x36E~0x36F	16 bits	Bootloader version of anti-rollback

      The bootloader version of anti-rollback is 0 by default. Users can change the number of ‘0’ bit to enlarge the bootloader version.

      For example, users can program the bootloader version of anti-rollback to 1 by the following command:

      EFUSE wraw 36E 2 FFFE
      

   2. Enable anti-rollback

      Users can program OTP by the following command to enable anti-rollback.

      EFUSE wraw 368 1 BF
      

   Note

   • Once anti-rollback is enabled, it cannot be disabled.

   • If bootloader and application do not use the same anti-rollback version, modify BOOT_OTA_GetCertRollbackVer() in {SDK}\component\soc\amebadplus\bootloader\boot_ota_km4.c and define another anti-rollback version in OTP for the application.

3. Write the bootloader OTA2 address into OTP if users need to upgrade the bootloader, which sets the bootloader OTA2 address according to Flash_Layout in {SDK}\component\soc\amebadplus\usrcfg\ameba_flashcfg.c, refer to User Configuration.

   EFUSE wraw 36C 2 0082
   

   Note

   • The address of bootloader OTA2 is the value of OTP 0x36C with 12-bit left shifted, or is the value of OTP 0x36C * 4K.

   • If the address of bootloader OTA2 is 0xFFFFFFFF by default, the bootloader won’t be upgraded when in OTA upgrade and the device always boots from bootloader OTA1.

   • The above commands are used in the serial terminal tool.

4. Rebuild the project using make all command to generate the signed images.

5. Download the images into Flash, and reset the board.

   [MODULE_BOOT-LEVEL_INFO]: KM0 PSRAM[0c051b60:20]
        [MODULE_BOOT-LEVEL_INFO]: KM0 BOOT[20004d00:40]
        [MODULE_BOOT-LEVEL_INFO]: KM4 XIP IMG[0e000000:5ad80]
        [MODULE_BOOT-LEVEL_INFO]: KM4 SRAM[20010000:13c0]
        [MODULE_BOOT-LEVEL_INFO]: KM4 PSRAM[0e05c140:20]
        [MODULE_BOOT-LEVEL_INFO]: IMG2 BOOT from OTA 1
        [MODULE_BOOT-LEVEL_INFO]: Start NonSecure @ 0xe001715 ...
   

Generating OTA Image Automatically

The OTA image will be generated automatically when building the project.

1. The km0_km4_app.bin is included in ota_all.bin by default.

2. If the bootloader is needed to be upgraded,

   1. Type command make menuconfig under {SDK}\amebadplus_gcc_project and choose CONFIG OTA OPTION -> Upgrade Bootloader, save and exit.

   2. Modify the bootloader related configurations as described in Section Modifying Configurations.

3. Rebuild the project by command make all under {SDK}\amebadplus_gcc_project. The OTA image file called ota_all.bin will be generated under {SDK}\amebadplus_gcc_project.

Updating from Local Server

This section introduces the design principles and usage of OTA from local server. It has well-transportability to porting to OTA applications from cloud.

The OTA from local server shows how the device updates the image from a local download server. The local download server sends the image to the device based on the network socket, as the following figure illustrates.

OTA update diagram via network

Note

Make sure both the device and the PC are connecting to the same local network.

Firmware Format

The firmware format is illustrated below.

Firmware format

Firmware header

Items	Address offset	Size	Description
Version	0x00	4 bytes	Version of OTA Header, default is 0xFFFFFFFF.
Header Number	0x04	4 bytes	Number of OTA Header. For RTL8721Dx, this value can be 1, 2.
Signature	0x08	4 bytes	OTA signature is string. For RTL8721Dx, this value is OTA.
Header Length	0x0C	4 bytes	Length of OTA header. For RTL8721Dx, this value is 0x18.
Checksum	0x10	4 bytes	Checksum of OTA image
Image Length	0x14	4 bytes	Size of OTA image
Offset	0x18	4 bytes	Start position of OTA image in current image
Image ID	0x1C	4 bytes	Image ID of current image OTA_IMGID_BOOT: 0x0 OTA_IMGID_APP: 0x1

OTA Flow

The OTA demo is located at {SDK}\component\soc\amebadplus\misc\ameba_ota.c. The image upgrade is implemented in the following steps:

1. Connect to the server. The IP address, port and OTA type are needed.

2. Acquire the older firmware address to be upgraded according to the MMU setting.

   If the address is re-mapping to OTA1 space by MMU, the OTA2 address would be selected to upgrade. Otherwise, the OTA1 address would be selected.

3. Receive the firmware file header to get the target OTA image information, such as image number, image length and image ID.

4. Download the new firmware from server.

5. Erase the Flash space for new firmware and write it into Flash except Manifest structure.

6. Verify the checksum.

   If the checksum is error, OTA fails.

7. If the checksum is ok, write Manifest structure to the upgraded firmware region to indicate boot from a new firmware next time.

8. OTA is finished. Reset the device, and it would boot from the new firmware.

   

   OTA operation flow

OTA Demo

Follow these steps to run the OTA demo to update from local server:

1. Edit {SDK}\component\example\ota\example_ota.c.

   1. Edit the host according to the server IP address.

      #define PORT   8082
      static const char *host = "192.168.31.193";   //"m-apps.oss-cn-shenzhen.aliyuncs.com"
      static const char *resource = "ota_all.bin"; //"051103061600.bin"
      

   2. Edit the OTA type to OTA_LOCAL.

      ret = ota_update_init(ctx, (char *)host, PORT, (char *)resource, OTA_LOCAL);
      

2. Rebuild the project with the command make all EXAMPLE=ota and download the images to the device.

3. Modify the major and minor version number in Manifest to a bigger version as described in Version Number.

   Note

   The bootloader will select OTA image with a bigger version number by default. If users don’t want to modify the version number, modify OTA_CLEAR_PATTERN to 1 defined in ameba_ota.h before Step 2. It should only be used in the development stage.

4. Rebuild the project and copy ota_all.bin into {SDK}\tools\DownloadServer.

5. Edit {SDK}\tools\DownloadServer\start.bat.

   • port = 8082

   • file name = ota_all.bin

     @echo off
     DownloadServer 8082 ota_all.bin
     set /p DUMMY=Press Enter to Continue ...
     

6. Click start.bat, and start the download server program.

7. Reboot the DUT and connect the device to the AP which the OTA server is in.

8. Reboot the DUT to execute the new firmware after finishing image download.

OTA Firmware Swap

The following figure shows the firmware swap procedure after OTA upgrade.

OTA firmware swap procedure

User Configuration

Modify the memory layout in {SDK}\component\soc\amebadplus\usrcfg\ameba_flashcfg.c if needed.

/*
* @brif      Flash layout is set according to Flash Layout in User Manual
*  In each entry, the first item is flash regoin type, the second item is start address, the second item is end address */
const FlashLayoutInfo_TypeDef Flash_Layout[] = {
   /*Region_Type,    [StartAddr,     EndAddr]                */
   {IMG_BOOT, 0x08000000, 0x08013FFF}, //Boot Manifest(4K) + KM4 Bootloader(76K)
   //Users should modify below according to their own memory
   {IMG_APP_OTA1, 0x08014000, 0x081F3FFF}, //Certificate(4K) + Manifest(4K) + KM4 Application OTA1 + Manifest(4K) + RDP IMG OTA1

   {IMG_BOOT_OTA2, 0x08200000, 0x08213FFF}, //Boot Manifest(4K) + KM4 Bootloader(76K) OTA
   {IMG_APP_OTA2, 0x08214000, 0x083F3FFF}, //Certificate(4K) + Manifest(4K) + KM4 Application OTA2 + Manifest(4K) + RDP IMG OTA2

   {FTL,     0x08700000, 0x08702FFF}, //FTL for BT (>=12K), the start offset of flash pages which is allocated to FTL physical map.
   {VFS1, 0x08703000, 0x08722FFF}, //VFS region 1 (128K)
   {USER, 0xFFFFFFFF, 0xFFFFFFFF}, //reserve for user

   /* End */
   {0xFF, 0xFFFFFFFF, 0xFFFFFFFF},
};