West Build and Flash

Applications for the Atmosic EVK boards can be built, flashed, and debugged using the familiar west build and west flash.

It is recommended to set the environment variables ZEPHYR_TOOLCHAIN_VARIANT to zephyr and ZEPHYR_SDK_INSTALL_DIR to the directory where Zephyr SDK is installed. For example, assuming the installed SDK version is 0.16.4 in the home directory, for reference, it will be like this in a bash shell environment: (use setenv in a C shell environment, or set for Windows):

export ZEPHYR_TOOLCHAIN_VARIANT=zephyr
export ZEPHYR_SDK_INSTALL_DIR=$HOME/zephyr-sdk-0.16.4

Atmosic boards require at least two images to be built: the SPE and the application. SPE is the Secure Processing Environment, and the application typically resides in the non-secure (NSPE) portion.

The Atmosic SPE can be found under <WEST_TOPDIR>/openair/samples/spe.

In the remainder of this document, substitute for <ZEPHYR_TOOLCHAIN_VARIANT>, <ZEPHYR_SDK_INSTALL_DIR>, <WEST_TOPDIR>, <SPE>, <APP>, <MCUBOOT>, <ATMWSTK>, <BOARD>, and <DEVICE_ID> appropriately. For example:

<ZEPHYR_TOOLCHAIN_VARIANT>: zephyr
<ZEPHYR_SDK_INSTALL_DIR>: /absolute/path/to/zephyrSDK
<WEST_TOPDIR>: /absolute/path/to/zephyrproject
<SPE>: openair/samples/spe
<APP>: zephyr/samples/bluetooth/peripheral
<MCUBOOT>: bootloader/mcuboot/boot/zephyr
<ATMWSTK>: PD50 or FULL for ATM33, PD50 or CPD200 for ATM34
<BOARD>: ATMEVK-3430e-YQN-5
<DEVICE_ID>: 000900036960

  • <DEVICE_ID> is the unique ID from the J-Link device used to program. For FTDI, the format will be ATRDIXXXX.

Building and Flashing

Applications can be built with MCUboot or without the MCUboot option. If a device firmware update (DFU) is not needed, you can choose the option without MCUboot. If you require DFU, then the MCUboot option is required.

A. Non-MCUboot Option

  1. Build the SPE:

west build -p -s <SPE> -b <BOARD> -d build/<BOARD>/<SPE>

  1. Build the Application:

Note: <BOARD>//ns is the non-secure variant of <BOARD>.

Build the app with the non-secure board variant and the SPE configured as follows:

west build -p -s <APP> -b <BOARD>//ns -d build/<BOARD>_ns/<APP> -- -DCONFIG_SPE_PATH=\"<WEST_TOPDIR>/build/<BOARD>/<SPE>\" -DCONFIG_ATMWSTK_<ATMWSTK>=y

Passing the path to the SPE is for linking in the non-secure-callable veneer file generated in building the SPE.

With this approach, each built image has to be flashed separately. Optionally, build a single merged image by enabling CONFIG_MERGE_SPE_NSPE, thereby minimizing the flashing steps:

west build -p -s <APP> -b <BOARD>//ns -d build/<BOARD>_ns/<APP> -- -DCONFIG_SPE_PATH=\"<WEST_TOPDIR>/build/<BOARD>/<SPE>\" -DCONFIG_ATMWSTK_<ATMWSTK>=y -DCONFIG_MERGE_SPE_NSPE=y

  1. Flashing the SPE and the Application:

Atmosic provides a mechanism to decrease the legacy programming time called FAST LOAD. Apply the option --fast_load to enable the FAST LOAD.

Flash the SPE and the application separately if CONFIG_MERGE_SPE_NSPE was not enabled:

west flash --device <DEVICE_ID> --jlink --fast_load --verify -d build/<BOARD>/<SPE> --noreset
west flash --device <DEVICE_ID> --jlink --fast_load --verify -d build/<BOARD>_ns/<APP>

Alternatively, if CONFIG_MERGE_SPE_NSPE was enabled in building the application, the first step (flashing the SPE) can be skipped.

Notes:

  • -p option specifies pristine build, similar to make clean option. Flags passed after the -- instructs west to treat them as C Pre processor flags passed to Make subsystem.

  • Above commands assumed use of Wireless Stack Library choice of PD50 for ATM33xx, and PD50/CPD200 for ATM34xx as specified by <ATMWSTK>. For ATM33xx platform, FULL wireless stack option does not support statically linked library, it only supports fixed wireless stack. When using FULL wireless stack for ATM33xx platform, additional DTSI configuration -DDTS_EXTRA_CPPFLAGS="-DFIXED_ATMWSTK=<ATMWSTK>;" also needs to be set to create a partition to host the ATMWSTK image when building SPE and application. As shown below:

    west build -p -s <SPE> -b <BOARD> -d build/<BOARD>/<SPE> -- -DDTS_EXTRA_CPPFLAGS="-DFIXED_ATMWSTK=<ATMWSTK>;"

