Reference Bootloader

Tip: If you cannot access some of the repos referenced in this section, please contact us to request access.

This section is a short introduction to the bootloader. For more information, read the full README.

When a device downloads new firmware, it stores it locally (in the storage area) and reboots. A bootloader must be present on the device to handle the update after the reboot. The bootloader:

1. Takes over after reboot.

2. Checks the integrity of the active firmware. It does that by calculating the hash of the active image and comparing it to the one in the metadata header.

3. Looks for available firmware on the system. There may be more than one image, depending on image sizes.

4. Chooses the firmware with the latest timestamp.

5. Checks the integrity of the image in the storage area by checking its hash against its internal metadata header - a structure the application uses to communicate with the bootloader.

6. Copies the image in the storage area to the active application region if it is applicable.

7. Forwards control to the start of the active firmware, which contains the Update client. The firmware can now receive updates.

   Note: The bootloader must have an interface agreement with Update client to have correct handover. You can learn more in the documentation of this interface.

When an update becomes available, the Update client inside the firmware performs the following actions:

1. Receives a notification from one of its update sources.
2. Downloads the new manifest and parses it to obtain the firmware URI.
3. Fetches the firmware from one of its update sources. Either the manifest or a cost-ranking algorithm specifies the update source to use.
4. Writes the firmware into the storage region on the SD card (or external SPI Flash), as a candidate firmware image.
5. Reboots, handing control back to the bootloader.

You can find an example bootloader and more documentation here.

Flash layout for the example bootloader

The bootloader expects to have the following internal flash layout if KVSTORE is used to provide the RoT:

    +--------------------------+
    |                          |
    |                          |
    |                          |
    |Firmware Candidate Storage|
    |                          |
    |                          |
    |                          |
    +--------------------------+ <-+ update-client.storage-address
    |                          |
    |         KVSTORE          |
    |                          |
    +--------------------------+ <-+ storage_tdb_internal.internal_base_address
    |                          |
    |                          |
    |                          |
    |        Active App        |
    |                          |
    |                          |
    |                          |
    +--------------------------+ <-+ mbed-bootloader.application-start-address
    |Active App Metadata Header|
    +--------------------------+ <-+ update-client.application-details
    |                          |
    |        Bootloader        |
    |                          |
    +--------------------------+ <-+ 0