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]>

cmake/sysbuild/suit.cmake

@@ -173,6 +173,18 @@ function(suit_create_package)
     --core sysbuild,,,${CMAKE_BINARY_DIR}/zephyr/.config
   )
 
+  foreach(image ${IMAGES})
+    sysbuild_get(BINARY_DIR IMAGE ${image} VAR APPLICATION_BINARY_DIR CACHE)
+    sysbuild_get(BINARY_FILE IMAGE ${image} VAR CONFIG_KERNEL_BIN_NAME KCONFIG)
+
+    set(BINARY_FILE "${BINARY_FILE}.bin")
+
+    list(APPEND CORE_ARGS
+      --core ${image},${SUIT_ROOT_DIRECTORY}${image}.bin,${BINARY_DIR}/zephyr/edt.pickle,${BINARY_DIR}/zephyr/.config
+    )
+    suit_copy_artifact_to_output_directory(${image} ${BINARY_DIR}/zephyr/${BINARY_FILE})
+  endforeach()
+
   foreach(image ${IMAGES})
     sysbuild_get(GENERATE_LOCAL_ENVELOPE IMAGE ${image} VAR CONFIG_SUIT_LOCAL_ENVELOPE_GENERATE KCONFIG)
     if(NOT DEFINED GENERATE_LOCAL_ENVELOPE)

doc/nrf/samples.rst

