afefa1c308
The current examples belongs to 'examples/mcuboot' directory. This moves related example code and Kconfig entries to their respective project inside examples/mcuboot directory. It cleans all Kconfig entries at 'boot/mcuboot', including Kconfig, Makefile and README.md files. This not perform any code modification. Signed-off-by: Gerson Fernando Budke <gerson.budke@ossystems.com.br>
55 lines
5.3 KiB
Markdown
55 lines
5.3 KiB
Markdown
# Boot / `mcuboot` MCUboot
|
|
|
|
## Description
|
|
|
|
The NuttX port of MCUboot secure boot library expects that the platform provides a Flash storage with the following partitions:
|
|
- `CONFIG_MCUBOOT_PRIMARY_SLOT_PATH`: MTD partition for the application firmware image PRIMARY slot;
|
|
- `CONFIG_MCUBOOT_SECONDARY_SLOT_PATH`: MTD partition for the application firmware image SECONDARY slot;
|
|
- `CONFIG_MCUBOOT_SCRATCH_PATH`: MTD partition for the Scratch area;
|
|
|
|
Also, these are optional features that may be enabled:
|
|
|
|
- `CONFIG_MCUBOOT_WATCHDOG`: If `CONFIG_WATCHDOG` is enabled, MCUboot shall reset the watchdog timer indicated by `CONFIG_MCUBOOT_WATCHDOG_DEVPATH` to the current timeout value, preventing any imminent watchdog timeouts.
|
|
|
|
The porting layer of MCUboot library consists of the following interfaces:
|
|
- `<flash_map_backend/flash_map_backend.h>`, for enabling MCUboot to manage the application firmware image slots in the device storage.
|
|
- `<mcuboot_config/mcuboot_config.h>`, for configuration of MCUboot's features.
|
|
- `<mcuboot_config/mcuboot_logging.h>`, for providing logging capabilities.
|
|
- `<os/os_malloc.h>`, for providing MCUboot access to the OS memory management interfaces.
|
|
- `<sysflash/sysflash.h>`, for configuration of the system's flash area organization.
|
|
|
|
The NuttX port of MCUboot is implemented at application-level and requires minimal knowledge about characteristics of the underlying storage device. This is achieved by means of the `BCH` and `FTL` subsystems, which enable MCUboot to manage MTD partitions via character device drivers using standard POSIX filesystem operations (e.g. `open()` / `close()` / `read()` / `write()`).
|
|
|
|
## Creating MCUboot-compatible application firmware images
|
|
|
|
One common use case for MCUboot is to integrate it to a firmware update agent, which is an important component of a secure firmware update subsystem. Through MCUboot APIs an application is able to install a newly received application firmware image and, once this application firmware image is assured to be valid, the application may confirm it as a stable image. In case that application firmware image is deemed bogus, MCUboot provides an API for invalidating that update, which will induce a rollback procedure to the most recent stable application firmware image.
|
|
|
|
The `CONFIG_EXAMPLES_MCUBOOT_UPDATE_AGENT` example demonstrates this workflow by downloading an application firmware image from a webserver, installing it and triggering the firmware update process for the next boot after a system reset. There is also the `CONFIG_EXAMPLES_MCUBOOT_SLOT_CONFIRM`, which is a fairly simple example that just calls an MCUboot API for confirming the executing application firmware image as stable.
|
|
|
|
For more information about all MCUboot examples, see `examples/mcuboot` directory.
|
|
|
|
## Using MCUboot on NuttX as a secure boot solution
|
|
|
|
NuttX port for MCUboot also enables the creation of a secure bootloader application requiring minimal platform-specific implementation. The logical implementation for the secure boot is performed at application-level by the MCUboot library. Once MCUboot validates the application firmware image, it delegates the loading and execution of the application firmware image to a platform-specific routine, which is accessed via `boardctl(BOARDIOC_BOOT_IMAGE)` call. Each platform must then provide an implementation for the `board_boot_image()` for executing the required actions in order to boot a new application firmware image (e.g. deinitialize peripherals, load the Program Counter register with the application firmware image entry point address).
|
|
|
|
The MCUboot bootloader application may be enabled by selecting the `CONFIG_MCUBOOT_BOOTLOADER` option.
|
|
|
|
## Assumptions
|
|
|
|
### IOCTL MTD commands
|
|
|
|
The implementation of `<flash_map_backend/flash_map_backend.h>` expects that the MTD driver for a given image partition handles the following `ioctl` commands:
|
|
- `MTDIOC_GEOMETRY`, for retrieving information about the geometry of the MTD, required for the configuration of the size of each flash area.
|
|
- `MTDIOC_ERASESTATE`, for retrieving the byte value of an erased cell of the MTD, required for the implementation of `flash_area_erased_val()` interface.
|
|
|
|
### Write access alignment
|
|
|
|
Through `flash_area_align()` interface MCUboot expects that the implementation provides the shortest data length that may be written via `flash_area_write()` interface. The NuttX implementation passes through the `BCH` and `FTL` layers, which appropriately handle the write alignment restrictions of the underlying MTD. So The NuttX implementation of `flash_area_align()` is able to return a fixed value of 1 byte, even if the MTD does not support byte operations.
|
|
|
|
## Limitations
|
|
|
|
### `<flash_map_backend/flash_map_backend.h>` functions are not multitasking-safe
|
|
|
|
MCUboot's documentation imposes no restrictions regarding the usage of its public interfaces, which doesn't mean they are thread-safe.
|
|
But, regarding NuttX implementation of the `<flash_map_backend/flash_map_backend.h>`, it is safe to state that they are **not** multitasking-safe. NuttX implementation manages the MTD partitions via character device drivers. As file-descriptors cannot be shared between different tasks, if one task calls `flash_area_open` and another task calls `flash_area_<read/write/close>` passing the same `struct flash_area` instance, it will result in failure.
|