Skip to content

Commit e612a11

Browse files
nordicjmnordicjm
committed
doc: nrf: app_dev: Add/update firmware loader details
Adds and updates existing documentation on firmware loader mode Signed-off-by: Jamie McCrae <[email protected]>
1 parent 0a4807e commit e612a11

File tree

2 files changed

+133
-69
lines changed

2 files changed

+133
-69
lines changed

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

Lines changed: 6 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -359,6 +359,8 @@ This variant image will use the same application configuration as the base image
359359
You only have to modify the version set in the :kconfig:option:`CONFIG_FW_INFO_FIRMWARE_VERSION` Kconfig option.
360360
To make ``s1_image`` bootable with |NSIB|, the value of :kconfig:option:`CONFIG_FW_INFO_FIRMWARE_VERSION` for the default image (or MCUboot if using MCUboot as a second-stage bootloader) must be bigger than the one for original image.
361361

362+
.. _ug_bootloader_using_firmware_loader_mode:
363+
362364
Using MCUboot in firmware loader mode
363365
**************************************
364366

@@ -430,21 +432,14 @@ The following is an example static Partition Manager file for the nRF53 devices:
430432
size: 0x2000
431433
region: sram_primary
432434
433-
The project must also have a ``sysbuild.cmake`` file which includes the firmware loader application in the build, this **must** be named ``firmware_loader``:
434-
435-
.. code-block:: cmake
436-
437-
ExternalZephyrProject_Add(
438-
APPLICATION firmware_loader
439-
SOURCE_DIR <path_to_firmware_loader_application>
440-
)
441-
442-
There must also be a ``sysbuild.conf`` file which selects the required sysbuild options for enabling MCUboot and selecting the firmware loader mode:
435+
The project must also configure MCUboot to operate in firmware loader mode and specify a firmware loader image in the :file:`sysbuild.conf` file.
436+
For example to select ``smp_svr``, set the following options:
443437

444438
.. code-block:: cfg
445439
446440
SB_CONFIG_BOOTLOADER_MCUBOOT=y
447441
SB_CONFIG_MCUBOOT_MODE_FIRMWARE_UPDATER=y
442+
SB_CONFIG_FIRMWARE_LOADER_IMAGE_SMP_SVR=y
448443
449444
At least one mode must be set in MCUboot for entering the firmware loader application, supported entrance methods include:
450445

@@ -460,3 +455,4 @@ For this example, the use of a GPIO when booting will be used. Create a ``sysbui
460455
CONFIG_BOOT_FIRMWARE_LOADER_ENTRANCE_GPIO=y
461456
462457
The project can now be built and flashed and will boot the firmware loader application when the button is held upon device reboot, or the main application will be booted when the device is reset and the button is not held down.
458+
See :ref:`sysbuild_images_adding_custom_firmware_loader_images` for details on how to add custom firmware loader images using sysbuild.

‎doc/nrf/app_dev/config_and_build/sysbuild/sysbuild_images.rst‎

Lines changed: 127 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,15 @@ These options determine whether the secure boot image is included on the network
5151
| ``SB_CONFIG_NETCORE_NONE`` | No network core image. |
5252
+---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+
5353

54+
The following sysbuild Kconfig options are available when MCUboot is configured in :ref:`firmware loader mode <ug_bootloader_using_firmware_loader_mode>`:
55+
These options specify the image for the firmware loader:
56+
57+
+---------------------------------------------+-----------------------------------------------+
58+
| Sysbuild Kconfig option | Description |
59+
+=============================================+===============================================+
60+
| ``SB_CONFIG_FIRMWARE_LOADER_IMAGE_SMP_SVR`` | Include ``smp_svr`` as firmware loader image. |
61+
+---------------------------------------------+-----------------------------------------------+
62+
5463
.. _sysbuild_images_adding_custom_images:
5564

