Skip to content

Commit d341906

Browse files
e-rknordicjm
e-rk
authored and
nordicjm
committed
samples: suit: add flash companion application
The flash companion serves as a proxy for the secure domain firmware on nRF54H20 devices, allowing the SUIT firmware upgrade process to access data on the external memory devices. Signed-off-by: Rafał Kuźnia <[email protected]>
1 parent 3501a6c commit d341906

File tree

13 files changed

+299
-3
lines changed

13 files changed

+299
-3
lines changed

‎cmake/sysbuild/suit.cmake‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -173,6 +173,18 @@ function(suit_create_package)
173173
--core sysbuild,,,${CMAKE_BINARY_DIR}/zephyr/.config
174174
)
175175

176+
foreach(image ${IMAGES})
177+
sysbuild_get(BINARY_DIR IMAGE ${image} VAR APPLICATION_BINARY_DIR CACHE)
178+
sysbuild_get(BINARY_FILE IMAGE ${image} VAR CONFIG_KERNEL_BIN_NAME KCONFIG)
179+
180+
set(BINARY_FILE "${BINARY_FILE}.bin")
181+
182+
list(APPEND CORE_ARGS
183+
--core ${image},${SUIT_ROOT_DIRECTORY}${image}.bin,${BINARY_DIR}/zephyr/edt.pickle,${BINARY_DIR}/zephyr/.config
184+
)
185+
suit_copy_artifact_to_output_directory(${image} ${BINARY_DIR}/zephyr/${BINARY_FILE})
186+
endforeach()
187+
176188
foreach(image ${IMAGES})
177189
sysbuild_get(GENERATE_LOCAL_ENVELOPE IMAGE ${image} VAR CONFIG_SUIT_LOCAL_ENVELOPE_GENERATE KCONFIG)
178190
if(NOT DEFINED GENERATE_LOCAL_ENVELOPE)

