Merge pull request #15417 from fjmolinas/pr_riotboot_porting_guide

riotboot: add basic porting guide [TAKEOVER]

bootloaders/riotboot/README.md

@@ -46,19 +46,12 @@ 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:
+Try to compile and run tests/riotboot:
 
-  - 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 right dependencies
-  - Being able to flash binary files, if integration with the build
-    system is required for flashing
+$ BOARD=<board> make -C tests/riotboot flash test
 
-The above requirements are usually met if the board succeeds to execute
-the riotboot test in tests/.
+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()`)
@@ -72,7 +65,6 @@ 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
@@ -97,12 +89,12 @@ 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.
+- `riotboot/slot1`: Builds a firmware in ELF and binary format with
+  an offset at the end of slot 0;
+- `riotboot/flash-slot1`: builds and flashes 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
@@ -112,3 +104,50 @@ flash` if the `riotboot` feature is used.
 ## Testing riotboot
 
 See [tests/riotboot/README.md](https://github.com/RIOT-OS/RIOT/blob/master/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:
+
+- Provide the variables `ROM_START_ADDR` and `ROM_LEN` as well as
+`RAM_LEN` and `RAM_START_ADDR`.
+- Adapt the linker scripts for your cpu to pass the test
+[tests/cortexm_common_ldscript](../../tests/cortexm_common_ldscript). This test
+ensures that the linker script supports building firmware's with a rom offset
+and specific sized firmware's.
+- Make the startup code `board_init()`, `cpu_init` idempotent, i.e. whether you
+execute it once, or twice, it works all the same. The global define `RIOTBOOT`
+can be useful here. (e.g. [cpu/efm32/cpu.c](../../cpu/efm32/cpu.c))
+- Make sure (and adapt if needed) that the flasher script can:
+    - flash a `.bin`
+    - flash at a specified offset
+    - flash without performing mass erase, only erase flash sections to be written
+  e.g.: [makefiles/tools/edbg.inc.mk](../../makefiles/tools/edbg.inc.mk)
+- Declare `FEATURES_PROVIDED += riotboot` for the target `BOARD`.
+- Make sure that `RIOTBOOT_LEN` size is such that the remainder of the flash
+can be divided by the number slots while staying `FLASHPAGE_SIZE` aligned.
+e.g: [cpu/nrf52/Makefile.include](../../cpu/nrf52/Makefile.include)
+- Check other specific `BOARD`/`CPU` flash alignment requirements (e.g.:
+kinetis vector table must be naturally aligned to the power of two, see
+[cpu/kinetis/Makefile.include](../../cpu/kinetis/Makefile.include))
+
+## Porting to a board based on other types of MCUs
+
+For other MCU architectures the following extra requirements must be fulfilled:
+
+- Provide the functions defined in the header
+[sys/include/riotboot/slot.h](../../sys/include/riotboot/slot.h), in particular
+`riotboot_slot_jump(unsigned slot)` which will allow jumping from the bootloader
+to another slot/application.
+- Adapt the linker script so that it supports building firmware's with a rom
+offset and a defined firmware size. To get an idea look at
+[cpu/cortexm_common/Makefile.include](../../cpu/cortexm_common/Makefile.include)
+
+Additional remarks:
+
+- If your are in Big-Endian, you may need to further adapt some part of the code.