5665
Adding custom images
@@ -63,35 +72,35 @@ Custom images can be added directly to a project (or board) or to a Zephyr modul
6372
Adding to a single project
6473
--------------------------
6574

66-
To add an image to a single project, you need a ``sysbuild.cmake`` file in the root folder of your project to incorporate the image into the project.
67-
If the image selection is optional, a ``Kconfig.sysbuild`` file in the root folder of your project is also required to include Kconfig options for the sysbuild configuration.
68-
If the image selection is mandatory, the ``Kconfig.sysbuild`` file can be omitted.
75+
To add an image to a single project, you need a :file:`sysbuild.cmake` file in the root folder of your project to incorporate the image into the project.
76+
If the image selection is optional, a :file:`Kconfig.sysbuild` file in the root folder of your project is also required to include Kconfig options for the sysbuild configuration.
77+
If the image selection is mandatory, the :file:`Kconfig.sysbuild` file can be omitted.
6978

7079

71-
Kconfig.sysbuild:
80+
* :file:`kconfig.sysbuild` file:
7281

73-
.. code-block:: kconfig
82+
.. code-block:: kconfig
7483
75-
config MY_APP_IMAGE_ABC
76-
bool "Include ABC image"
77-
depends on SOC_SERIES_NRF53X
78-
default y if BOARD_NRF5340DK_NRF5340_CPUAPP
79-
help
80-
Will include the ABC image in the build, which will...
84+
config MY_APP_IMAGE_ABC
85+
bool "Include ABC image"
86+
depends on SOC_SERIES_NRF53X
87+
default y if BOARD_NRF5340DK_NRF5340_CPUAPP
88+
help
89+
Will include the ABC image in the build, which will...
8190
82-
source "${ZEPHYR_BASE}/share/sysbuild/Kconfig"
91+
source "${ZEPHYR_BASE}/share/sysbuild/Kconfig"
8392
84-
sysbuild.cmake:
93+
* :file:`sysbuild.cmake` file
8594

86-
.. code-block:: cmake
95+
.. code-block:: cmake
8796
88-
if(SB_CONFIG_MY_APP_IMAGE_ABC)
89-
ExternalZephyrProject_Add(
90-
APPLICATION ABC
91-
SOURCE_DIR "<path_to_application>"
92-
BUILD_ONLY true # This will build the application and not flash it, this **must** be used when building additional images to a core (not the primary image) when using Partition Manager, as the main application for each core will flash a merged hex file instead
93-
)
94-
endif()
97+
if(SB_CONFIG_MY_APP_IMAGE_ABC)
98+
ExternalZephyrProject_Add(
99+
APPLICATION ABC
100+
SOURCE_DIR "<path_to_application>"
101+
BUILD_ONLY true # This will build the application and not flash it, this **must** be used when building additional images to a core (not the primary image) when using Partition Manager, as the main application for each core will flash a merged hex file instead
102+
)
103+
endif()
95104
96105
This method can be used to add a new image to the existing board target.
97106

@@ -103,60 +112,119 @@ Adding custom network core images
103112
To add an image for a different board target (like for the network core of the nRF5340 SoC), you must use a different syntax.
104113
This can be handled using the following approach:
105114

106-
Kconfig.sysbuild:
115+
* :file:`kconfig.sysbuild` file:
107116

