Documentation: migrate apps/boot doc
This commit is contained in:
raiden00pl
Xiang Xiao
parent
131f4151b7
commit
61359f7fcc
@ -1,3 +1,10 @@
|
||||
====================
|
||||
Bootloader Utilities
|
||||
====================
|
||||
|
||||
.. toctree::
|
||||
:glob:
|
||||
:maxdepth: 3
|
||||
:titlesonly:
|
||||
|
||||
*/*
|
||||
|
||||
109
Documentation/applications/boot/mcuboot/index.rst
Normal file
109
Documentation/applications/boot/mcuboot/index.rst
Normal file
@ -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:
|
||||
|
||||
- ``<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.
|
||||
11
Documentation/applications/boot/miniboot/index.rst
Normal file
11
Documentation/applications/boot/miniboot/index.rst
Normal file
@ -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
|
||||
Loading…
x
Reference in New Issue
Block a user