mcuboot/docs/readme-mbed.md

42 lines
2.8 KiB
Markdown
Raw Normal View History

Mbed-OS porting layer implementation for mcuboot This PR provides a porting layer implementation and framework for building an mcuboot-based bootloader with Mbed-OS. Some symbols are not provided by the Mbed-OS port within mcuboot, namely: - The secondary storage device (see below) - The signing keys - The encryption keys, if used Use of this port is demonstrated by the following projects: - https://github.com/AGlass0fMilk/mbed-mcuboot-demo (a complete mcuboot/Mbed-OS-based bootloader) - https://github.com/AGlass0fMilk/mbed-mcuboot-blinky (example showing how to make an Mbed-OS application that is bootable by mcuboot) Memory porting implementation: The underlying implemenation uses Mbed's BlockDevice API as the storage backend for mcuboot's memory operations. This provides a very flexible way of configuring the location and layout of the secondary flash storage area. To build an mcuboot-based bootloader with Mbed-OS, the user must implement a hook function, mbed::BlockDevice* get_secondary_bd(), to provide the secondary BlockDevice that mcuboot will use. The signing and encryption keys must also be provided by the user. They can be generated using the existing imgtool utility in the same manner used by Zephyr. There are no automated build steps currently provided by Mbed-OS to sign/encrypt build artifacts. Known limitations: The update candidate encryption features have not yet been fully tested. A truly secure implementation will require integration with Mbed's TRNG API in the future to inhibit side-channel attacks on the decryption process. The TinyCrypt backend is currently only supported for Mbed-OS builds when building with the GCC toolchain. The new cmake-based Mbed-OS build system will fix the underlying issue (file name uniqueness). Signed-off-by: George Beckstein <becksteing@embeddedplanet.com> Signed-off-by: Evelyne Donnaes <evelyne.donnaes@arm.com> Signed-off-by: Lingkai Dong <lingkai.dong@arm.com> Co-authored-by: Lingkai Dong <lingkai.dong@arm.com> Co-authored-by: Fabio Utzig <fabio.utzig@nordicsemi.no>
2020-10-30 05:32:11 +08:00
# MCUboot port for Mbed OS
This is an MCUboot port for Mbed OS.
## Using MCUboot
Note: The following is a general overview. It does not cover MCUboot or Mbed OS basics.
See https://github.com/AGlass0fMilk/mbed-mcuboot-demo as a detailed example.
### Basic configurations
To use MCUboot, you need to create an Mbed OS project with the following configurations:
* `"mcuboot.primary-slot-address"`: address of the primary slot in the internal flash
* `"mcuboot.slot-size"`: size of an image slot (only one image, two slots are currently supported)
* `"mcuboot.max-img-sectors"`: maximum number of sectors, should be at least the number of sectors in each slot
* `"target.restrict_size"`: the maximum size of the bootloader, such that it does not overlap with the primary slot
More configurations such as signing algorithm, slot swapping, etc. can be found in [mbed_lib.json](https://github.com/mcu-tools/mcuboot/tree/master/boot/mbed/mbed_lib.json). Please note that certain features are not currently supported.
Mbed-OS porting layer implementation for mcuboot This PR provides a porting layer implementation and framework for building an mcuboot-based bootloader with Mbed-OS. Some symbols are not provided by the Mbed-OS port within mcuboot, namely: - The secondary storage device (see below) - The signing keys - The encryption keys, if used Use of this port is demonstrated by the following projects: - https://github.com/AGlass0fMilk/mbed-mcuboot-demo (a complete mcuboot/Mbed-OS-based bootloader) - https://github.com/AGlass0fMilk/mbed-mcuboot-blinky (example showing how to make an Mbed-OS application that is bootable by mcuboot) Memory porting implementation: The underlying implemenation uses Mbed's BlockDevice API as the storage backend for mcuboot's memory operations. This provides a very flexible way of configuring the location and layout of the secondary flash storage area. To build an mcuboot-based bootloader with Mbed-OS, the user must implement a hook function, mbed::BlockDevice* get_secondary_bd(), to provide the secondary BlockDevice that mcuboot will use. The signing and encryption keys must also be provided by the user. They can be generated using the existing imgtool utility in the same manner used by Zephyr. There are no automated build steps currently provided by Mbed-OS to sign/encrypt build artifacts. Known limitations: The update candidate encryption features have not yet been fully tested. A truly secure implementation will require integration with Mbed's TRNG API in the future to inhibit side-channel attacks on the decryption process. The TinyCrypt backend is currently only supported for Mbed-OS builds when building with the GCC toolchain. The new cmake-based Mbed-OS build system will fix the underlying issue (file name uniqueness). Signed-off-by: George Beckstein <becksteing@embeddedplanet.com> Signed-off-by: Evelyne Donnaes <evelyne.donnaes@arm.com> Signed-off-by: Lingkai Dong <lingkai.dong@arm.com> Co-authored-by: Lingkai Dong <lingkai.dong@arm.com> Co-authored-by: Fabio Utzig <fabio.utzig@nordicsemi.no>
2020-10-30 05:32:11 +08:00
### Providing a secondary slot
You need to provide an instance of `mbed::BlockDevice` as the secondary slot. It can be any types of internal or external storage provided that:
* Its size equals the `"mcuboot.slot-size"` you have set
* Its minimum supported read and write sizes (granularities) are _no larger than_ 16 byte, which MCUboot's read/write operations are aligned to. If the read size is larger than _one byte_, you need to set `"mcuboot.read-granularity"` to the read size of the storage - this buffers smaller read operations.
In order for MCUboot to access your secondary slot, the interface to implement is
```cpp
mbed::BlockDevice* get_secondary_bd(void);
```
which should return an uninitialized instance of BlockDevice.
### Building the bootloader
To build a bootloader based on MCUboot, make sure `"mcuboot.bootloader-build"` is `true` (already the default) and you have provided configurations and a secondary slot BlockDevice as explained above.
### Building a user application
To build a user application, set `"mcuboot.bootloader-build"` to `false` so MCUboot is built as a _library only_ without a bootloader application. This is useful if your user application needs to confirm the current image with `boot_set_confirmed()` after an update, or set a new image in the secondary slot as pending with `boot_set_pending()` in order to trigger an update upon reboot.
As your application starts in the primary slots (instead of the beginning of the whole flash), you need to set the start address (`"target.mbed_app_start"`) to be equal to `"mcuboot.primary-slot-address"` + `"mcuboot.header-size"` of your bootloader. And its size (`"target.mbed_app_size"`) must be no larger than `"mcuboot.slot-size"` - `"mcuboot.header-size"`, and some space must be left for the image trailer too (see [this](design.md#image-trailer)).