bootloader: add riotboot minimal bootloader #10065

kYc0o · 2018-09-27T17:50:21Z

Contribution description

RIOT image header and "riotboot" bootloader

Overview

riotboot is the name of a minimal bootloader application and infrastructure.
It consists of

the application "riotboot" in the bootloaders folder which serves as minimal bootloader
the module "riot_hdr" used to recognise RIOT firmware images which riotboot can boot.
the module "slot_util" used to manage the images (slots) with a RIOT header attached to them
a tool in dist/tools/riot_hdr for header generation.
several make targets to glue everything together

Concept

riotboot expects the flash to be separated in slots: at CPU_FLASH_BASE address resides the bootloader, which is followed by a slot 0 with a firmware image.

A RIOT image with a single slot looks like:

|------------------------------- FLASH -------------------------------------|
|----- RIOTBOOT_LEN ----|----------- RIOTBOOT_SLOT_SIZE (slot 0) -----------|
                        |--- RIOTBOOT_HDR_LEN ----|
 ---------------------------------------------------------------------------
|       bootloader      | riot_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(riot_hdr_t).

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

The header contains

/**
 * @brief Structure to store image header - All members are little endian
 * @{
 */
typedef struct {
    uint32_t magic_number;         /**< header magic_number (always "RIOT")    */
    uint32_t version;              /**< Integer representing firmware version  */
    uint32_t start_addr;           /**< Start address in flash                 */
    uint32_t chksum;               /**< checksum of riot_hdr                   */
} riot_hdr_t;
/** @} */

The bootloader "riotboot" only cares about checksum.

Testing procedure

There's a test provided in tests/riotboot. This has only tested for now in:

samr21-xpro
iotlab-m3 (desk)
nucleo-l152re

Please add above the boards that you have tested and worked.

Issues/PRs references

#9342
#9969

kaspar030 · 2018-09-28T08:22:05Z

Why did you cut out the slot selection logic?

bergzand · 2018-09-28T08:29:17Z

Why did you cut out the slot selection logic?

From the description it looks like this is a minimal version that only supports a single firmware slot.

kaspar030 · 2018-09-28T08:31:10Z

From the description it looks like this is a minimal version that only supports a single firmware slot.

Yup, but my original commit contained like, ~15 lines more, but did support multiple slots.

IMO, going through all the bootloader hoops to verify a firmware's metadata hash seems a bit pointless.

kYc0o · 2018-09-28T14:45:41Z

Yup, but my original commit contained like, ~15 lines more, but did support multiple slots.

IMO, going through all the bootloader hoops to verify a firmware's metadata hash seems a bit pointless.

I wanted to provide the minimal as possible and then build on top of it the extensions, like support for two firmware slots and flashing. I think I can re-add this logic since it doesn't hurt, but it will look like we're looking for inexistent slots (there are no support for second slot here).

Anyways, there are some current problems to be solved first, after solve them I can get back into this question.

emmanuelsearch · 2018-10-01T15:10:44Z

@kYc0o any eta on when you will push the changes?

kYc0o · 2018-10-01T17:34:59Z

Anyways, there are some current problems to be solved first, after solve them I can get back into this question.

Marking WIP because of this.

@kYc0o any eta on when you will push the changes?

Should be done by tomorrow at latest.

kYc0o · 2018-10-02T16:50:26Z

Not WIP anymore.

I changed several conceptual things on this PR and remove some awful dependencies which were not needed.

Now, slot 0 represents the first firmware image, while the bootloader represents no slot. This change was to be aligned on other bootloaders (e.g. mcuboot) slot concepts, and actually having slot 0 as the bootloader wasn't really useful.

RIOT_HDR_SIZE is now removed and it's not anymore a dependency for the header generator, it's now rather passed as an argument.

The compilation of genhdr is now automatic, but only depends on the existence of the binary, so any modification to the code of riot_hdr is not tracked. @cladmi do you have an idea to do it without importing all the files from riot_hdr?

Finally, I don't know how to get rid of the cppcheck error, in my system I don't have it, most likely because I have a more recent cppcheck version.

kYc0o · 2018-10-04T16:28:22Z

Pushed some changes to get rid of the cppcheck error. Although, it was a false negative IMHO so we should update Murdock to avoid those.