@@ -46,6 +46,7 @@ If you want to list samples available for one or more specific boards, `use the
    samples/pmic
    samples/sdfw
    samples/sensor
+   samples/suit
    samples/tfm
    samples/thread
    samples/zigbee

doc/nrf/samples/suit.rst

@@ -0,0 +1,11 @@
+.. _suit_samples:
+
+SUIT samples
+############
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Subpages
+   :glob:
+
+   ../../../samples/suit/*/README

samples/suit/flash_companion/CMakeLists.txt

@@ -0,0 +1,12 @@
+#
+# Copyright (c) 2024 Nordic Semiconductor ASA
+#
+# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
+#
+
+cmake_minimum_required(VERSION 3.20.0)
+
+find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
+project(flash_companion)
+
+target_sources(app PRIVATE src/main.c)

samples/suit/flash_companion/README.rst

@@ -0,0 +1,118 @@
+:orphan:
+
+.. _suit_flash_companion:
+
+SUIT flash companion
+####################
+
+.. contents::
+   :local:
+   :depth: 2
+
+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.
+
+Requirements
+************
+
+The sample supports the following development kit:
+
+.. table-from-rows:: /includes/sample_board_rows.txt
+   :header: heading
+   :rows: nrf54h20dk_nrf54h20_cpuapp
+
+Overview
+********
+
+The flash companion sample implements a device driver for the external flash device and provides an IPC service to the Secure Domain Firmware.
+The Secure Domain Firmware uses the IPC service to read, erase, or write data to the external memory.
+
+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.
+
+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.
+
+Configuration
+*************
+
+|config|
+
+Setup
+=====
+
+You can build the sample using Sysbuild by enabling the :kconfig:option:`SB_CONFIG_SUIT_BUILD_FLASH_COMPANION` Kconfig option.
+The memory partition from which the firmware will run can be configured by providing a devicetree overlay through Sysbuild.
+You should create a dedicated partition in non-volatile memory and override the ``zephyr,code-partition``.
+The memory partition must not be used by any other firmware image.
+
+The sample is booted during the SUIT firmware upgrade process.
+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.
+
+Configuration options
+=====================
+
+Check and configure the following configuration option:
+
+.. _SB_CONFIG_SUIT_BUILD_FLASH_COMPANION:
+
+SB_CONFIG_SUIT_BUILD_FLASH_COMPANION - Configuration for the firmware
+   This option enables the sample and builds it during the Sysbuild.
+
+Building and running
+********************
+
+The flash companion sample is not a stand-alone firmware.
+To build it, open a different sample or application, such as :file:`samples/suit/smp_transfer`.
+Make sure that both the main application and the flash companion support your target platform.
+
+Perform the following steps in the main application directory:
+
+1. Enable the :kconfig:option:`SB_CONFIG_SUIT_BUILD_FLASH_COMPANION` Sysbuild option.
+
+#. Create :file:`sysbuild/flash_companion.overlay` devicetree overlay file and add the following content:
+
+   a. Create a dedicated partition in non-volatile memory:
+
+      .. code-block:: devicetree
+
+         &cpuapp_rx_partitions {
+            cpuapp_slot0_partition: partition@a6000 {
+               reg = <0xa6000 DT_SIZE_K(448)>;
+            };
+            companion_partition: partition@116000 {
+               reg = <0x116000 DT_SIZE_K(64)>;
+            };
+         };
+
+      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``).
+
+   #. Apply the same memory partition configuration to the main application's devicetree overlay.
+
+   #. Enable SPI NOR devicetree node.
+      In the case of nRF54H20 DK, you can enable the following node:
+
+      .. code-block:: devicetree
+
+         &mx25uw63 {
+            status = "okay";
+         };
+
+#. Build the main application:
+
+   .. code-block:: console
+
+      $ west build -b nrf54h20dk/nrf54h20/cpuapp --sysbuild
+
+The flash companion sample will be built automatically by Sysbuild.
+
+Dependencies
+************
+
+This sample uses the following |NCS| libraries:
+
+* :file:`include/sdfw_services/ssf_client.h`
+* `zcbor`_
+
+It uses the following Zephyr library:
+
+* :ref:`zephyr:flash_api`
+
+The sample also uses drivers from `nrfx`_.

samples/suit/flash_companion/boards/nrf54h20dk_nrf54h20_cpuapp.overlay

@@ -0,0 +1,27 @@
+/*
+ * Copyright (c) 2024 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
+ */
+
+/ {
+	chosen {
+		extmem-device = &mx25uw63;
+	};
+};
+
+&cpusec_cpuapp_ipc {
+	status = "okay";
+};
+
+&cpusec_bellboard {
+	status = "okay";
+};
+
+&cpuapp_bellboard {
+	status = "okay";
+};
+
+&mx25uw63 {
+	status = "okay";
+};

samples/suit/flash_companion/prj.conf

@@ -0,0 +1,59 @@
+#
+# Copyright (c) 2024 Nordic Semiconductor ASA
+#
+# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
+#
+
+# Minimal scheduler configuration
+CONFIG_NUM_PREEMPT_PRIORITIES=0
+CONFIG_MULTITHREADING=y
+CONFIG_NUM_COOP_PRIORITIES=16
+CONFIG_NUM_METAIRQ_PRIORITIES=0
+CONFIG_SCHED_DUMB=y
+CONFIG_WAITQ_DUMB=y
+
+# Enable peripherals needed by the flash companion firmware
+CONFIG_GPIO=y
+CONFIG_PINCTRL=y
+CONFIG_FLASH=y
+
+# Disable power management
+CONFIG_PM=n
+
+# Disable unneeded interrupt features
+CONFIG_DYNAMIC_INTERRUPTS=n
+CONFIG_IRQ_OFFLOAD=n
+
+# Disable memory protection
+CONFIG_THREAD_STACK_INFO=n
+CONFIG_THREAD_CUSTOM_DATA=n
+
+# Disable unneeded ARM core functionality
+CONFIG_ARM_MPU=n
+CONFIG_FPU=n
+
+# Disable boot banner
+CONFIG_BOOT_BANNER=n
+CONFIG_BOOT_DELAY=0
+
+# Disable serial communication
+CONFIG_CONSOLE=n
+CONFIG_UART_CONSOLE=n
+CONFIG_STDOUT_CONSOLE=n
+CONFIG_PRINTK=n
+CONFIG_EARLY_CONSOLE=n
+
+# Build
+CONFIG_SIZE_OPTIMIZATIONS=y
+
+# Enable external memory service
+CONFIG_SSF_EXTMEM_SERVICE_ENABLED=y
+
+# Link against zephyr,code-partition
+CONFIG_USE_DT_CODE_PARTITION=y
+
+CONFIG_SUIT_LOCAL_ENVELOPE_GENERATE=n
+CONFIG_NRF_REGTOOL_GENERATE_UICR=n
+
+# Enable canonical zcbor encoding
+CONFIG_ZCBOR_CANONICAL=y

samples/suit/flash_companion/src/main.c

@@ -0,0 +1,14 @@
+/*
+ * Copyright (c) 2024 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
+ */
+
+#include <zephyr/kernel.h>
+#include <sdfw/sdfw_services/extmem_remote.h>
+
+int main(void)
+{
+	extmem_remote_init();
+	return 0;
+}

subsys/sdfw_services/services/extmem/extmem_remote.c

@@ -25,7 +25,7 @@
 #include <zephyr/logging/log.h>
 LOG_MODULE_REGISTER(extmem_srvc, CONFIG_SSF_EXTMEM_SERVICE_LOG_LEVEL);
 
-#define FLASH_DEVICE DEVICE_DT_GET(DT_ALIAS(spi_flash0))
+#define FLASH_DEVICE DEVICE_DT_GET(DT_CHOSEN(extmem_device))
 
 #define SSF_CLIENT_SERVICE_DEFINE_GLOBAL(_name, _srvc_name, _req_encode, _rsp_decode)              \
 	const struct ssf_client_srvc _name = {                                                     \

subsys/suit/memory_layout/src/suit_memory_layout.c

@@ -35,8 +35,8 @@
 #define SUIT_PLAT_INTERNAL_NVM_DEV NULL
 #endif
 
-#if (DT_NODE_EXISTS(DT_ALIAS(spi_flash0)))
-#define EXTERNAL_NVM_DEV DEVICE_DT_GET(DT_ALIAS(spi_flash0))
+#if (DT_NODE_EXISTS(DT_CHOSEN(extmem_device)))
+#define EXTERNAL_NVM_DEV DEVICE_DT_GET(DT_CHOSEN(extmem_device))
 #else
 #define EXTERNAL_NVM_DEV NULL
 #endif

sysbuild/CMakeLists.txt

@@ -365,5 +365,6 @@ endif()
 
 include(${CMAKE_CURRENT_LIST_DIR}/netcore.cmake)
 include(${CMAKE_CURRENT_LIST_DIR}/secureboot.cmake)
+include(${CMAKE_CURRENT_LIST_DIR}/suit.cmake)
 
 store_ncs_vars()

sysbuild/Kconfig.suit

@@ -69,4 +69,20 @@ config SUIT_ENVELOPE_NORDIC_TOP_DIRECTORY
 
 endif # SUIT_ENVELOPE
 
+config SUIT_BUILD_FLASH_COMPANION
+	bool "Build SUIT flash companion firmware"
+	help
+	  Build the flash companion firmware, which acts as a proxy for the secure domain
+	  firmware to read and write to the external memory.
+
+if SUIT_BUILD_FLASH_COMPANION
+
+config FLASH_COMPANION_TARGET_CPUCLUSTER
+	string "Flash companion target cluster"
+	default "cpuapp"  if SOC_SERIES_NRF54HX
+	help
+	  Set the target CPU cluster on which the companion firmware will run.
+
+endif # SUIT_BUILD_FLASH_COMPANION
+
 endmenu

sysbuild/suit.cmake

@@ -0,0 +1,25 @@
+#
+# Copyright (c) 2024 Nordic Semiconductor ASA
+#
+# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
+#
+
+if(SB_CONFIG_SUIT_BUILD_FLASH_COMPANION)
+  # Calculate the network board target
+  string(REPLACE "/" ";" split_board_qualifiers "${BOARD_QUALIFIERS}")
+  list(GET split_board_qualifiers 1 target_soc)
+  list(GET split_board_qualifiers 2 target_cpucluster)
+
+  if(DEFINED BOARD_REVISION)
+    set(board_target "${BOARD}@${BOARD_REVISION}/${target_soc}/${SB_CONFIG_FLASH_COMPANION_TARGET_CPUCLUSTER}")
+  else()
+    set(board_target "${BOARD}/${target_soc}/${SB_CONFIG_FLASH_COMPANION_TARGET_CPUCLUSTER}")
+  endif()
+
+  ExternalZephyrProject_Add(
+    APPLICATION flash_companion
+    SOURCE_DIR "${ZEPHYR_NRF_MODULE_DIR}/samples/suit/flash_companion"
+    BOARD ${board_target}
+    BUILD_ONLY TRUE
+  )
+endif()