‎doc/nrf/samples.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,7 @@ If you want to list samples available for one or more specific boards, `use the
4646
samples/pmic
4747
samples/sdfw
4848
samples/sensor
49+
samples/suit
4950
samples/tfm
5051
samples/thread
5152
samples/zigbee

‎doc/nrf/samples/suit.rst‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
.. _suit_samples:
2+
3+
SUIT samples
4+
############
5+
6+
.. toctree::
7+
:maxdepth: 1
8+
:caption: Subpages
9+
:glob:
10+
11+
../../../samples/suit/*/README

‎samples/suit/flash_companion/CMakeLists.txt‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
#
2+
# Copyright (c) 2024 Nordic Semiconductor ASA
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(flash_companion)
11+
12+
target_sources(app PRIVATE src/main.c)

‎samples/suit/flash_companion/README.rst‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
:orphan:
2+
3+
.. _suit_flash_companion:
4+
5+
SUIT flash companion
6+
####################
7+
8+
.. contents::
9+
:local:
10+
:depth: 2
11+
12+
The SUIT flash companion sample allows the Secure Domain Firmware to access the external memory during the :ref:`Software Updates for Internet of Things (SUIT) <ug_nrf54h20_suit_dfu>` firmware upgrade.
13+
14+
Requirements
15+
************
16+
17+
The sample supports the following development kit:
18+
19+
.. table-from-rows:: /includes/sample_board_rows.txt
20+
:header: heading
21+
:rows: nrf54h20dk_nrf54h20_cpuapp
22+
23+
Overview
24+
********
25+
26+
The flash companion sample implements a device driver for the external flash device and provides an IPC service to the Secure Domain Firmware.
27+
The Secure Domain Firmware uses the IPC service to read, erase, or write data to the external memory.
28+
29+
The sample is meant to be booted by the Secure Domain while performing the firmware update process using the :ref:`SUIT <ug_nrf54h20_suit_dfu>` firmware upgrade.
30+
31+
The flash companion sample is not a stand-alone firmware, it is intended to be used with the ``nrf54h_suit_sample`` to complete a firmware transfer with external flash.
32+
33+
Configuration
34+
*************
35+
36+
|config|
37+
38+
Setup
39+
=====
40+
41+
You can build the sample using Sysbuild by enabling the :kconfig:option:`SB_CONFIG_SUIT_BUILD_FLASH_COMPANION` Kconfig option.
42+
The memory partition from which the firmware will run can be configured by providing a devicetree overlay through Sysbuild.
43+
You should create a dedicated partition in non-volatile memory and override the ``zephyr,code-partition``.
44+
The memory partition must not be used by any other firmware image.
45+
46+
The sample is booted during the SUIT firmware upgrade process.
47+
See the :ref:`ug_nrf54h20_suit_external_memory` user guide to learn how to setup your sample to boot and use the flash companion's services during firmware upgrade.
48+
49+
Configuration options
50+
=====================
51+
52+
Check and configure the following configuration option:
53+
54+
.. _SB_CONFIG_SUIT_BUILD_FLASH_COMPANION:
55+
56+
SB_CONFIG_SUIT_BUILD_FLASH_COMPANION - Configuration for the firmware
57+
This option enables the sample and builds it during the Sysbuild.
58+
59+
Building and running
60+
********************
61+
62+
The flash companion sample is not a stand-alone firmware.
63+
To build it, open a different sample or application, such as :file:`samples/suit/smp_transfer`.
64+
Make sure that both the main application and the flash companion support your target platform.
65+
66+
Perform the following steps in the main application directory:
67+
68+
1. Enable the :kconfig:option:`SB_CONFIG_SUIT_BUILD_FLASH_COMPANION` Sysbuild option.
69+
70+
#. Create :file:`sysbuild/flash_companion.overlay` devicetree overlay file and add the following content:
71+
72+
a. Create a dedicated partition in non-volatile memory:
73+
74+
.. code-block:: devicetree
75+
76+
&cpuapp_rx_partitions {
77+
cpuapp_slot0_partition: partition@a6000 {
78+
reg = <0xa6000 DT_SIZE_K(448)>;
79+
};
80+
companion_partition: partition@116000 {
81+
reg = <0x116000 DT_SIZE_K(64)>;
82+
};
83+
};
84+
85+
In the above example the executable memory partition of the main application (``cpuapp_slot0_partition``) is shrunk to make space for the flash companion executable memory partition (``companion_partition``).
86+
87+
#. Apply the same memory partition configuration to the main application's devicetree overlay.
88+
89+
#. Enable SPI NOR devicetree node.
90+
In the case of nRF54H20 DK, you can enable the following node:
91+
92+
.. code-block:: devicetree
93+
94+
&mx25uw63 {
95+
status = "okay";
96+
};
97+
98+
#. Build the main application:
99+
100+
.. code-block:: console
101+
102+
$ west build -b nrf54h20dk/nrf54h20/cpuapp --sysbuild
103+
104+
The flash companion sample will be built automatically by Sysbuild.
105+
106+
Dependencies
107+
************
108+
109+
This sample uses the following |NCS| libraries:
110+
111+
* :file:`include/sdfw_services/ssf_client.h`
112+
* `zcbor`_
113+
114+
It uses the following Zephyr library:
115+
116+
* :ref:`zephyr:flash_api`
117+
118+
The sample also uses drivers from `nrfx`_.

‎samples/suit/flash_companion/boards/nrf54h20dk_nrf54h20_cpuapp.overlay‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
/*
2+
* Copyright (c) 2024 Nordic Semiconductor ASA
3+
*
4+
* SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
5+
*/
6+
7+
/ {
8+
chosen {
9+
extmem-device = &mx25uw63;
10+
};
11+
};
12+
13+
&cpusec_cpuapp_ipc {
14+
status = "okay";
15+
};
16+
17+
&cpusec_bellboard {
18+
status = "okay";
19+
};
20+
21+
&cpuapp_bellboard {
22+
status = "okay";
23+
};
24+
25+
&mx25uw63 {
26+
status = "okay";
27+
};

‎samples/suit/flash_companion/prj.conf‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
#
2+
# Copyright (c) 2024 Nordic Semiconductor ASA
3+
#
4+
# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
5+
#
6+
7+
# Minimal scheduler configuration
8+
CONFIG_NUM_PREEMPT_PRIORITIES=0
9+
CONFIG_MULTITHREADING=y
10+
CONFIG_NUM_COOP_PRIORITIES=16
11+
CONFIG_NUM_METAIRQ_PRIORITIES=0
12+
CONFIG_SCHED_DUMB=y
13+
CONFIG_WAITQ_DUMB=y
14+
15+
# Enable peripherals needed by the flash companion firmware
16+
CONFIG_GPIO=y
17+
CONFIG_PINCTRL=y
18+
CONFIG_FLASH=y
19+
20+
# Disable power management
21+
CONFIG_PM=n
22+
23+
# Disable unneeded interrupt features
24+
CONFIG_DYNAMIC_INTERRUPTS=n
25+
CONFIG_IRQ_OFFLOAD=n
26+
27+
# Disable memory protection
28+
CONFIG_THREAD_STACK_INFO=n
29+
CONFIG_THREAD_CUSTOM_DATA=n
30+
31+
# Disable unneeded ARM core functionality
32+
CONFIG_ARM_MPU=n
33+
CONFIG_FPU=n
34+
35+
# Disable boot banner
36+
CONFIG_BOOT_BANNER=n
37+
CONFIG_BOOT_DELAY=0
38+
39+
# Disable serial communication
40+
CONFIG_CONSOLE=n
41+
CONFIG_UART_CONSOLE=n
42+
CONFIG_STDOUT_CONSOLE=n
43+
CONFIG_PRINTK=n
44+
CONFIG_EARLY_CONSOLE=n
45+
46+
# Build
47+
CONFIG_SIZE_OPTIMIZATIONS=y
48+
49+
# Enable external memory service
50+
CONFIG_SSF_EXTMEM_SERVICE_ENABLED=y
51+
52+
# Link against zephyr,code-partition
53+
CONFIG_USE_DT_CODE_PARTITION=y
54+
55+
CONFIG_SUIT_LOCAL_ENVELOPE_GENERATE=n
56+
CONFIG_NRF_REGTOOL_GENERATE_UICR=n
57+
58+
# Enable canonical zcbor encoding
59+
CONFIG_ZCBOR_CANONICAL=y

‎samples/suit/flash_companion/src/main.c‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
/*
2+
* Copyright (c) 2024 Nordic Semiconductor ASA
3+
*
4+
* SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
5+
*/
6+
7+
#include <zephyr/kernel.h>
8+
#include <sdfw/sdfw_services/extmem_remote.h>
9+
10+
int main(void)
11+
{
12+
extmem_remote_init();
13+
return 0;
14+
}

‎subsys/sdfw_services/services/extmem/extmem_remote.c‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@
2525
#include <zephyr/logging/log.h>
2626
LOG_MODULE_REGISTER(extmem_srvc, CONFIG_SSF_EXTMEM_SERVICE_LOG_LEVEL);
2727

28-
#define FLASH_DEVICE DEVICE_DT_GET(DT_ALIAS(spi_flash0))
28+
#define FLASH_DEVICE DEVICE_DT_GET(DT_CHOSEN(extmem_device))
2929

3030
#define SSF_CLIENT_SERVICE_DEFINE_GLOBAL(_name, _srvc_name, _req_encode, _rsp_decode) \
3131
const struct ssf_client_srvc _name = { \

‎subsys/suit/memory_layout/src/suit_memory_layout.c‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -35,8 +35,8 @@
3535
#define SUIT_PLAT_INTERNAL_NVM_DEV NULL
3636
#endif
3737

38-
#if (DT_NODE_EXISTS(DT_ALIAS(spi_flash0)))
39-
#define EXTERNAL_NVM_DEV DEVICE_DT_GET(DT_ALIAS(spi_flash0))
38+
#if (DT_NODE_EXISTS(DT_CHOSEN(extmem_device)))
39+
#define EXTERNAL_NVM_DEV DEVICE_DT_GET(DT_CHOSEN(extmem_device))
4040
#else
4141
#define EXTERNAL_NVM_DEV NULL
4242
#endif

0 commit comments

Comments
 (0)