Add idle relocated TCM multicore test for nRF54H20

CODEOWNERS

@@ -523,6 +523,8 @@
 /samples/nrf5340/empty_app_core/          @nrfconnect/ncs-si-muffin
 /samples/nrf5340/extxip_smp_svr/          @nrfconnect/ncs-eris
 /samples/nrf54h20/empty_app_core/         @nrfconnect/ncs-aurora
+/samples/nrf54h20/idle_relocated_tcm/     @nrfconnect/ncs-si-muffin
+/samples/nrf54h20/radio_loader/           @nrfconnect/ncs-si-muffin
 /samples/ironside_se/                     @nrfconnect/ncs-aurora
 /samples/nrf_compress/                    @nordicjm
 /samples/nrf_profiler/                    @nrfconnect/ncs-si-bluebagel
@@ -646,6 +648,7 @@
 /samples/net/**/*.rst                     @nrfconnect/ncs-cia-doc
 /samples/net/coap_client/*.rst            @nrfconnect/ncs-iot-oulu-tampere-doc
 /samples/nfc/**/*.rst                     @nrfconnect/ncs-si-muffin-doc
+/samples/nrf54h20/idle_relocated_tcm/*.rst @nrfconnect/ncs-si-muffin-doc
 /samples/nrf5340/empty_app_core/*.rst     @nrfconnect/ncs-si-muffin-doc
 /samples/nrf5340/extxip_smp_svr/*.rst     @nrfconnect/ncs-eris-doc
 /samples/nrf5340/netboot/*.rst            @nrfconnect/ncs-eris-doc

cmake/modules/kconfig.cmake

@@ -29,7 +29,11 @@ if(CONFIG_NCS_IS_VARIANT_IMAGE)
   else()
     include(${ZEPHYR_NRF_MODULE_DIR}/cmake/sysbuild/bootloader_dts_utils.cmake)
 
-    dt_chosen(code_partition PROPERTY "zephyr,code-partition")
+    dt_chosen(code_partition PROPERTY "fw-to-relocate")
+    if("${code_partition}" STREQUAL "")
+      dt_chosen(code_partition PROPERTY "zephyr,code-partition")
+    endif()
+
     dt_partition_addr(code_partition_offset PATH "${code_partition}" REQUIRED)
     dt_reg_size(code_partition_size PATH "${code_partition}" REQUIRED)
 
@@ -44,8 +48,24 @@ if(CONFIG_NCS_IS_VARIANT_IMAGE)
     # Additionally, convert primary slot dependencies to secondary slot dependencies.
     set(dotconfig_variant_content)
     foreach(line IN LISTS dotconfig_content)
+      dt_chosen(fw_to_relocate_property PROPERTY "fw-to-relocate")
       if("${line}" MATCHES "^CONFIG_FLASH_LOAD_OFFSET=.*$")
-        string(REGEX REPLACE "CONFIG_FLASH_LOAD_OFFSET=(.*)" "CONFIG_FLASH_LOAD_OFFSET=${code_partition_offset}" line ${line})
+        # Change the CONFIG_FLASH_LOAD_OFFSET value only if the fw_to_relocate_property is empty - meaning that the firmware is not being relocated.
+        if("${fw_to_relocate_property}" STREQUAL "")
+          string(REGEX REPLACE "CONFIG_FLASH_LOAD_OFFSET=(.*)" "CONFIG_FLASH_LOAD_OFFSET=${code_partition_offset}" line ${line})
+        endif()
+      endif()
+
+      # Change the CONFIG_BUILD_OUTPUT_ADJUST_LMA value only if the fw_to_relocate_property is not empty - meaning that the firmware is being relocated.
+      if(NOT "${fw_to_relocate_property}" STREQUAL "")
+        if("${line}" MATCHES "^CONFIG_BUILD_OUTPUT_ADJUST_LMA=.*$")
+
+          dt_partition_addr(fw_to_relocate_offset ABSOLUTE PATH "${fw_to_relocate_property}" REQUIRED)
+          dt_chosen(tcm_code_property PROPERTY "zephyr,code-partition")
+          dt_reg_addr(tcm_code_addr PATH "${tcm_code_property}" REQUIRED)
+
+          string(REGEX REPLACE "CONFIG_BUILD_OUTPUT_ADJUST_LMA=(.*)" "CONFIG_BUILD_OUTPUT_ADJUST_LMA=${flash_base_addr}+${fw_to_relocate_offset}-${tcm_code_addr}" line ${line})
+        endif()
       endif()
 
       if("${line}" MATCHES "^CONFIG_FLASH_LOAD_SIZE=.*$")
@@ -62,7 +82,10 @@ if(CONFIG_NCS_IS_VARIANT_IMAGE)
     set(autoconf_variant_content)
     foreach(line IN LISTS autoconf_content)
       if("${line}" MATCHES "^#define CONFIG_FLASH_LOAD_OFFSET .*$")
-        string(REGEX REPLACE "#define CONFIG_FLASH_LOAD_OFFSET (.*)" "#define CONFIG_FLASH_LOAD_OFFSET ${code_partition_offset}" line ${line})
+        # Change the CONFIG_FLASH_LOAD_OFFSET value only if the fw_to_relocate_property is empty - meaning that the firmware is not being relocated.
+        if("${fw_to_relocate_property}" STREQUAL "")
+          string(REGEX REPLACE "#define CONFIG_FLASH_LOAD_OFFSET (.*)" "#define CONFIG_FLASH_LOAD_OFFSET ${code_partition_offset}" line ${line})
+        endif()
       endif()
 
       if("${line}" MATCHES "^#define CONFIG_FLASH_LOAD_SIZE .*$")

cmake/sysbuild/sign_nrf54h20.cmake

@@ -25,7 +25,11 @@ function(check_merged_slot_boundaries merged_partition images)
     set(end_offset)
     sysbuild_get(start_offset IMAGE ${image} VAR CONFIG_ROM_START_OFFSET KCONFIG)
     sysbuild_get(end_offset IMAGE ${image} VAR CONFIG_ROM_END_OFFSET KCONFIG)
-    dt_chosen(code_flash TARGET ${image} PROPERTY "zephyr,code-partition")
+    dt_chosen(code_flash TARGET ${image} PROPERTY "fw-to-relocate")
+    if("${code_flash}" STREQUAL "")
+      dt_chosen(code_flash TARGET ${image} PROPERTY "zephyr,code-partition")
+    endif()
+
     dt_partition_addr(code_addr PATH "${code_flash}" TARGET ${image} REQUIRED ABSOLUTE)
     dt_reg_size(code_size TARGET ${image} PATH ${code_flash})
 

doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst

@@ -855,6 +855,11 @@ Other samples
   * Added a new testing step demonstrating how to calculate event propagation statistics.
     Also added the related test preset for the :file:`calc_stats.py` script (:file:`nrf/scripts/nrf_profiler/stats_nordic_presets/app_event_manager_profiler_tracer.json`).
 
+* Added:
+
+  * The :ref:`idle_relocated_tcm_sample` sample to demonstrate how to relocate the firmware to the TCM memory at boot time.
+    The sample also uses the ``radio_loader`` sample image (located in :file:`nrf/samples/nrf54h20/radio_loader`), which cannot be tested as a standalone sample, to relocate the firmware from the MRAM to the TCM memory at boot time.
+
 Drivers
 =======
 

doc/nrf/samples/other.rst

@@ -25,3 +25,4 @@ This section lists single |NCS| samples for various uses that are not part of ot
    ../../../tests/benchmarks/multicore/*/README
    ../../../samples/zephyr/smp_svr_mini_boot/README
    ../../../samples/basic/*/README
+   ../../../samples/nrf54h20/*/README

