docs: add nxboot documentation entry
This commit adds documentation entry for NuttX based bootloader nxboot. Signed-off-by: Michal Lenc <michallenc@seznam.cz>
This commit is contained in:
Michal Lenc
Alan C. Assis
parent
3818ce8268
commit
9930a64de7
|
|
@ -0,0 +1,272 @@
|
||||||
|
===========================
|
||||||
|
``nxboot`` NuttX Bootloader
|
||||||
|
===========================
|
||||||
|
|
||||||
|
NuttX Bootloader (nxboot) can be used to provide update and recovery
|
||||||
|
capabilities for NuttX based devices. The bootloader implements an
|
||||||
|
algorithm that uses three partitions/areas: primary, secondary and
|
||||||
|
tertiary. Primary area is used to run the image and thus is usually
|
||||||
|
located in program memory. Secondary and tertiary areas are used
|
||||||
|
to store update image or recovery image and can be located on
|
||||||
|
external flash memory for example.
|
||||||
|
|
||||||
|
Please note that this bootloader is new and it is possible some of its
|
||||||
|
characteristics might be changed/enhanced/fix as it is further used and
|
||||||
|
tested. These might include slight changes in API and image format.
|
||||||
|
|
||||||
|
Algorithm Description
|
||||||
|
---------------------
|
||||||
|
|
||||||
|
The update is performed with a simple copy from update area to primary
|
||||||
|
area with recovery being created in recovery area if not already present.
|
||||||
|
Once image is confirmed by the user, the image in update area is
|
||||||
|
confirmed as well, update area becomes recovery area and vice versa.
|
||||||
|
This means the recovery is always present (except for the first update)
|
||||||
|
and subsequent updates just copy image from update to primary. This
|
||||||
|
makes the update significantly faster and more considerable to flash
|
||||||
|
wear while keeping the recovery/revert possibility.
|
||||||
|
|
||||||
|
Not confirmed image is reverted to recovery image if reboot occurs.
|
||||||
|
|
||||||
|
The bootable image consists of a header :c:struct:`nxboot_img_header`
|
||||||
|
containing magic, size of the image excluding the header, CRC32 of the
|
||||||
|
image excluding the header and firmware version. The header is located
|
||||||
|
prior to the image itself and has a configurable size
|
||||||
|
``CONFIG_NXBOOT_HEADER_SIZE``. One erase page is also reserved at the
|
||||||
|
end of the partition (the entire partition, not the image!). This page
|
||||||
|
has two write blocks/pages with each one holding a flag. The first page
|
||||||
|
from the end holds image confirmation flag, the second one holds the flag
|
||||||
|
informing this image was already updated. These flags are written by the
|
||||||
|
bootloader and are used to detect which partition is update/recovery
|
||||||
|
and whether the image is confirmed or not.
|
||||||
|
|
||||||
|
There are two variants of bootable image. The first is the image that is
|
||||||
|
expected to be flashed directly into the primary area via physical programmer
|
||||||
|
as STlink or JTAG. This image does not use CRC32 for validation and does
|
||||||
|
not contain tail with the flags described above. It has an inverted
|
||||||
|
magic value compared to the update image. This should not be used
|
||||||
|
for OTA update, but only for the initial upload of the software to the
|
||||||
|
device.
|
||||||
|
|
||||||
|
The update image has a valid precalculated CRC32 and standard magic value.
|
||||||
|
The image is expected to be uploaded to the board either via programmer
|
||||||
|
or some protocol (Ethernet, CAN, etc.) to the external flash. The primary
|
||||||
|
flash can be used as well, but this halts the program execution during write
|
||||||
|
operations, so it is not recommended if external flash can be used. The
|
||||||
|
uploaded image is detected by the bootloader during the next boot and update
|
||||||
|
occurs. The program responsible for uploading the update image to the
|
||||||
|
partition has to erase the last erase page in this partition to ensure
|
||||||
|
all flags are unset.
|
||||||
|
|
||||||
|
The application can use function :c:func:`nxboot_get_state` to determine
|
||||||
|
what partition is update and recovery and thus where the update image
|
||||||
|
should be stored.
|
||||||
|
|
||||||
|
Hardware Requirements
|
||||||
|
---------------------
|
||||||
|
|
||||||
|
As mentioned above, the bootlaoder utilizes three partitions with the
|
||||||
|
first one typically located in program flash.
|
||||||
|
|
||||||
|
The bootloader itself requires the minimal knowledge about characteristics
|
||||||
|
of the underlying storage device. This is achieved by means of the ``BCH``
|
||||||
|
and ``FTL`` subsystems, which enable the bootloader to manage MTD partitions
|
||||||
|
via character device drivers using standard POSIX filesystem operations
|
||||||
|
(e.g. ``open()`` / ``close()`` / ``read()`` / ``write()``).
|
||||||
|
|
||||||
|
It is currently required to access the partitions via mentioned ``BCH``
|
||||||
|
and ``FTL`` subsystems, but future enhancement could provide a direct access
|
||||||
|
with ``MTD`` layer.
|
||||||
|
|
||||||
|
Configuration
|
||||||
|
-------------
|
||||||
|
|
||||||
|
Following configuration options are available:
|
||||||
|
|
||||||
|
- ``CONFIG_BOOT_NXBOOT``: Enables NuttX Bootloader build.
|
||||||
|
- ``CONFIG_NXBOOT_PRIMARY_SLOT_PATH``:
|
||||||
|
The path to the application firmware image primary slot character
|
||||||
|
device driver. The image runs from this location. Default is ``dev/ota0``.
|
||||||
|
- ``CONFIG_NXBOOT_SECONDARY_SLOT_PATH``:
|
||||||
|
The path to the application firmware image primary slot character device
|
||||||
|
driver. This is either update or recovery slot.. Default is ``dev/ota1``.
|
||||||
|
- ``CONFIG_NXBOOT_TERTIARY_SLOT_PATH``:
|
||||||
|
The path to the application firmware image primary slot character device
|
||||||
|
driver. This is either update or recovery slot.. Default is ``dev/ota2``.
|
||||||
|
- ``CONFIG_NXBOOT_HEADER_SIZE``:
|
||||||
|
Size of the image header. Note that this size should be aligned with the
|
||||||
|
program memory write page size!
|
||||||
|
- ``CONFIG_NXBOOT_BOOTLOADER``:
|
||||||
|
This option builds and links a bootloader application. This application
|
||||||
|
should be an entry function for NuttX. It checks for possible
|
||||||
|
update/revert operation, performs it and boot the correct image.
|
||||||
|
- ``CONFIG_NXBOOT_SWRESET_ONLY``:
|
||||||
|
This option ensures the update/revert is performed only for software
|
||||||
|
reset. This way the board can keep its image (even if not confirmed)
|
||||||
|
during for example power shutdown and perform update/revert only if
|
||||||
|
expected based on user/maintainer input. Following reset causes
|
||||||
|
are considered as software resets.
|
||||||
|
|
||||||
|
``BOARDIOC_RESETCAUSE_CPU_SOFT``: software reset
|
||||||
|
|
||||||
|
``BOARDIOC_RESETCAUSE_CPU_RWDT``: watchdog error
|
||||||
|
|
||||||
|
``BOARDIOC_RESETCAUSE_PIN``: reset button
|
||||||
|
|
||||||
|
- ``NXBOOT_PREVENT_DOWNGRADE`` :
|
||||||
|
NXboot uses Semantic Version 2.0.0 (without build metadata). By default,
|
||||||
|
the update is performed for every version that doesn't match the
|
||||||
|
currently running one. If NXBOOT_PREVENT_DOWNGRADE selected, update is
|
||||||
|
performed only for newer versions (according to Semantic Version
|
||||||
|
preference rules).
|
||||||
|
|
||||||
|
``WARNING``: NXboot currently implements preferences only for
|
||||||
|
``MAJOR.MINOR.PATCH`` and ignores prerelease.
|
||||||
|
|
||||||
|
Image Creation
|
||||||
|
--------------
|
||||||
|
|
||||||
|
The image intended to be booted by nxboot bootlaoder must have prepended header
|
||||||
|
to be recognized and worked with correctly. A Python script ``nximage.py``
|
||||||
|
located in ``apps/boot/nxboot/tools`` directory can be used to generate
|
||||||
|
nxboot compatible image.
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
python3 apps/boot/nxboot/tools/nximage.py \
|
||||||
|
--version "VERSION" \
|
||||||
|
--header_size CONFIG_NXBOOT_HEADER_SIZE \
|
||||||
|
--primary \
|
||||||
|
nuttx.bin image.img
|
||||||
|
|
||||||
|
It takes input parameters ``--version`` with your image's version and
|
||||||
|
``--header_size`` with the configured size of the header. Option
|
||||||
|
``--primary`` generates the primary. This option should be used only
|
||||||
|
for image intended to be flashed directly to program memory (with
|
||||||
|
flashing tool like STlink). It must not be set for image intended to be used
|
||||||
|
as update image. The input file is a binary ``nuttx.bin``, output with added
|
||||||
|
header is ``image.img``.
|
||||||
|
|
||||||
|
Image version adheres to `Semantic Versioning 2.0.0 <https://semver.org/spec/v2.0.0.html>`__
|
||||||
|
without the usage of build metadata. The used format is
|
||||||
|
MAJOR.MINOR:PATCH-prerelease. The image version is important for the update
|
||||||
|
to occur as the bootloader automatically rejects update firmware that
|
||||||
|
has the same version as the already running firmware.
|
||||||
|
Configuration options:
|
||||||
|
|
||||||
|
Public API
|
||||||
|
----------
|
||||||
|
|
||||||
|
Enabling ``CONFIG_BOOT_NXBOOT`` option provides following NXboot API.
|
||||||
|
|
||||||
|
.. code-block:: c
|
||||||
|
|
||||||
|
#include <nxboot.h>
|
||||||
|
|
||||||
|
.. c:struct:: nxboot_img_version
|
||||||
|
.. code-block:: c
|
||||||
|
|
||||||
|
#define NXBOOT_HEADER_PRERELEASE_MAXLEN 110
|
||||||
|
|
||||||
|
struct nxboot_img_version
|
||||||
|
{
|
||||||
|
/* MAJOR version */
|
||||||
|
uint16_t major;
|
||||||
|
/* MINOR version */
|
||||||
|
uint16_t minor;
|
||||||
|
/* PATCH version */
|
||||||
|
uint16_t patch;
|
||||||
|
/* Additional pre-release version */
|
||||||
|
char pre_release[NXBOOT_HEADER_PRERELEASE_MAXLEN];
|
||||||
|
};
|
||||||
|
|
||||||
|
.. c:struct:: nxboot_img_header
|
||||||
|
.. code-block:: c
|
||||||
|
|
||||||
|
#define NXBOOT_HEADER_MAGIC 0x534f584e
|
||||||
|
#define NXBOOT_HEADER_MAGIC_INV 0xaca0abb1
|
||||||
|
|
||||||
|
struct nxboot_img_header
|
||||||
|
{
|
||||||
|
/* Header magic */
|
||||||
|
uint32_t magic;
|
||||||
|
/* Image size (excluding the header) */
|
||||||
|
uint32_t size;
|
||||||
|
/* CRC32 of image (excluding the header) */
|
||||||
|
uint32_t crc32;
|
||||||
|
/* Image version */
|
||||||
|
struct nxboot_img_version img_version;
|
||||||
|
};
|
||||||
|
|
||||||
|
.. c:enum:: nxboot_update_type
|
||||||
|
.. code-block:: c
|
||||||
|
|
||||||
|
enum nxboot_update_type
|
||||||
|
{
|
||||||
|
/* No action to do */
|
||||||
|
NXBOOT_UPDATE_TYPE_NONE = 0,
|
||||||
|
/* Update will take place upon reboot */
|
||||||
|
NXBOOT_UPDATE_TYPE_UPDATE = 1,
|
||||||
|
/* Revert will take place upon reboot */
|
||||||
|
NXBOOT_UPDATE_TYPE_REVERT = 2,
|
||||||
|
};
|
||||||
|
|
||||||
|
.. c:struct:: nxboot_state
|
||||||
|
.. code-block:: c
|
||||||
|
|
||||||
|
#define NXBOOT_PRIMARY_SLOT_NUM 0
|
||||||
|
#define NXBOOT_SECONDARY_SLOT_NUM 1
|
||||||
|
#define NXBOOT_TERTIARY_SLOT_NUM 2
|
||||||
|
|
||||||
|
struct nxboot_state
|
||||||
|
{
|
||||||
|
/* Number of update slot */
|
||||||
|
int update;
|
||||||
|
/* Number of recovery slot */
|
||||||
|
int recovery;
|
||||||
|
/* True if recovery image contains valid recovery */
|
||||||
|
bool recovery_valid;
|
||||||
|
/* True if primary slot is confirmed */
|
||||||
|
bool primary_confirmed;
|
||||||
|
/* True if update slot has a valid image */
|
||||||
|
enum nxboot_update_type next_boot;
|
||||||
|
};
|
||||||
|
|
||||||
|
.. c:function:: int nxboot_get_state(struct nxboot_state *state)
|
||||||
|
|
||||||
|
This function can be used to determine whether primary image is
|
||||||
|
confirmed or not. This provides more direct access to confirm
|
||||||
|
state compared to nxboot_get_state function that returns the full
|
||||||
|
state of the bootloader.
|
||||||
|
|
||||||
|
:param state: A pointer to ``struct nxboot_state`` structure.
|
||||||
|
|
||||||
|
:return: 0 on success, -1 and sets errno on failure.
|
||||||
|
|
||||||
|
.. c:function:: int nxboot_get_confirm(void)
|
||||||
|
|
||||||
|
Confirms the image currently located in primary partition and marks
|
||||||
|
its copy in update partition as a recovery.
|
||||||
|
|
||||||
|
:return: 1 means confirmed, 0 not confirmed, -1 and sets errno on failure.
|
||||||
|
|
||||||
|
.. c:function:: int nxboot_confirm(void)
|
||||||
|
|
||||||
|
Confirms the image currently located in primary partition and marks
|
||||||
|
its copy in update partition as a recovery.
|
||||||
|
|
||||||
|
:return: 0 on success, -1 and sets errno on failure.
|
||||||
|
|
||||||
|
.. c:function:: int nxboot_perform_update(bool check_only)
|
||||||
|
|
||||||
|
Checks for the possible firmware update and performs it by copying
|
||||||
|
update image to primary slot or recovery image to primary slot in case
|
||||||
|
of the revert. In any situation, this function ends with the valid
|
||||||
|
image in primary slot.
|
||||||
|
|
||||||
|
This is an entry point function that should be called from the
|
||||||
|
bootloader application.
|
||||||
|
|
||||||
|
:param check_only: Only repairs corrupted update.
|
||||||
|
|
||||||
|
:return: 0 on success, -1 and sets errno on failure.
|
||||||
Loading…
Reference in New Issue