GAP Firmware Update

GAP SDK provides the standard mechanism to update the firmware in the MRAM and External Flash. This mechanism is based on SSBL + GAP CLI utils, which can be easily reconfigured and customized to adapt to different use cases and architectures.

For more details of SSBL and GAP CLI, please read related sections.

This user guides will show you how to use the mechanism to do update on the GAP9 EVK.

Architecture of an APP

An application’s flash image compiled and built in gap sdk will be structured followed the default layout in:

gap_sdk_private/utils/layouts/default_layout_multi.json

Users can also use a customer layout to customize it, and be chosen via menuconfig.

Requirements in layout

To achieve the firmware update, the flash image must includes a SSBL (Second Stage Boot Loader) which integrated with an update mechanism.

By default, user can activate the gap_cli features in ssbl to achieve this goal.

BEWARE, if the ssbl need to be update-able, we need to have multi ssbl partitions inside of a flash image.

Default Layout Boot Sequence

APP boot:

Power On -> ROM (embedded in chip) -> FSBL (First Stage Boot Loader) -> SSBL -> APP

Update boot:

Update triggered -> SSBL -> SSBL recovery mode -> GAP CLI RUN

Usage on GAP9 EVK

  1. HW Requirements:

GAP CLI support uart only, which can be used for controling the CLI and uploading the contents. Therefore, an uart device is necessary:

  • An UART based bluetooth chip

  • An USB <=> UART probe: like DSD TECH SH-U09C5

Connect this probe on EVK CN7 or pins mentioned in

  • utils/gap_cli/include/uart_cli_phy.h

  1. Install FSBL + SSBL(with CLI)

FSBL and SSBL will be compiled and installed when building the SDK (for GVSOC by default) User can change the configs, recompile and install by using following commands after configuration:

cmake --build <build dir> -t install_bin

When testing on board (boot from mram only), please enable: - Platform => Board - Core => Boot Device => MRAM - Utils => Enable GAP CLI

=> GAP CLI => Choose the UART interface => Features => Enable ssbl feature on GAP CLI

  1. Flash the app with FSBL+SSBL

Compile your app as usual, the fsbl and ssbl will be added in flash image by gapy according to the layout.

Then run the following command to flash the board:

cmake --build <build dir> -t flash

  1. Power on the board w/ boot from mram.

  2. Trigger the update:

1). By default, the ssbl recovery mode will be triggered when:

a). No bootable partition b). Boot app failed for 10 times

  • If the app hasn’t been marked as valid, it will be considered as failed. The boot counter will be increased.

c). Triggered by HW or SW (Need to be customized)

  • Add a gpio for enable the update flag, and mark it in Flash.

2). Compile the app to be updated and generate the flash descriptions:

cmake --build <build dir> -t flash_dump_app_sections

This command will generate:

  • <build dir>/mram-description.json: layout for mram can be loaded for updating

  • <build dir>/mram.bin: a bin includes all the sections to be uploaded.

Same files will be generated if there’s sections for ext-flash, but updating in ext-flash is not supported yet.

3). Once the recovery mode is triggered, open the clisender by running:

This is only used for updating fw from PC via uart probe.

clisender

4). Using Clisender to upload and trigger the update:

a). Choose the Serial port and baudrate ( 115200 by default ) b). Click on “Connect to serial port” c). Check if the clisender has connected to gap cli:

Choose “Check Status” Click “Run”

d). Start Updating:

  • SSBL/OTA => Choose MRAM and Open => Run

  • Partition update, choose the “mram-description.txt” => Run

    • This step will takes some time, until “Status: Success. Partition(s) updated.”

  • Close => Run

  1. Reboot the board.

Remarks

  1. The update is based on partition names:

    • If the name doesn’t existe => Updater will create a new partition

    • If the name exite => Update the partition

      • It will failed when exist partition size < new partition size. User can give some overcommit size by giving default partition size in the layout of 1st app, like:

{
    "name": "app",
    "template": "app binary",
    "properties": {
        "compressed": false,
        "size": <partition size>,
        binary": null
    }
}

  1. Features under development:

    • Update external flash

    • Update all:

      • Erase all except FSBL+SSBL.

      • Reflash all the partitions and renew the partition and volume tables.

  2. Features under validation:

    • Security (mbed TLS)

    • Lz4 decompression