Skip to content

Commit ff92cd5

Browse files
ahasztagahasztag
committed
sysbuild: Add support for FW loader updates
This commit adds support for FW loader updates, using a dedicated unboxer application. Signed-off-by: Artur Hadasz <artur.hadasz@nordicsemi.no>
1 parent bf767db commit ff92cd5

16 files changed

Lines changed: 978 additions & 6 deletions

‎CODEOWNERS‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,8 @@
4545
/applications/matter_weather_station/*.rst @nrfconnect/ncs-matter-doc
4646
/applications/nrf5340_audio/**/*.rst @nrfconnect/ncs-audio-doc
4747
/applications/nrf_desktop/**/*.rst @nrfconnect/ncs-si-xcake-doc
48+
/applications/unboxer/ @nrfconnect/ncs-eris
49+
/applications/unboxer/**/*.rst @nrfconnect/ncs-eris-doc
4850

4951
# Boards
5052
/boards/nordic/nrf54l*/ @nrfconnect/ncs-co-boards @kl-cruz

‎applications/unboxer/CMakeLists.txt‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
#
2+
# Copyright (c) 2026 Nordic Semiconductor
3+
#
4+
# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
5+
#
6+
7+
cmake_minimum_required(VERSION 3.20.0)
8+
9+
find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
10+
project(unboxer)
11+
12+
target_sources(app PRIVATE src/main.c)
13+
14+
target_include_directories(app PRIVATE
15+
${ZEPHYR_MCUBOOT_MODULE_DIR}/boot/bootutil/include
16+
${ZEPHYR_MCUBOOT_MODULE_DIR}/boot/zephyr/include
17+
)
18+
19+
if(CONFIG_UNBOXER_FW_LOADER_ENTRANCE_BOOT_REQ)
20+
zephyr_library_link_libraries(MCUBOOT_BOOTUTIL)
21+
endif()

‎applications/unboxer/Kconfig‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
#
2+
# Copyright (c) 2026 Nordic Semiconductor
3+
#
4+
# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
5+
#
6+
7+
module = UNBOXER
8+
module-str = unboxer
9+
source "subsys/logging/Kconfig.template.log_config"
10+
11+
choice UNBOXER_FW_LOADER_ENTRANCE_METHOD
12+
prompt "Method which the unboxer uses to request firmware loader entrance"
13+
default UNBOXER_FW_LOADER_ENTRANCE_SELF_INVALIDATE_BY_ERASE
14+
help
15+
Select the method which the unboxer uses to request firmware loader entrance.
16+
17+
config UNBOXER_FW_LOADER_ENTRANCE_SELF_INVALIDATE_BY_ERASE
18+
bool "Erase start of the unboxer package to enter firmware loader"
19+
help
20+
If this method is used, the unboxer will erase the start of the unboxer package
21+
if it detects the need to request firmware loader entrance.
22+
The amount of bytes to erase is equal to the erase block size.
23+
24+
config UNBOXER_FW_LOADER_ENTRANCE_BOOT_MODE
25+
bool "Use boot mode to request FW loader entrance"
26+
select RETAINED_MEM
27+
select RETENTION
28+
select RETENTION_BOOT_MODE
29+
30+
config UNBOXER_FW_LOADER_ENTRANCE_BOOT_REQ
31+
bool "Use boot request to request FW loader entrance"
32+
select RETAINED_MEM if !SOC_NRF54H20
33+
select RETENTION if !SOC_NRF54H20
34+
select NRF_MCUBOOT_BOOT_REQUEST
35+
select IMG_MANAGER
36+
37+
config UNBOXER_FW_LOADER_ENTRANCE_METHOD_NONE
38+
bool "Do not perform any actions to request firmware loader entrance"
39+
help
40+
In some of the cases the unboxer should not perform any actions
41+
to request firmware loader entrance.
42+
Currently these include:
43+
- Firmware loader entrance requested by gpio
44+
- Firmware loader entrance requested by reset pin
45+
46+
endchoice
47+
48+
config UNBOXER_REBOOT
49+
bool "Reboot the device after requesting firmware loader entrance"
50+
depends on !UNBOXER_FW_LOADER_ENTRANCE_METHOD_NONE
51+
default y if UNBOXER_FW_LOADER_ENTRANCE_SELF_INVALIDATE_BY_ERASE
52+
default y if UNBOXER_FW_LOADER_ENTRANCE_BOOT_REQ
53+
default y if UNBOXER_FW_LOADER_ENTRANCE_BOOT_MODE
54+
select REBOOT
55+
56+
source "Kconfig.zephyr"