108-
.. code-block:: kconfig
117+
.. code-block:: kconfig
109118
110-
menu "Network core configuration"
111-
depends on SUPPORT_NETCORE
119+
menu "Network core configuration"
120+
depends on SUPPORT_NETCORE
112121
113-
config SUPPORT_NETCORE_ABC
114-
bool
115-
default y
122+
config SUPPORT_NETCORE_ABC
123+
bool
124+
default y
116125
117-
choice NETCORE
118-
prompt "Netcore image"
119-
depends on SUPPORT_NETCORE && !EXTERNAL_CONFIGURED_NETCORE
126+
choice NETCORE
127+
prompt "Netcore image"
128+
depends on SUPPORT_NETCORE && !EXTERNAL_CONFIGURED_NETCORE
120129
121-
config NETCORE_ABC
122-
bool "ABC"
123-
help
124-
Use ABC image as the network core image.
130+
config NETCORE_ABC
131+
bool "ABC"
132+
help
133+
Use ABC image as the network core image.
125134
126-
endchoice
135+
endchoice
127136
128-
if !NETCORE_NONE
137+
if !NETCORE_NONE
129138
130-
config NETCORE_IMAGE_NAME
131-
default "abc" if NETCORE_ABC
139+
config NETCORE_IMAGE_NAME
140+
default "abc" if NETCORE_ABC
132141
133-
config NETCORE_IMAGE_PATH
134-
default "${ZEPHYR_MY_MODULE_MODULE_DIR}/<image_path>" if NETCORE_ABC
142+
config NETCORE_IMAGE_PATH
143+
default "${ZEPHYR_MY_MODULE_MODULE_DIR}/<image_path>" if NETCORE_ABC
135144
136-
endif # !NETCORE_NONE
145+
endif # !NETCORE_NONE
137146
138-
endmenu
147+
endmenu
139148
140-
source "${ZEPHYR_BASE}/share/sysbuild/Kconfig"
149+
source "${ZEPHYR_BASE}/share/sysbuild/Kconfig"
141150
142-
sysbuild.cmake:
151+
* :file:`sysbuild.cmake` file - This file is optional and should be used only if specific custom configurations are required for the application.
143152

