MPLAB

wolfBoot demo application for MPLABx IDE

Instruction to compile and test under Windows or Linux OS.

Target platform

This example application has been configured to work on SAM E51 Curiosity Nano evaluation board.

wolfBoot is configured in DUAL_BANK mode, meaning that it will use the bank-swapping feature available on SAM E51 to update the firmware. This operation is much faster than physically swapping the content of two partitions one sector at a time.

wolfBoot is stored and executed at the beginning of the flash (0x00000000), while the signed application image starts at address 0x0000 8000.

Before starting

• Read the instructions in Targets.md before starting. If your version of xc32 does not have a license for optimizers, wolfBoot binary image will normally not fit in the first 32B of the flash. If this is the case, you may want to consider compiling wolfBoot separately, by providing a .config file and running make.

• The key provided in the bootloader project (in the test/keystore.c source file) is for demo purposes only. This is a 'test' key that should not be used in production, because in fact, it's very well known as it's distributed with the wolfBoot sources. Please read the instructions to generate or import your own keys if you intend to secure your target device. The test/keystore.c source file generates warnings about this when included in the build. Replace with your automatically generated keystore.c when you run keygen.

Instructions

Creating the keys

This step is required to compile the bootloader with a valid key.

Enter the tools/keytools directory and run make. This will create the keygen and sign tools. On Windows, you can use the .sln file provided to build the keytools using Visual Studio.

Check docs/Signing.md for the detailed instructions on compiling the tools and creating keys using the keygen tool.

When used with the -g option, the keygen tool will generate a keypair. The file wolfboot_signing_private_key.der in the root of the repository contains the private key that will be used to sign valid firmware images.

The file src/keystore.c now contains the public key that the bootloader incorporates, to use it later to verify the image.

After generating your own private + public keys, remember to replace the file IDE/MPLAB/test/keystore.c with the newly created one, src/keystore.c:

cp src/keystore.c IDE/MPLAB/test

Compiling and linking the images

Now both projects (wolfboot and test-app) can be compiled and linked. The resulting images will be placed in the output directory dist/default/production/ under the main directory of each of the two projects.

The only requirement for the application to be staged by wolfboot is the modified entry point when setting the origin of the space in ROM.

With the example configuration (ecc384+sha256), the manifest header size is 512B (0x200), and the main BOOT partition starts at 32 KB (0x8000).

The entry point for the application firmware must take the total offset into account, by setting ROM_ORIGIN to 0x8200. Change this parameter accordingly if you plan to modify the geometry of your partitions in FLASH.

The FLASH memory configuration for this demo is located in include/MPLAB/target.h.

The file can be changed manually to set a new partitions geometry, or a new target.h could be created in the include/ directory by running make, which will be based on the chosen configuration via the .config file. If a custom target.h is created by make, the demo version in include/MPLAB can be removed.

The wolfBoot project should build with no modifications to the project, because it does not use any .c files from the manufacturer's BSP.

On the other hand, the application uses the Harmony libraries to access the UART USB and other peripherals. To generate the necessary files, once you open the project in MPLAB X IDE, click on the MCC icon on top, then click on "Generate" to download the latest Microchip libraries and device support in your local repository.

Converting to .bin format

MPLAB ide produces executables of the bootloader and the test firmware images in both .elf and .hex formats.

Using the objcopy tool from the gcc toolchain, we can convert the images to the binary format.

To convert the wolfBoot image from .hex to .bin run:

arm-none-eabi-objcopy -I ihex -O binary IDE/MPLAB/bootloader/wolfboot-same51.dualbank.X/dist/default/production/wolfboot-same51.dualbank.X.production.hex mplab_wolfboot.bin

To convert the application the same way:

arm-none-eabi-objcopy -I ihex -O binary IDE/MPLAB/test-app/test-usb-updater.same51.X/dist/default/production/test-usb-updater.same51.X.production.hex mplab_app.bin

Signing the application image

The test application (mplab_app.bin) must be now tagged with a version number and signed. This is done by the sign tool.

The tool requires the location of the private key and one numeric argument, stored as the version tag for the signed image. Running it with version "1":

tools/keytools/sign --ecc384 mplab_app.bin wolfboot_signing_private_key.der 1

will create a new file mplab_app_v1_signed.bin, that can be uploaded into the flash memory at address 0x8000. The first 512 B in this binary file are reserved by wolfBoot for the manifest header.

Uploading the binary images to the target

Follow the instructions in docs/Targets.md to upload the binary images (mplab_wolfboot.bin and mplab_app_v1_signed.bin) to the target.

Verify that the system is up and running

When the application starts, it will send a few bytes through the USB UART interface associated.

This data can be parsed with a small tool used in wolfBoot's automated tests, test-expect-version.

• Compile the tool via:

make -C tools/test-expect-version

• Run the program:

tools/test-expect-version/test-expect-version

• Reset the target.

The tool will display the version of the current firmware running. This data is sent by the application itself when it boots.

Update the firmware via test-update-server (Linux and MacOS only)

A demo update server via USB UART is provided in the directory tools/test-update-server.

To test the update mechanism, first compile the tool via:

make -C tools/test-update-server

To provide a signed update package, sign and tag a different version of the application, e.g. for version "8" run:

tools/keytools/sign --ecc384 mplab_app.bin wolfboot_signing_private_key.der 8

Run the update server:

tools/test-update-server/server mplab_app_v8_signed.bin

Reset the target. The application will initiate an update request, to which the server will reply and will send the signed image through the USB UART.

The server should display the progress of the update on screen.

At the end of the update, verify that wolfboot has swapped the mapping of the two FLASH banks, cloned itself so it sits at the beginning of both banks, and correctly verified and staged the new firmware, by checking via test-expect-version that the current firmware running has version '8'.