jcarrano · 2018-12-13T13:54:58Z

@kYc0o

Can you find at least one point of failure?
Not of failure, but those mechanisms in make that depend on order tend to be be fragile. In any case, I wrote that as a comment and not as a change request because I realize it's not an issue of this PR, and there's not much you can do about it.

emmanuelsearch · 2018-12-13T14:15:21Z

@cladmi must the docker aspect you mention be part of this PR (or can it be a subsequent PR)?

emmanuelsearch · 2018-12-13T14:16:32Z

@jcarrano what is blocking (if anything) in your comments, from your point of view?

It's easier to fix it myself in a PR later.

emmanuelsearch · 2018-12-17T08:36:05Z

ping @cladmi

cladmi · 2018-12-17T19:12:21Z

@emmanuelsearch issue is also present for mcuboot integration so not a new issue.
I will try to fix it for both for the release.

Not much time to review the details, but test works and also helped with some of the implementation.

danpetry · 2018-12-18T11:36:11Z

Please squash and rebase. @kaspar030 do you need any more changes before merging?

kaspar030 · 2018-12-18T17:58:27Z

IMO this is good to go. Please squash!

This module adds some helper function to manage slots created with a riotboot_hdr header. Co-authored-by: Kaspar Schleiser <kaspar@schleiser.de>

In order to use the RIOT bootloader (riotboot) a header needs to be created and placed before the firmware. This tool generates such a header with the expected information by the bootloader. Co-authored-by: Kaspar Schleiser <kaspar@schleiser.de>

riotboot is introduced here and makes use of riotboot_hdr, which indentifies the images encapsulated as slots. The slot size and offset is configurable, which makes slots extendable if needed, e.g. 2 or more slots can be transparently added. Co-authored-by: Kaspar Schleiser <kaspar@schleiser.de> Co-authored-by: Gaëtan Harter <gaetan.harter@fu-berlin.de>

This new function allows to jump to another execution environment (VTOR) located at a certain (aligned) address. It's used to boot firmwares at another location than `CPU_FLASH_BASE`. The user needs to ensure that the CPU using this feature is able to be initialised at least twice while jumping to the RIOT `reset_handler_default` function, since it initialises the CPU again (calls cpu_init()). Co-authored-by: Kaspar Schleiser <kaspar@schleiser.de>

RIOTBOOT_SLOT_LEN is calculated as an hexadecimal value and handles ROM_LEN defined as kilobytes like '512K' This enables support for all the cortex-m0+/3/4/7 arch, so most boards embedding these are potentially supported. One needs just to ensure that the CPU can be initialised at least twice. Co-authored-by: Gaëtan Harter <gaetan.harter@fu-berlin.de>

Currently only tested boards provide the feature riotboot. Potentially all boards embeding a cortex-m0+/3/4/7 are able to have riotboot as a feature, but other dependencies need to be met, e.g. usage of cortexm.ld linker script, double initialisation of cpu_init(), etc. See doc in bootloaders/riotboot.

The tests overrides the target all to be tested by the CI. All the instructions how to use it are in README.md The test is successful if the image boots and displays information about the image and running slot. Co-authored-by: Federico Pellegrin <fede@evolware.org>

Co-authored-by: Federico Pellegrin <fede@evolware.org>

kaspar030 · 2018-12-18T18:55:01Z

I squashed as @kYc0o is currently offline. As I co-authored most of the code, we'll need more than my ACK. Anyhow, I think we should get this in ASAP. We can always iterate.

emmanuelsearch · 2018-12-18T19:09:01Z

@kaspar030 we have another ACK from @danpetry so we're good if Murdock is green.

miri64 · 2018-12-18T19:28:02Z

🎉

kYc0o · 2018-12-19T05:30:27Z

😃 a big thanks to all the contributors and reviewers for making this PR in!

waehlisch · 2018-12-19T11:16:04Z

@jcarrano

It's easier to fix it myself in a PR later.

We don't want forget this: Can you create issues or the PR timely.

kYc0o added this to the Release 2018.10 milestone Sep 27, 2018

kYc0o force-pushed the pr/riotboot branch 4 times, most recently from a6721e5 to 0d2a562 Compare September 27, 2018 18:50