samples/nrf54h20/idle_relocated_tcm/CMakeLists.txt

@@ -0,0 +1,19 @@
+#
+# Copyright (c) 2025 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})
+
+if(NOT SYSBUILD)
+	message(FATAL_ERROR
+		" This is a multi-image application that should be built using sysbuild.\n"
+		" Add --sysbuild argument to west build command to prepare all the images.")
+endif()
+
+project(idle)
+
+target_sources(app PRIVATE src/main.c)

samples/nrf54h20/idle_relocated_tcm/Kconfig.sysbuild

@@ -0,0 +1,24 @@
+#
+# Copyright (c) 2025 Nordic Semiconductor ASA
+#
+# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
+#
+
+source "share/sysbuild/Kconfig"
+
+choice NETCORE
+
+default NETCORE_CUSTOM_RADIO
+
+config NETCORE_CUSTOM_RADIO
+	bool "Custom radio"
+	help
+	  Use custom radio.
+
+endchoice
+
+config NETCORE_IMAGE_NAME
+	default "remote_rad" if NETCORE_CUSTOM_RADIO
+
+config NETCORE_IMAGE_PATH
+	default "$(ZEPHYR_NRF_MODULE_DIR)/samples/nrf54h20/idle_relocated_tcm/remote" if NETCORE_CUSTOM_RADIO

