Skip to content

Commit a3703bb

Browse files
nvlsianpunvlsianpu
committed
doc/nrf/mcuboot_nsib: Add page on main MCUboot's Kconfig
Added page which describes bare-minimum of Major's configuration details of MCUboot. Ref.: NCSDK-32409, NCSDK-29716, NCSIDB-1373, NCSIDB-1373 Signed-off-by: Andrzej Puzdrowski <[email protected]> Signed-off-by: Anna Wojdylo <[email protected]>
1 parent 96410d6 commit a3703bb

File tree

2 files changed

+152
-0
lines changed

2 files changed

+152
-0
lines changed

‎doc/nrf/app_dev/bootloaders_dfu/mcuboot_nsib/bootloader_main_config.rst‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
.. _ug_bootloader_main_config:
2+
3+
Essential MCUboot configuration items
4+
#####################################
5+
6+
.. contents::
7+
:local:
8+
:depth: 2
9+
10+
The following page provides an overview of the key configuration items necessary for understanding and configuring MCUboot's behavior.
11+
The :ref:`sysbuild` Kconfig options generally override the MCUboot's Kconfig option.
12+
Sysbuild options aim to establish a coherent environment for the entire system, while MCUboot options focus specifically on the bootloader.
13+
This means that many sysbuild options configure the MCUboot, the application, and the build system settings to ensure compatibility.
14+
15+
Supported image configurations
16+
******************************
17+
18+
MCUboot primarily functions as a dual-bank bootloader, managing one bank as the executable and the other as an upgrade candidate or an alternative executable.
19+
In MCUboot terminology, *image* refers to a specific type of executable code, typically the application image.
20+
In the dual-bank scheme, two banks (or slots) are associated with each image.
21+
22+
MCUboot can be configured to support multiple images, enabling it to operate as an enhanced dual-bank bootloader.
23+
This configuration allows for more complex update scenarios and greater flexibility in managing different sets of firmware:
24+
25+
* ``CONFIG_UPDATEABLE_IMAGE_NUMBER`` - Specifies the number of images that MCUboot can handle.
26+
* :kconfig:option:`SB_CONFIG_MCUBOOT_UPDATEABLE_IMAGES` - Configures the number of images supported by MCUboot at the sysbuild level.
27+
28+
Operational modes of MCUboot
29+
****************************
30+
31+
MCUboot supports various operational modes that dictate its behavior towards the application images it manages.
32+
The choice of mode determines the specific scheme of the bootloader's operations for the images supported by a given MCUboot instance:
33+
34+
.. list-table:: MCUboot modes
35+
:header-rows: 1
36+
:widths: auto
37+
38+
* - **Mode name**
39+
- **Description**
40+
- **MCUboot Kconfig option**
41+
- **Sysbuild Kconfig option**
42+
- **Multiple images**
43+
* - Swap using scratch
44+
- Implements a dual-bank image swapping algorithm utilizing a scratch area, accommodating memories with varying erase block sizes.
45+
- ``CONFIG_BOOT_SWAP_USING_OFFSET``
46+
- :kconfig:option:`SB_CONFIG_MCUBOOT_MODE_SWAP_SCRATCH`
47+
- Yes
48+
* - Swap using move
49+
- Executes a dual-bank image swapping algorithm by moving sectors, offering greater efficiency than scratch-based swaps, suitable only for memories with consistent erase block sizes.
50+
- ``CONFIG_BOOT_SWAP_USING_MOVE``
51+
- :kconfig:option:`SB_CONFIG_BOOT_SWAP_USING_MOVE`
52+
- Yes
53+
* - Swap using offset
54+
- Introduces a new dual-bank image swapping algorithm that moves sectors with optimizations for enhanced speed, applicable to memories with uniform erase block sizes.
55+
- ``CONFIG_BOOT_SWAP_USING_OFFSET``
56+
- --
57+
- Yes
58+
* - Overwrite
59+
- Employs a straightforward dual-bank image overwrite algorithm that directly replaces the image.
60+
- ``CONFIG_BOOT_UPGRADE_ONLY``
61+
- :kconfig:option:`SB_CONFIG_BOOT_UPGRADE_ONLY`
62+
- Yes
63+
* - Direct-XIP
64+
- Facilitates dual-bank image execution directly from storage, updating by uploading a new image to an alternate bank, eliminating the need for swapping or overwriting NVM.
65+
- ``CONFIG_BOOT_DIRECT_XIP``
66+
- :kconfig:option:`SB_CONFIG_BOOT_DIRECT_XIP`
67+
- Yes
68+
* - Direct-XIP with revert
69+
- Enables dual-bank image execution directly from storage with additional support for reverting to a previous image if necessary, enhancing system reliability.
70+
- ``CONFIG_MCUBOOT_MODE_DIRECT_XIP_WITH_REVERT``
71+
- :kconfig:option:`SB_CONFIG_MCUBOOT_MODE_DIRECT_XIP_WITH_REVERT`
72+
- Yes
73+
* - Firmware loader
74+
- Provides a dual-bank image firmware loading mode that allows dynamic selection of the image bank for booting the application, accommodating banks of different sizes.
75+
- ``SB_CONFIG_MCUBOOT_MODE_FIRMWARE_LOADER``
76+
- :kconfig:option:`SB_CONFIG_MCUBOOT_MODE_FIRMWARE_UPDATER`
77+
- No
78+
* - Single application
79+
- Supports a single application image mode, utilized when only one application image is necessary and dual-bank operations are not required.
80+
- ``CONFIG_MCUBOOT_MODE_SINGLE_APP``
81+
- :kconfig:option:`SB_CONFIG_MCUBOOT_MODE_SINGLE_APP`
82+
- No
83+
84+
Signature types
85+
***************
86+
87+
MCUboot supports various signature types.
88+
The signature type specifies the algorithm used to sign the image.
89+
You can calculate each signature on a hash of the image, prepared by MCUboot (referred to as pre-hash signatures).
90+
Notably, the Ed25519 signature can also be directly calculated on the image itself.
91+
92+
.. list-table:: MCUboot signature types
93+
:header-rows: 1
94+
:widths: auto
95+
96+
* - **Signature**
97+
- **Description**
98+
- **MCUboot Kconfig option**
99+
- **Sysbuild Kconfig option**
100+
- **Signed material**
101+
* - RSA
102+
- Utilizes RSA for digital signatures, supporting key sizes of 2048 and 3072 bits.
103+
- ``CONFIG_BOOT_SIGNATURE_TYPE_RSA``, ``CONFIG_BOOT_SIGNATURE_TYPE_RSA_LEN``
104+
- :kconfig:option:`SB_CONFIG_BOOT_SIGNATURE_TYPE_RSA`
105+
- Image hash
106+
* - ECDSA P-256
107+
- Employs the elliptic curve digital signature algorithm using the P-256 curve for enhanced security.
108+
- ``CONFIG_BOOT_SIGNATURE_TYPE_ECDSA_P256``
109+
- :kconfig:option:`SB_CONFIG_BOOT_SIGNATURE_TYPE_ECDSA_P256`
110+
- Image hash
111+
* - Ed25519
112+
- Uses the Edwards curve digital signature algorithm with Ed25519.
113+
- ``CONFIG_BOOT_SIGNATURE_TYPE_ED25519``
114+
- :kconfig:option:`SB_CONFIG_BOOT_SIGNATURE_TYPE_ED25519`
115+
- Image hash, image itself (pure Ed25519)
116+
* - None
117+
- Indicates the absence of a signature; the image is unchecked but its hash is verified for integrity.
118+
- ``CONFIG_BOOT_SIGNATURE_TYPE_NONE``
119+
- :kconfig:option:`SB_CONFIG_BOOT_SIGNATURE_TYPE_NONE`
120+
- Not applicable
121+
122+
MCUboot image hash algorithms
123+
*****************************
124+
125+
MCUboot supports several hash algorithms to calculate the integrity of the image hash.
126+
Typically, the default hash algorithm is sufficient for most applications, as MCUboot selects the most relevant one based on the system configuration.
127+
However, you can customize it to meet specific requirements.
128+
129+
.. list-table:: MCUboot image hash algorithms
130+
:header-rows: 1
131+
:widths: auto
132+
133+
* - **Hash**
134+
- **MCUboot Kconfig option**
135+
- **Comments**
136+
* - SHA-256
137+
- ``CONFIG_BOOT_HASH_ALG_SHA256``
138+
- The default hash. Compatible with all pre-hash signature types.
139+
* - SHA-384
140+
- ``CONFIG_BOOT_HASH_ALG_SHA384``
141+
- Currently not utilized by |NCS|.
142+
* - SHA-512
143+
- ``CONFIG_BOOT_HASH_ALG_SHA512``
144+
- Restricted to use with Ed25519 signatures.
145+
146+
MCUboot recovery protocol
147+
*************************
148+
149+
Mcuboot supports serial recovery protocols compatible with :ref:`MCUmgr <dfu_tools_mcumgr_cli>`, enabling device programming via serial connection instead of J-Link.
150+
This feature allows direct upload of applications to the executable image bank and, depending on configuration, to other banks as well.
151+
To use this feature, enable the ``CONFIG_MCUBOOT_SERIAL`` Kconfig option.

‎doc/nrf/app_dev/bootloaders_dfu/mcuboot_nsib/bootloader_mcuboot_nsib.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ Following that, you can :ref:`add an immutable bootloader<ug_bootloader_adding_s
2020
bootloader_quick_start
2121
bootloader_adding_sysbuild
2222
bootloader
23+
bootloader_main_config
2324
bootloader_partitioning
2425
bootloader_dfu_image_versions
2526
bootloader_config

0 commit comments

Comments
 (0)