kYc0o added State: WIP State: The PR is still work-in-progress and its code is not in its final presentable form yet Discussion: RFC The issue/PR is used as a discussion starting point about the item of the issue/PR labels Oct 1, 2018

kYc0o requested review from cladmi, emmanuelsearch and kaspar030 October 1, 2018 17:35

waehlisch mentioned this pull request Oct 2, 2018

OTA: tracking issue #9342

Closed

kYc0o force-pushed the pr/riotboot branch 2 times, most recently from 584dfa6 to fcec3c6 Compare October 2, 2018 16:37

kYc0o removed the State: WIP State: The PR is still work-in-progress and its code is not in its final presentable form yet label Oct 2, 2018

kYc0o force-pushed the pr/riotboot branch 2 times, most recently from 5b924f3 to dbb74e3 Compare October 4, 2018 15:38

kYc0o force-pushed the pr/riotboot branch from dbb74e3 to 1a20dce Compare October 5, 2018 15:11

kaspar030 approved these changes Dec 18, 2018

View reviewed changes

kYc0o and others added 8 commits December 18, 2018 19:31

sys/riotboot: add riotboot_slot module

2df0abf

This module adds some helper function to manage slots created with a riotboot_hdr header. Co-authored-by: Kaspar Schleiser <kaspar@schleiser.de>

tests/riotboot: add basic automatic test in python

66911d6

Co-authored-by: Federico Pellegrin <fede@evolware.org>

kaspar030 force-pushed the pr/riotboot branch from 10aca80 to 66911d6 Compare December 18, 2018 18:33

emmanuelsearch merged commit 3a3c23d into RIOT-OS:master Dec 18, 2018

fedepell mentioned this pull request Dec 18, 2018

sam0 flashpage_write: correct translation from RIOT pages to CPU pages writing #10069

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

bootloader: add riotboot minimal bootloader #10065

bootloader: add riotboot minimal bootloader #10065

kYc0o commented Sep 27, 2018 •

edited by danpetry

Loading

kaspar030 commented Sep 28, 2018

bergzand commented Sep 28, 2018

kaspar030 commented Sep 28, 2018

kYc0o commented Sep 28, 2018

emmanuelsearch commented Oct 1, 2018

kYc0o commented Oct 1, 2018

kYc0o commented Oct 2, 2018

kYc0o commented Oct 4, 2018

jcarrano commented Dec 13, 2018

emmanuelsearch commented Dec 13, 2018

emmanuelsearch commented Dec 13, 2018

emmanuelsearch commented Dec 17, 2018

cladmi commented Dec 17, 2018

danpetry commented Dec 18, 2018

kaspar030 commented Dec 18, 2018

kaspar030 commented Dec 18, 2018

emmanuelsearch commented Dec 18, 2018

miri64 commented Dec 18, 2018

kYc0o commented Dec 19, 2018 •

edited

Loading

waehlisch commented Dec 19, 2018

bootloader: add riotboot minimal bootloader #10065

bootloader: add riotboot minimal bootloader #10065

Conversation

kYc0o commented Sep 27, 2018 • edited by danpetry Loading

Contribution description

RIOT image header and "riotboot" bootloader

Overview

Concept

Testing procedure

Issues/PRs references

kaspar030 commented Sep 28, 2018

bergzand commented Sep 28, 2018

kaspar030 commented Sep 28, 2018

kYc0o commented Sep 28, 2018

emmanuelsearch commented Oct 1, 2018

kYc0o commented Oct 1, 2018

kYc0o commented Oct 2, 2018

kYc0o commented Oct 4, 2018

jcarrano commented Dec 13, 2018

emmanuelsearch commented Dec 13, 2018

emmanuelsearch commented Dec 13, 2018

emmanuelsearch commented Dec 17, 2018

cladmi commented Dec 17, 2018

danpetry commented Dec 18, 2018

kaspar030 commented Dec 18, 2018

kaspar030 commented Dec 18, 2018

emmanuelsearch commented Dec 18, 2018

miri64 commented Dec 18, 2018

kYc0o commented Dec 19, 2018 • edited Loading

waehlisch commented Dec 19, 2018

kYc0o commented Sep 27, 2018 •

edited by danpetry

Loading

kYc0o commented Dec 19, 2018 •

edited

Loading