‎applications/unboxer/README.rst‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
.. _unboxer_application:
2+
3+
Unboxer application
4+
###################
5+
6+
.. contents::
7+
:local:
8+
:depth: 2
9+
10+
This application provides firmware loader update functionality in combination with the MCUboot bootloader in firmware updater mode.
11+
It extracts a new firmware loader image from a combined unboxer-and-firmware-loader package in the primary slot, copies it to the firmware loader partition, then invalidates itself so that the device boots into the firmware loader on the next reboot.
12+
13+
This application is not intended to function as a standalone application.
14+
Instead, it is automatically included and built by sysbuild when firmware loader update is enabled in a project configuration (:kconfig:option:`SB_CONFIG_FIRMWARE_LOADER_UPDATE_ENABLE`).
15+
16+
Overview
17+
********
18+
19+
The unboxer runs from the application slot (slot0) when the device boots with a combined image that contains both the unboxer and a new firmware loader image - see :ref:`ug_bootloader_firmware_loader_update`.
20+
It:
21+
22+
* Reads the combined image in ``slot0_partition`` and locates the appended firmware loader image
23+
* Compares it with the image already installed in the firmware loader partition (``slot1_partition``)
24+
* If they differ, erases the firmware loader partition, copies the new image, and verifies the copy
25+
* Invalidates the unboxer (so MCUboot will not boot it again) using the configured strategy:
26+
* Erase the start of the unboxer package, or
27+
* Request firmware loader entrance (boot mode or boot request) so MCUboot handles invalidation
28+
* Optionally reboots the device so the firmware loader is run next
29+
30+
After a successful run, the device boots into the updated firmware loader instead of the unboxer.
31+
32+
Building and running
33+
********************
34+
35+
This application is not intended for standalone building.
36+
It is automatically included and built when the following sysbuild options are enabled in a project configuration:
37+
38+
* :kconfig:option:`SB_CONFIG_BOOTLOADER_MCUBOOT`
39+
* :kconfig:option:`SB_CONFIG_MCUBOOT_MODE_FIRMWARE_UPDATER`
40+
* :kconfig:option:`SB_CONFIG_FIRMWARE_LOADER_UPDATE_ENABLE`
41+
42+
This will by default select :kconfig:option:`SB_CONFIG_FIRMWARE_LOADER_UNBOXER_BASIC`, which will cause this application to be built.
43+
44+
Testing
45+
=======
46+
47+
This application is not intended for standalone testing.
48+
It is exercised as part of samples that enable firmware loader update (for example, the :ref:`single_slot_sample` sample with ``SB_CONFIG_FIRMWARE_LOADER_UPDATE_ENABLE=y``).

‎applications/unboxer/prj.conf‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
#
2+
# Copyright (c) 2026 Nordic Semiconductor ASA
3+
#
4+
# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
5+
#
6+
7+
CONFIG_FLASH=y
8+
CONFIG_STREAM_FLASH=y
9+
CONFIG_FLASH_MAP=y
10+
CONFIG_CRC=y
11+
CONFIG_MULTITHREADING=n
12+
13+
# # Enable logging
14+
CONFIG_LOG=y
15+
# This is needed for logs to be printed because of CONFIG_MULTITHREADING=n
16+
CONFIG_LOG_MODE_IMMEDIATE=y
17+
CONFIG_LOG_MODE_MINIMAL=y
18+
CONFIG_NCS_BOOT_BANNER=n
19+
20+
CONFIG_LTO=y
21+
CONFIG_ISR_TABLES_LOCAL_DECLARATION=y
22+
23+
# The unboxer image is not directly flashable
24+
CONFIG_BUILD_OUTPUT_HEX=n

‎applications/unboxer/socs/nrf54h20_cpuapp.conf‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
#
2+
# Copyright (c) 2026 Nordic Semiconductor ASA
3+
#
4+
# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
5+
#
6+
7+
CONFIG_MULTITHREADING=y

0 commit comments

Comments
 (0)