riotboot

Overview

This folder contains a simple bootloader called "riotboot". A header with metadata of length RIOTBOOT_HDR_LEN precedes the RIOT firmware. The header contains "RIOT" as a magic number to recognize a RIOT firmware image, a checksum, and the version of the RIOT firmware APP_VER. This bootloader verifies the checksum of the header which is located at an offset (ROM_OFFSET) with respect to the ROM_START_ADDR defined by the CPU, just after the space allocated for riotboot.

In case of multiple firmware slots, the bootloader iterates through valid headers and boots the newest image.

riotboot consists of:

Concept

riotboot expects the flash to be formatted in slots: at the CPU_FLASH_BASE address resides the bootloader, which is followed by a slot 0 containing a RIOT firmware image. If present, a second firmware image (in slot 1) starts just afterwards.

The bootloader and a RIOT firmware in slot 0 are depicted below:

|------------------------------- FLASH -------------------------------------|
|----- RIOTBOOT_LEN ----|----------- RIOTBOOT_SLOT_SIZE (slot 0) -----------|
|----- RIOTBOOT_HDR_LEN ------|
---------------------------------------------------------------------------
| riotboot | riotboot_hdr_t + filler (0) | RIOT firmware |
---------------------------------------------------------------------------
#define FLASH
FLASH register bank.
Structure to store image header - All members are little endian.
Definition: hdr.h:51

Please note that RIOTBOOT_HDR_LEN depends on the architecture of the MCU, since it needs to be aligned to 256B. This is fixed regardless of sizeof(riotboot_hdr_t)

Also note that, if no slot is available with a valid checksum, no image will be booted and the bootloader will enter while(1); endless loop.

Requirements

Try to compile and run tests/riotboot:

$ BOARD=<board> make -C tests/riotboot flash test

If the test succeeds, your board is supported. Else you can try to port riotboot to your board (see the below porting guide).

When building the bootloader, the global define RIOTBOOT is available. You can use this define to skip certain parts in board_init() (or cpu_init()) that should not be executed during boot. Note that this define is different from MODULE_RIOTBOOT, which is also defined when building an application that utilizes riotboot.

Single Slot

Just compile your application with FEATURES_REQUIRED += riotboot. The header is generated automatically according to your APP_VER, which can be optionally set (current system time in seconds since 1970 (epoch) by default) in your makefile.

Flashing example

If your application is using the riotboot feature, the usual targets (all, flash, flash-only) will automatically compile and/or flash both the bootloader and slot0, while ensuring that slot 1 is invalidated so slot 0 will be booted.

The image can also be flashed using riotboot/flash which also flashes the bootloader. Below a concrete example:

BOARD=samr21-xpro FEATURES_REQUIRED+=riotboot APP_VER=$(date +s) make -C examples/hello-world riotboot/flash-combined-slot0

The above compiles a hello world binary and a bootloader, then flashes the combined binary comprising of: bootloader + slot 0 header + slot 0 image. If booted, the device will execute the Hello-World image.

A comprehensive test is available at tests/riotboot (also see below).

Multi-Slot

When several slots are available, the bootloader iterates through valid headers and boots the newest image (which has the greater VERSION)

Dedicated make targets are available to build and flash several slots:

In particular, if one wants to be sure to boot a particular image, using the target riotboot/flash-extended-slot0 is the way to go (resulting in only slot 0 being valid, thus being booted). This is done automatically by make flash if the riotboot feature is used.

Testing riotboot

See tests/riotboot/README.md.

Quick riotboot porting guide

Your board/cpu is not supported yet? Try to port riotboot!

Porting to a board based on an Arm Cortex-M0+/3/4/7/22/33 MCU

Extending riotboot to support another board with a Cortex-M0+/3/4/7/22/33 microcontroller is rather straightforward. You need to:

Porting to a board based on other types of MCUs

For other MCU architectures the following extra requirements must be fulfilled:

Additional remarks: