diff --git a/Documentation/applications/boot/index.rst b/Documentation/applications/boot/index.rst index e4539c1015f..d70a419ac64 100644 --- a/Documentation/applications/boot/index.rst +++ b/Documentation/applications/boot/index.rst @@ -1,3 +1,10 @@ ==================== Bootloader Utilities ==================== + +.. toctree:: + :glob: + :maxdepth: 3 + :titlesonly: + + */* diff --git a/Documentation/applications/boot/mcuboot/index.rst b/Documentation/applications/boot/mcuboot/index.rst new file mode 100644 index 00000000000..761f741b92f --- /dev/null +++ b/Documentation/applications/boot/mcuboot/index.rst @@ -0,0 +1,109 @@ +======= +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: + +- ````, for enabling MCUboot to manage + the application firmware image slots in the device storage. +- ````, for configuration of MCUboot's features. +- ````, for providing logging capabilities. +- ````, for providing MCUboot access to the OS memory management interfaces. +- ````, 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 ```` 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 +----------- + +```` 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 ````, 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_`` +passing the same ``struct flash_area`` instance, it will result in failure. diff --git a/Documentation/applications/boot/miniboot/index.rst b/Documentation/applications/boot/miniboot/index.rst new file mode 100644 index 00000000000..084fecda0b5 --- /dev/null +++ b/Documentation/applications/boot/miniboot/index.rst @@ -0,0 +1,11 @@ +======== +miniboot +======== + +Minimal bootloader based on NuttX. + +Configuration options: + +- ``CONFIG_MINIBOOT_SLOT_PATH`` - The path to the application firmware image + slot character device driver. Default: ``/dev/ota0`` +- ``CONFIG_MINIBOOT_HEADER_SIZE`` - Application firmware image header size