[riot-notifications] [RIOT-OS/RIOT] riotboot: add basic porting guide (#11597)

Alexandre Abadie notifications at github.com
Tue May 28 22:48:36 CEST 2019


aabadie requested changes on this pull request.

Found minor things but otherwise it looks good :)
Maybe also split long lines (there are a few) ?

> @@ -46,19 +46,9 @@ 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:
-
-  - 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
-
-The above requirements are usually met if the board succeeds to execute
-the riotboot test in tests/.
+Try to compile and run tests/riotboot. If the test succeeds, your board is
+supported. Else you can try to port rioboot to your board (see the below

s/rioboot/rio**t**boot/

> @@ -108,3 +98,43 @@ To test building, flashing and booting the first slot:
 For the second slot:
 
 `BOARD=samr21-xpro APP_VER=$(date +%s) make -C tests/riotboot/ riotboot/flash-slot1 test`
+
+# Quick riotboot porting guide
+
+Your board is not supported yet? Try to port riotboot!
+
+## Porting to a board based on am Arm Cortex-M0+/3/4/7 MCU
+
+Extending riotboot to support another board with a Cortex-M0+/3/4/7
+microcontroller is rather straightforward. You need to:
+
+  - Provide the variables `ROM_START_ADDR` and `ROM_LEN` as well as

Here and below, there's no need for spaces before `-` since there are first level bullet points.

> @@ -46,19 +46,9 @@ 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:
-
-  - 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
-
-The above requirements are usually met if the board succeeds to execute
-the riotboot test in tests/.
+Try to compile and run tests/riotboot. If the test succeeds, your board is

Maybe provide the full `make` command ?

> +in your board's Makefile.features
+
+## Porting to a board based on other types of MCUs
+
+More work is necessary, but the approach of riotboot is purposedly kept
+"minimal" in order to minimize this work.
+
+- Provide the functions defined in the header sys/include/riotboot/slot.h, in particular `riotboot_slot_jump(unsigned slot)`.
+- Adapt the linker script to link to different start addresses for the bootloader, and for slot(s) for example `SLOT0_LEN`, `SLOT1_LEN`, and linker script config with `ROM_OFFSET` and `FW_ROM_LEN`. To get an idea, take a look at cpu/cortexm_common/Makefile.include
+- Make the startup code idempotent.
+- Adapt the flasher script to support .bin flashing with an offset. To get an idea, you can look at makefiles/tools/edbg.inc.mk
+- Modify flags e.g. add `FEATURES_PROVIDED += riotboot` in your board's Makefile.features
+
+Additional remarks:
+
+- Check the your board's Flash memory alignment specificities!

Should be `Check your board's....` (extra `the`) ?

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/RIOT-OS/RIOT/pull/11597#pullrequestreview-242912056
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.riot-os.org/pipermail/notifications/attachments/20190528/dfd9ca77/attachment.html>


More information about the notifications mailing list