From d8f64a36e46af80aff174b34d69f13a2e55a3ab4 Mon Sep 17 00:00:00 2001
From: Emmanuel Baccelli <emmanuel.baccelli@inria.fr>
Date: Tue, 15 Jan 2019 18:32:10 +0100
Subject: [PATCH] bootloaders/riotboot: updated documentation on multislot

---
 bootloaders/riotboot/README.md | 65 ++++++++++++++++++++++++++--------
 1 file changed, 50 insertions(+), 15 deletions(-)

diff --git a/bootloaders/riotboot/README.md b/bootloaders/riotboot/README.md
index 90af49a944..8b43bc6338 100644
--- a/bootloaders/riotboot/README.md
+++ b/bootloaders/riotboot/README.md
@@ -8,6 +8,9 @@ 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:
 
   - This application which serves as minimal bootloader,
@@ -19,11 +22,12 @@ riotboot consists of:
   - 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.
+`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.
 
-A RIOT firmware in a single slot is composed by:
+The bootloader and a RIOT firmware in slot 0 are depicted below:
 
 ```
 |------------------------------- FLASH -------------------------------------|
@@ -38,9 +42,8 @@ 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.
+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
 A board capable to use riotboot must meet the following requirements:
@@ -57,19 +60,51 @@ A board capable to use riotboot must meet the following requirements:
 The above requirements are usually met if the board succeeds to execute
 the riotboot test in tests/.
 
-# Usage
+# Single Slot
 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
+
+## Flashing example
 The image can be flashed using `riotboot/flash` which also flashes
-the bootloader.
+the bootloader. Below a concrete example:
 
-e.g. `BOARD=samr21-xpro FEATURES_REQUIRED+=riotboot APP_VER=$(date +%s) make -C examples/hello-world riotboot/flash`
+`BOARD=samr21-xpro FEATURES_REQUIRED+=riotboot APP_VER=$(date +%s) make -C examples/hello-world flash-combined-slot0`
 
-The command compiles both the hello-world example and riotboot,
-generates the header and attaches it at the beginning of the example
-binary.
+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.
+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:
+
+  - `riotboot/slot1`: Builds a firmware in ELF and binary format with
+    an offset at the end of slot 0;
+  - `riotboot/flash-slot1`: builds and flash a firmware for slot 1;
+  - `riotboot/flash-extended-slot0` builds + flashes slot 0 and erases (zeroes)
+    the metadata of slot 1 (invalidating it);
+  - `riotboot` builds both slot 0 and 1.
+
+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).
+
+## Flashing examples
+
+The following sequence of commands tests building, flashing and booting slot 0,
+then slot 1. tests/riotboot prints out the current booted slot in the shell.
+
+To test building, flashing and booting the first slot:
+
+`BOARD=samr21-xpro APP_VER=$(date +%s) make -C tests/riotboot/ riotboot/flash-combined-slot0 test`
+
+For the second slot:
+
+`BOARD=samr21-xpro APP_VER=$(date +%s) make -C tests/riotboot/ riotboot/flash-slot1 test`