144-
This file is optional and is only needed if custom configuration needs to be set on the application
153+
.. code-block:: cmake
145154
146-
.. code-block:: cmake
155+
if(SB_CONFIG_NETCORE_ABC)
156+
# Project can optionally be configured here if needed
147157
148-
if(SB_CONFIG_MY_APP_IMAGE_ABC)
149-
# Project can optionally be configured here if needed
150-
151-
# This will add a Kconfig fragment file, named `my_extra.conf` from the application directory
152-
add_overlay_config(${SB_CONFIG_NETCORE_IMAGE_NAME} ${SB_CONFIG_NETCORE_IMAGE_PATH}/my_extra.conf)
153-
# This will add a devicetree overlay file, named `my_extra.dts` from the application directory
154-
add_overlay_dts(${SB_CONFIG_NETCORE_IMAGE_NAME} ${SB_CONFIG_NETCORE_IMAGE_PATH}/my_extra.dts)
155-
# This will set a bool Kconfig option in the image (note: sysbuild forces this setting, it cannot be overwritten by changing the application configuration)
156-
set_config_bool(${SB_CONFIG_NETCORE_IMAGE_NAME} CONFIG_MY_CUSTOM_CONFIG y)
157-
# This will set a string (or numeric) Kconfig option in the image (note: sysbuild forces this setting, it cannot be overwritten by changing the application configuration)
158-
set_property(TARGET ${SB_CONFIG_NETCORE_IMAGE_NAME} APPEND_STRING PROPERTY CONFIG "CONFIG_CUSTOM_STRING=my_custom_value\n")
159-
endif()
158+
# This will add a Kconfig fragment file, named `my_extra.conf` from the application directory
159+
add_overlay_config(${SB_CONFIG_NETCORE_IMAGE_NAME} ${SB_CONFIG_NETCORE_IMAGE_PATH}/my_extra.conf)
160+
# This will add a devicetree overlay file, named `my_extra.dts` from the application directory
161+
add_overlay_dts(${SB_CONFIG_NETCORE_IMAGE_NAME} ${SB_CONFIG_NETCORE_IMAGE_PATH}/my_extra.dts)
162+
# This will set a bool Kconfig option in the image (note: sysbuild forces this setting, it cannot be overwritten by changing the application configuration)
163+
set_config_bool(${SB_CONFIG_NETCORE_IMAGE_NAME} CONFIG_MY_CUSTOM_CONFIG y)
164+
# This will set a string (or numeric) Kconfig option in the image (note: sysbuild forces this setting, it cannot be overwritten by changing the application configuration)
165+
set_property(TARGET ${SB_CONFIG_NETCORE_IMAGE_NAME} APPEND_STRING PROPERTY CONFIG "CONFIG_CUSTOM_STRING=my_custom_value\n")
166+
endif()
167+
168+
.. _sysbuild_images_adding_custom_firmware_loader_images:
169+
170+
Adding custom firmware loader images
171+
====================================
172+
173+
You can add custom firmware loader images similarly to how nRF5340 network core images are incorporated.
174+
This can be handled using the following approach:
175+
176+
* :file:`kconfig.sysbuild` file:
177+
178+
.. code-block:: kconfig
179+
180+
menu "Firmware loader configuration"
181+
depends on MCUBOOT_MODE_FIRMWARE_UPDATER
182+
183+
config SUPPORT_FIRMWARE_LOADER_ABC
184+
bool
185+
default y
186+
187+
choice FIRMWARE_LOADER
188+
prompt "Firmware loader image"
189+
depends on MCUBOOT_MODE_FIRMWARE_UPDATER
190+
191+
config FIRMWARE_LOADER_IMAGE_ABC
192+
bool "ABC"
193+
help
194+
Use ABC image as the firmware loader image.
195+
196+
endchoice
197+
198+
if !FIRMWARE_LOADER_IMAGE_NONE
199+
200+
config FIRMWARE_LOADER_IMAGE_NAME
201+
default "abc" if FIRMWARE_LOADER_IMAGE_ABC
202+
203+
config FIRMWARE_LOADER_IMAGE_PATH
204+
default "${ZEPHYR_MY_MODULE_MODULE_DIR}/<image_path>" if FIRMWARE_LOADER_IMAGE_ABC
205+
206+
endif # !FIRMWARE_LOADER_IMAGE_NONE
207+
208+
endmenu
209+
210+
source "${ZEPHYR_BASE}/share/sysbuild/Kconfig"
211+
212+
* :file:`sysbuild.cmake` file - This file is optional and should be used only if specific custom configurations are required for the application.
213+
214+
.. code-block:: cmake
215+
216+
if(SB_CONFIG_FIRMWARE_LOADER_IMAGE_ABC)
217+
# Project can optionally be configured here if needed
218+
219+
# This will add a Kconfig fragment file, named `my_extra.conf` from the application directory
220+
add_overlay_config(${SB_CONFIG_FIRMWARE_LOADER_IMAGE_NAME} ${SB_CONFIG_FIRMWARE_LOADER_IMAGE_PATH}/my_extra.conf)
221+
# This will add a devicetree overlay file, named `my_extra.dts` from the application directory
222+
add_overlay_dts(${SB_CONFIG_FIRMWARE_LOADER_IMAGE_NAME} ${SB_CONFIG_FIRMWARE_LOADER_IMAGE_PATH}/my_extra.dts)
223+
# This will set a bool Kconfig option in the image (note: sysbuild forces this setting, it cannot be overwritten by changing the application configuration)
224+
set_config_bool(${SB_CONFIG_FIRMWARE_LOADER_IMAGE_NAME} CONFIG_MY_CUSTOM_CONFIG y)
225+
# This will set a string (or numeric) Kconfig option in the image (note: sysbuild forces this setting, it cannot be overwritten by changing the application configuration)
226+
set_property(TARGET ${SB_CONFIG_FIRMWARE_LOADER_IMAGE_NAME} APPEND_STRING PROPERTY CONFIG "CONFIG_CUSTOM_STRING=my_custom_value\n")
227+
endif()
160228
161229
.. _sysbuild_images_adding_to_a_single_board:
162230

0 commit comments

Comments
 (0)