samples/nrf54h20/idle_relocated_tcm/README.rst

@@ -0,0 +1,230 @@
+.. _idle_relocated_tcm_sample:
+
+Multicore idle test with firmware relocated to radio core TCM
+#############################################################
+
+.. contents::
+   :local:
+   :depth: 2
+
+The test benchmarks the idle behavior of an application that runs on multiple cores.
+It demonstrates a radio loader pattern where the radio core firmware is loaded from MRAM into TCM (Tightly Coupled Memory) at runtime.
+
+Requirements
+************
+
+The test supports the following development kit:
+
+.. table-from-rows:: /includes/sample_board_rows.txt
+   :header: heading
+   :rows: nrf54h20dk_nrf54h20_cpuapp
+
+Overview
+********
+
+This test demonstrates how to build a multicore idle application with :ref:`configuration_system_overview_sysbuild` using a two-stage boot process for the radio core:
+
+* Radio Loader - A small bootloader that runs on the radio core, copies firmware from MRAM to TCM, and jumps to it.
+* Remote Firmware - The actual application that runs from TCM after being loaded.
+
+The test automatically relocates the remote firmware binary to the correct MRAM address during build time, ensuring it can be loaded by the radio loader.
+
+Architecture
+============
+
+The system uses the following memory layout:
+
+* **MRAM (Non-volatile):**
+
+  * ``cpurad_loader_partition`` @ 0x92000 - Contains the radio loader (8 KB)
+  * ``cpurad_loaded_fw`` @ 0x94000 - Contains the remote firmware binary (128 KB)
+
+* **TCM (Volatile, fast execution):**
+
+  * ``cpurad_ram0`` @ 0x23000000 - Code execution region (128 KB)
+  * ``cpurad_data_ram`` @ 0x23020000 - Data region (64 KB)
+
+Additional files
+================
+
+The test comes with the following additional files:
+
+* :file:`sysbuild.conf` - Enables the radio loader by setting ``CONFIG_NRF_RADIO_LOADER=y``.
+* :file:`boards/memory_map.overlay` - Shared memory map configuration for both loader and remote firmware.
+* :file:`sysbuild/radio_loader/` - Radio loader configuration overrides (:file:`prj.conf`, overlay).
+* :file:`sysbuild/remote_rad/` - Radio core firmware configuration overrides (:file:`prj.conf`, overlay).
+
+Enabling the Radio Loader
+*************************
+
+The radio loader is automatically added to the build when you enable it in sysbuild configuration.
+
+In :file:`sysbuild.conf`:
+
+.. code-block:: kconfig
+
+   SB_CONFIG_NRF_RADIO_LOADER=y
+
+This single configuration option:
+
+#. Automatically adds the ``radio_loader`` application located in the :file:`nrf/samples/nrf54h20/radio_loader` folder.
+#. Builds it for the CPURAD core.
+#. No manual ``ExternalZephyrProject_Add()`` needed in sysbuild.
+
+Memory map configuration
+========================
+
+The memory map is defined in :file:`boards/memory_map.overlay` and is shared between the radio loader and remote firmware to ensure consistency.
+
+The overlay defines:
+
+#. TCM regions:
+
+   .. code-block:: devicetree
+
+      cpurad_ram0: sram@23000000 {
+          compatible = "mmio-sram";
+          reg = <0x23000000 0x20000>;  /* 128 KB for code */
+      };
+      cpurad_data_ram: sram@23020000 {
+          compatible = "mmio-sram";
+          reg = <0x23020000 0x10000>;  /* 64 KB for data */
+      };
+
+#. MRAM partitions:
+
+   .. code-block:: devicetree
+
+      &mram1x {
+          /delete-node/ partitions;
+
+          partitions {
+              compatible = "fixed-partitions";
+              #address-cells = <1>;
+              #size-cells = <1>;
+
+              cpurad_loader_partition: partition@92000 {
+                  label = "cpurad_loader_partition";
+                  reg = <0x92000 DT_SIZE_K(8)>;  /* 8 KB allocated (~4 KB actual) */
+              };
+
+              cpurad_loaded_fw: partition@94000 {
+                  label = "cpurad_loaded_fw";
+                  reg = <0x94000 DT_SIZE_K(128)>;  /* 128 KB fixed */
+              };
+          };
+      };
+
+Automatic firmware relocation
+*****************************
+
+The remote firmware must be relocated to match the MRAM partition address where it will be stored.
+This is automatically done by Zephyr's ``CONFIG_BUILD_OUTPUT_ADJUST_LMA`` feature when the devicetree chosen nodes are configured correctly.
+
+How it works
+============
+
+Firmware relocation is handled automatically by Zephyr's build system using the ``CONFIG_BUILD_OUTPUT_ADJUST_LMA`` configuration option, which is configured in ``zephyr/soc/nordic/nrf54h/Kconfig.defconfig.nrf54h20_cpurad`` for all nRF54H20 CPURAD projects.
+
+The configuration automatically detects the ``fw-to-relocate`` chosen node in your devicetree.
+When present, it calculates the LMA adjustment to relocate firmware from MRAM to TCM.
+Without this chosen node, firmware runs directly from the ``zephyr,code-partition`` location (standard XIP behavior).
+
+Simply configure the devicetree chosen nodes correctly in your firmware's overlay:
+
+.. code-block:: devicetree
+
+   /{
+       chosen {
+           /* VMA: where code runs (TCM) */
+           zephyr,code-partition = &cpurad_ram0;
+           zephyr,sram = &cpurad_data_ram;
+
+           /* LMA: where to load from (MRAM partition) - enables relocation */
+           fw-to-relocate = &cpurad_loaded_fw;
+       };
+   };
+
+Zephyr automatically calculates the Load Memory Address (LMA) adjustment based on your chosen nodes:
+
+**With fw-to-relocate chosen node** (for radio loader pattern):
+
+.. code-block:: text
+
+   LMA_adjustment = fw-to-relocate address - zephyr,code-partition address
+                  = cpurad_loaded_fw - cpurad_ram0
+                  = 0x94000 - 0x23000000
+
+**Without fw-to-relocate** (standard behavior):
+
+.. code-block:: text
+
+   LMA_adjustment = zephyr,code-partition address - zephyr,sram address
+
+The build system then adjusts the hex file so that the firmware is loaded from MRAM (``0x94000``), but runs from TCM (``0x23000000``).
+
+Building and running
+********************
+
+.. |test path| replace:: :file:`samples/nrf54h20/idle_relocated_tcm`
+
+.. include:: /includes/build_and_run_test.txt
+
+Testing
+=======
+
+After programming the test to your development kit, complete the following steps to test it:
+
+1. |connect_terminal|
+#. Reset the kit.
+#. Observe the console output for both cores:
+
+   * For the application core, the output should be as follows:
+
+     .. code-block:: console
+
+       *** Booting nRF Connect SDK zephyr-v3.5.0-3517-g9458a1aaf744 ***
+       build time: Nov 22 2025 17:00:59
+       Multicore idle test on [email protected]/nrf54h20/cpuapp
+       Multicore idle test iteration 0
+       Multicore idle test iteration 1
+       ...
+
+   * For the radio core, the output should be as follows:
+
+     .. code-block:: console
+
+       *** Booting nRF Connect SDK zephyr-v3.5.0-3517-g9458a1aaf744 ***
+       build time: Nov 22 2025 17:00:29
+       Multicore idle test on [email protected]/nrf54h20/cpurad
+       Current PC (program counter) address: 0x23000ae0
+       Multicore idle test iteration 0
+       Multicore idle test iteration 1
+       ...
+
+   The radio loader first loads the firmware from MRAM (``0x0e094000``) to TCM (``0x23000000``) and then jumps to the loaded firmware.
+   This process is transparent and happens during the early boot stage.
+
+#. Verify the DFU process:
+
+   #. Build the firmware for the secondary app slot, increase the version number in the :file:`prj.conf` file (uncomment the line):
+
+      .. code-block:: kconfig
+
+         CONFIG_MCUBOOT_IMGTOOL_SIGN_VERSION="0.0.1+0"
+
+   #. Build the firmware:
+
+      .. code-block:: console
+
+         west build -p -b nrf54h20dk/nrf54h20/cpuapp
+
+   #. Program the firmware to the secondary application slot:
+
+      .. code-block:: console
+
+         nrfutil device program --firmware build/zephyr_secondary_app.merged.hex  --options chip_erase_mode=ERASE_NONE
+
+   Reset the development kit.
+   The firmware must boot from the secondary application slot.
+   Observe the change in build time in the console output.