west build -p -s <APP> -b <BOARD>//ns -d build/<BOARD>_ns/<APP> -- -DCONFIG_SPE_PATH=\"<WEST_TOPDIR>/build/<BOARD>/<SPE>\" -DDTS_EXTRA_CPPFLAGS="-DFIXED_ATMWSTK=<ATMWSTK>;" -DCONFIG_ATMWSTK_<ATMWSTK>=y -DCONFIG_MERGE_SPE_NSPE=y

  • Additionally, use of Fixed wireless stack, requires an extra step of programming the flash with elf file of the wireless stack as shown below. Flash this first before flashing SPE or Application.

    west flash --verify --device <DEVICE_ID> --jlink --fast_load --skip-rebuild -d build/<BOARD>/<SPE> --use-elf --elf-file openair/modules/hal_atmosic/ATM33xx-5/drivers/ble/atmwstk_<ATMWSTK>.elf --noreset

    Look at section on Atmosic BLE Stack for more details.

B. MCUboot Option

  1. Build the MCUboot and the SPE:

To build with MCUboot, first build MCUboot:

west build -p -s <MCUBOOT> -b <BOARD>@mcuboot_bl -d build/<BOARD>/<MCUBOOT>

For ATM33xx platforms, insert -DDTS_EXTRA_CPPFLAGS="-DDFU_IN_FLASH" OR -DDTS_EXTRA_CPPFLAGS="-DFIXED_ATMWSTK=<ATMWSTK>;-DDFU_IN_FLASH" if using Fixed Wireless Stack.

and then the Atmosic SPE:

west build -p -s <SPE> -b <BOARD>@mcuboot -d build/<BOARD>/<SPE> -- -DCONFIG_BOOTLOADER_MCUBOOT=y -DCONFIG_MCUBOOT_GENERATE_UNSIGNED_IMAGE=n -DDTS_EXTRA_CPPFLAGS=";"

For ATM33xx platform, the flag DTS_EXTRA_CPPFLAGS above becomes -DDTS_EXTRA_CPPFLAGS="-DDFU_IN_FLASH" OR -DDTS_EXTRA_CPPFLAGS="-DFIXED_ATMWSTK=<ATMWSTK>;-DDFU_IN_FLASH" if using Fixed Wireless Stack.

Note that make use of “board revision” to configure our board partitions to work for MCUboot. On top of the “revisions,” MCUboot currently needs an additional overlay that must be provided through the command line to give it the entire SRAM.

  1. Build the Application with MCUboot and SPE:

Build the application with MCUboot and SPE as follows:

west build -p -s <APP> -b <BOARD>@mcuboot//ns -d build/<BOARD>_ns/<APP> -- -DCONFIG_BOOTLOADER_MCUBOOT=y -DCONFIG_MCUBOOT_SIGNATURE_KEY_FILE=\"bootloader/mcuboot/root-ec-p256.pem\" -DCONFIG_SPE_PATH=\"<WEST_TOPDIR>/build/<BOARD>/<SPE>\" -DCONFIG_ATMWSTK_<ATMWSTK>=y -DDTS_EXTRA_CPPFLAGS=";" -DEXTRA_CONF_FILE="<WEST_TOPDIR>/openair/doc/dfu/overlay-bt-dfu.conf"

For ATM33xx platform, the flag DTS_EXTRA_CPPFLAGS above becomes -DDTS_EXTRA_CPPFLAGS="-DDFU_IN_FLASH" OR -DDTS_EXTRA_CPPFLAGS="-DFIXED_ATMWSTK=<ATMWSTK>;-DDFU_IN_FLASH" if using Fixed Wireless Stack.

This is somewhat of a non-standard workflow. When passing -DCONFIG_BOOTLOADER_MCUBOOT=y on the application build command line, west automatically creates a signed, merged image (zephyr.signed.{bin,hex}), which is ultimately used by west flash to program the device. The original application binaries are renamed with a .nspe suffixed to the file basename (zephyr.{bin,hex,elf} renamed to zephyr.nspe.{bin,hex,elf}) and are the ones that should be supplied to a debugger.

  1. Flashing the MCUboot, SPE, and the Application:

Flash MCUboot

Atmosic provides a mechanism to decrease the legacy programming time called FAST LOAD. Apply the option --fast_load to enable the FAST LOAD:

west flash --verify --device <DEVICE_ID> --jlink --fast_load -d build/<BOARD>/<MCUBOOT> --noreset

Note that adding --erase_flash is an option to erase Flash if needed.

Flash the signed application image (merged with SPE):

west flash --verify --device <DEVICE_ID> --jlink --fast_load -d build/<BOARD>_ns/<APP>

For ATM33xx platform, if using Fixed Wireless Stack, additional step to flash the Fixed Wireless Stack is required. Look at Non-MCUboot section above for flashing the elf file.