# 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 recognise 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.

riotboot consists of:

  - This application which serves as minimal bootloader,
  - the module "riotboot_hdr" used to recognise RIOT firmware which riotboot
    can boot,
  - the module "riotboot_slot" used to manage the partitions (slots) with a
    RIOT header attached to them,
  - a tool in dist/tools/riotboot_gen_hdr for header generation,
  - several make targets to glue everything together.

## Concept
`riotboot` expects the flash to be formatted in slots: at CPU_FLASH_BASE
address resides the bootloader, which is followed by a slot 0 with a
RIOT firmware.

A RIOT firmware in a single slot is composed by:

```
|------------------------------- FLASH -------------------------------------|
|----- RIOTBOOT_LEN ----|----------- RIOTBOOT_SLOT_SIZE (slot 0) -----------|
                        |----- RIOTBOOT_HDR_LEN ------|
 ---------------------------------------------------------------------------
|        riotboot       | riotboot_hdr_t + filler (0) |   RIOT firmware     |
 ---------------------------------------------------------------------------
```

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)`

The bootloader will, on reset, verify the checksum of the first slot header,
then boot it. If the slot doesn't have a valid checksum, no image will be
booted and the bootloader will enter `while(1);` endless loop.

# Requirements
A board capable to use riotboot must meet the following requirements:

  - Embed a Cortex-M0+/3/4/7 processor
  - Provide the variables `ROM_START_ADDR` and `ROM_LEN`
  - Use cpu/cortexm_common/ldscripts/cortexm.ld ld script
  - Pass the cortexm_common_ldscript test in tests/
  - Being able to execute startup code at least twice (`board_init()`)
  - Declare `FEATURES_PROVIDED += riotboot` to pull the rigth dependencies
  - Being able to flash binary files, if integration with the build
    system is required for flashing

The above requirements are usually met if the board succeeds to execute
the riotboot test in tests/.

# Usage
Just compile your application using the target `riotboot`. The header
is generated automatically according to your `APP_VER`, which can be
optionally set (0 by default) in your makefile.

## Flashing
The image can be flashed using `riotboot/flash` which also flashes
the bootloader.

e.g. `BOARD=samr21-xpro FEATURES_REQUIRED+=riotboot APP_VER=$(date +%s) make -C examples/hello-world riotboot/flash`

The command compiles both the hello-world example and riotboot,
generates the header and attaches it at the beginning of the example
binary.

A comprehensive test is available at tests/riotboot.