Migrate your application for the nRF54H20 DK to nRF Connect SDK v2.7.0 (for v2.6.99-cs2 users)

This document describes the changes you should be aware of when migrating your application from the nRF Connect SDK v2.6.99-cs2 to the nRF Connect SDK v2.7.0.

Overview

nRF Connect SDK v2.7.0 introduced a series of changes that might affect your existing applications. The following is a summary of the most important ones:

Updated nRF Connect SDK toolchain

The nRF Connect SDK toolchain has been updated.

Sysbuild

A new build system was recently introduced in the nRF Connect SDK. For more information, see the Migrating to sysbuild user guide.

Hardware Model v2

The hardware model was introduced in the nRF Connect SDK v2.7.0.

nRF54H20 SoC binaries

A new version (v0.5.0) of the nRF54H20 SoC binaries was released. This is the only version compatible with the nRF Connect SDK v2.7.0. The nRF54H20 DK must be in lifecycle state EMPTY to be provisioned with the new SoC binaries.

DTS changes

The layout of DTS files and the names of DTS nodes related to the updated board names have been updated, which also affects overlay files from applications and samples. If your application required a specific custom board, you must update the custom board files to match the changes done to the nRF54H20 SoC DTS files.

Required changes

The following changes are mandatory to make your application work in the same way as in previous releases.

This section describes the changes related to samples and applications.

Samples and applications

General

  • Sysbuild A new build system was recently introduced in nRF Connect SDK For more information, see the Migrating to sysbuild user guide.

  • Hardware Model v2 The hardware model was introduced in the nRF Connect SDK v2.7.0.

Applications using the dfu_application.zip file

For all applications using the dfu_application.zip file generated by the nRF Connect SDK build system:

  • Make sure that your DFU host tools support the dfu_application.zip file with the new format version (1). If the tools do not support the new format version and you cannot update them, you can manually align the content of the zip archive generated with format version 1 to version 0:

    • Build your application in the same configuration with the nRF Connect SDK v2.6 release to obtain a reference file dfu_application.zip with format version 0.

    • Manually align the content of the dfu_application.zip file generated with format version 1:

      • Align the properties described in the manifest.json file. Make sure to update all of the fields that are used by the selected DFU host tool.

      • Rename the binary files that are included in the zip archive to match the file names used by the updated manifest. The binary file content is interoperable across nRF Connect SDK releases.

Devicetree

  • Many devicetree nodes have been re-labeled for consistency. Some nodes have undergone more substantial changes, which are explained in later parts of this section. The following table lists node labels that are no longer used and their equivalent or functionally similar nodes in the revised nRF54H20 DTS files. All old names must be updated in DTS files (overlays, custom boards, or both) and application code.

    Old labels

    New labels

    Notes

    bellboard_cpuapp

    cpuapp_bellboard

    bellboard_cpurad

    cpurad_bellboard

    bellboard_cpusec

    cpusec_bellboard

    clic_cpuppr

    cpuppr_clic

    cpuapp_ram0x_ns

    cpuapp_cpurad_ram0x_region

    Multiple labels had been used.

    cpurad_ram0x_ns

    ipc_shm_area_cpuapp_cpurad

    cpuapp_ram0x_s

    cpuapp_ram0x_region

    cpuapp_sram0x

    cpuapp_data

    cpuppr

    cpuppr_vpr

    cpuppr_sram

    cpuppr_code_data

    cpurad_ram0x_s

    cpurad_ram0x_region

    ieee802154

    cpurad_ieee802154

    ipc_cpuapp

    cpuapp_cpurad_ipc

    Specific to Radiocore.

    ipc_cpurad

    Specific to Application.

    ipc_shm_cpuapp_cpuppr

    cpuapp_cpuppr_ipc_shm

    ipc_shm_cpuapp_cpurad

    cpuapp_cpurad_ipc_shm

    ipc_shm_cpuapp_cpusec

    cpuapp_cpusec_ipc_shm

    ipc_shm_cpuapp_cpusys

    cpuapp_cpusys_ipc_shm

    ipc_shm_cpuppr_cpuapp

    cpuppr_cpuapp_ipc_shm

    ipc_shm_cpurad_cpuapp

    cpurad_cpuapp_ipc_shm

    ipc_shm_cpurad_cpusec

    cpurad_cpusec_ipc_shm

    ipc_shm_cpurad_cpusys

    cpurad_cpusys_ipc_shm

    ipc_shm_cpusec_cpuapp

    cpusec_cpuapp_ipc_shm

    ipc_shm_cpusec_cpurad

    cpusec_cpurad_ipc_shm

    ipc_shm_cpusys_cpuapp

    cpusys_cpuapp_ipc_shm

    ipc_shm_cpusys_cpurad

    cpusys_cpurad_ipc_shm

    ipc_to_cpusec

    cpusec_cpuapp_ipc

    Specific to Application.

    cpusec_cpurad_ipc

    Specific to Radiocore.

    mram0

    cpuapp_rx_partitions

    Specific to Application.

    cpurad_rx_partitions

    Specific to Radiocore.

    mram1

    cpuapp_rw_partitions

    Specific to Application.

    mram10

    mram1x

    Covers both MRAM10 and MRAM11 as one contiguous area.

    mram11

    mram10_nvr

    cpuapp_uicr

    Used to have multiple reg values.

    cpurad_uicr

    ficr

    ram20_shared_region

    shared_ram20_region

    ram3x_cpuapp

    cpuapp_dma_region

    ram3x_cpurad

    cpurad_dma_region

    Linker section is also renamed from DMA_RAM3x_NET to DMA_RAM3x_RAD.

    ram3x_dma_region

    shared_ram3x_region

    rng

    prng

    slot0_partition

    cpuapp_slot0_partition

    Specific to Application.

    cpurad_slot0_partition

    Specific to Radiocore.

    sram0

    cpuapp_ram0

    Specific to Application.

    cpurad_ram0

    Specific to Radiocore.

    vevif_cpuppr

    cpuppr_vevif

    vevif_cpusys

    cpusys_vevif

  • All /chosen properties specific to nRF54H20 have been removed. In case some of these are used in your application code, some suitable replacements are noted in the table below.

    Removed choice

    Notes

    nordic,bellboard-cpuapp

    Use node label cpuapp_bellboard.

    nordic,bellboard-cpurad

    Use node label cpurad_bellboard.

    nordic,bellboard-cpusec

    Use node label cpusec_bellboard.

    nordic,tdd-etr-buffer

    To be replaced in a later version of NCS.

    nrf,hsfll

    Use node label cpuapp_hsfll or cpurad_hsfll.

    nrf,resetinfo

    Use alias resetinfo.

    nrf,tz-secure-image

    Use chosen zephyr,code-partition.

    nrf,tz-non-secure-image

    nrf,uicr

    Use node label cpuapp_uicr or cpurad_uicr.

    nrf,uicr-ext

    Use property ptr-ext-uicr of UICR node.

  • In the board DTS file for the nRF54H20 DK, only the following peripherals are enabled:

    Target

    Labels

    cpuapp

    grtc, uart136, cpuapp_bellboard, cpurad_bellboard, cpusys_vevif, can120, exmif, gpio0, gpio6, gpio9, gpiote130, pwm130, usbhs

    cpurad

    grtc, uart135, cpuapp_bellboard, cpurad_bellboard, cpusys_vevif, dppic130*, dppic132*, ipct130*

    cpuppr

    grtc, uart135

    • A peripheral is enabled at the SoC level in ncs/zephyr/dts/arm/nordic/nrf54h20_cpurad.dtsi

    • Some peripherals are no longer enabled by default.

      This means that custom boards and applications that relied on certain peripherals being implicitly enabled, must now explicitly set status = "okay" on the respective nodes in the board DTS or overlay files. In the SoC DTS for the nRF54H20 DK, all peripherals are disabled, except where noted above.

    • UART output is now enabled by default for all cores. However, when using a custom board, the default baud rate (current-speed property) should be set in the board DTS, as it is no longer set in the SoC DTS.

  • Memory map:

    • Each memory region must now set status = "okay" in order to be included for UICR generation.

    • For the nRF54H20 DK, the default memory regions are defined in ncs/zephyr/boards/nordic/nrf54h20dk/nrf54h20dk_nrf54h20-memory_map.dtsi. All of them have status = "disabled" initially, which allows them to be specified in a common location. Some of them are only enabled for particular cores or relevant samples.

    • Migrating SRAM region definitions:

      • Example before:

        / {
   soc {
      ram0x: memory@2f000000 {
         reg = <0x2f000000 DT_SIZE_K(768)>;
         ranges = <0 0x2f000000 0xc0000>;
         ...
         cpuapp_ram0x_s: memory@10000 {
            compatible = "nordic,allocatable-ram";
            reg = <0x10000 DT_SIZE_K(260)>;
            perm-read;
            perm-write;
            perm-secure;
            #address-cells = <1>;
            #size-cells = <1>;
            ranges = <0x0 0x10000 0x41000>;
            ipc_shm_area_cpusec_cpuapp: memory@0 {
               reg = <0x0 DT_SIZE_K(4)>;
               #address-cells = <1>;
               #size-cells = <1>;
               ranges = <0x0 0x0 DT_SIZE_K(4)>;
               ipc_shm_cpusec_cpuapp: memory@0 {
                  reg = <0x0 DT_SIZE_K(2)>;
               };
               ipc_shm_cpuapp_cpusec: memory@800 {
                  reg = <0x800 DT_SIZE_K(2)>;
               };
            };
         };
      };
   };
};

      • Example after:

        / {
   reserved-memory {
      cpuapp_ram0x_region: memory@2f010000 {
         compatible = "nordic,owned-memory";
         reg = <0x2f010000 DT_SIZE_K(260)>;
         perm-read;
         perm-write;
         perm-secure;
         #address-cells = <1>;
         #size-cells = <1>;
         ranges = <0x0 0x2f010000 0x41000>;
         cpusec_cpuapp_ipc_shm: memory@0 {
            reg = <0x0 DT_SIZE_K(2)>;
         };
         cpuapp_cpusec_ipc_shm: memory@800 {
            reg = <0x800 DT_SIZE_K(2)>;
         };
      };
   };
};

        The nordic,allocatable-ram binding has been removed and is replaced here with nordic,owned-memory, which supports the same ownership/permission properties. For more information, see ncs/zephyr/dts/bindings/reserved-memory/nordic,owned-memory.yaml.

        Like before, these SRAM regions can be defined anywhere in the DTS, but it is recommended to place them under the /reserved-memory node. The global RAM nodes for ram0x (and others) no longer exist, so the regions should use absolute addresses.

    • Migrating MRAM partition definitions:

      • Example before:

        &mram_controller {
   mram0: mram@e0a6000 {
      compatible = "nordic,allocatable-mram", "soc-nv-flash";
      reg = <0xe0a6000 DT_SIZE_K(360)>;
      erase-block-size = <4096>;
      write-block-size = <1>;
      perm-read;
      perm-execute;
      perm-secure;
      partitions {
         compatible = "fixed-partitions";
         #address-cells = <1>;
         #size-cells = <1>;
         slot0_partition: partition@a6000 {
            reg = <0xa6000 DT_SIZE_K(296)>;
         };
         ppr_code_partition: partition@f0000 {
            reg = <0xf0000 DT_SIZE_K(64)>;
         };
      };
   };
   mram1: mram@e100000 {
      compatible = "nordic,allocatable-mram", "soc-nv-flash";
      reg = <0xe100000 DT_SIZE_K(916)>;
      erase-block-size = <4096>;
      write-block-size = <1>;
      perm-read;
      perm-write;
      partitions {
         compatible = "fixed-partitions";
         #address-cells = <1>;
         #size-cells = <1>;
         dfu_partition: partition@100000 {
            reg = < 0x100000 DT_SIZE_K(892) >;
         };
         storage_partition: partition@1df000 {
            reg = < 0x1df000 DT_SIZE_K(24) >;
         };
      };
   };
};

      • Example after:

        &mram1x {
   cpuapp_rx_partitions: cpuapp-rx-partitions {
      compatible = "nordic,owned-partitions", "fixed-partitions";
      perm-read;
      perm-execute;
      perm-secure;
      #address-cells = <1>;
      #size-cells = <1>;
      cpuapp_slot0_partition: partition@a6000 {
         reg = <0xa6000 DT_SIZE_K(296)>;
      };
      cpuppr_code_partition: partition@f0000 {
         reg = <0xf0000 DT_SIZE_K(64)>;
      };
   };
   cpuapp_rw_partitions: cpuapp-rw-partitions {
      compatible = "nordic,owned-partitions", "fixed-partitions";
      perm-read;
      perm-write;
      perm-secure;
      #address-cells = <1>;
      #size-cells = <1>;
      dfu_partition: partition@100000 {
         reg = < 0x100000 DT_SIZE_K(892) >;
      };
      storage_partition: partition@1df000 {
         reg = < 0x1df000 DT_SIZE_K(24) >;
      };
   };
};

        All MRAM partitions must now be organized under the mram1x node, which spans both MRAM10 and MRAM11. The mram_controller node has been removed.

        The nordic,allocatable-mram binding has been removed and is replaced here with nordic,owned-partitions, which no longer derives from soc-nv-flash. For more information, see ncs/zephyr/dts/bindings/mtd/nordic,owned-partitions.yaml.

        Without the old mram nodes in between, all partition offsets are now correctly expressed as relative to mram1x. The only limitation is that it is no longer possible to assign a different erase-block-size per MRAM region.

  • IPC configuration:

    • For the nRF54H20 DK, the default IPC nodes are defined in ncs/zephyr/boards/nordic/nrf54h20dk/nrf54h20dk_nrf54h20-ipc_conf.dtsi. There is exactly one node for each relevant pair of processors, such as cpuapp_cpurad_ipc. Each node also sets the channel numbers for both directions of communication.

    • Local bellboards require additional configuration to receive events from remote cores. Example configuration for Application core:

      &cpuapp_bellboard {
   interrupts = <96 NRF_DEFAULT_IRQ_PRIORITY>;
   interrupt-names = "irq0";
   /* irq0: 0: cpuapp-cpusec, 6: cpuapp-cpusys, 13: cpuapp-cpuppr, 18: cpuapp-cpurad */
   nordic,interrupt-mapping = <0x00042041 0>;
};

      The nordic,interrupt-mapping property must be kept in sync with the other IPC nodes in DTS, which contain mboxes specifiers. Here, the property consists of a channel bitmask for interrupt index 0, where for every specifier of the form <&cpuapp_bellboard N>, the Nth bit is set. For more information, see ncs/zephyr/dts/bindings/mbox/nordic,nrf-bellboard-local.yaml.

    • Configuring a bellboard instance with multiple IRQ lines previously required multiple nodes with compatible = "nordic,mbox-nrf-ids". Now, this compatible property has been removed, and IRQ information can be attached to the actual bellboard node.

      • Example before:

        &global_peripherals {
   mbox_local_0: mbox0@9a000 {
      compatible = "nordic,mbox-nrf-ids";
      reg = <0x9a000 0x1000>;
      interrupts = <96 NRF_DEFAULT_IRQ_PRIORITY>;
      instance = <0>;
      #mbox-cells = <1>;
   };
   mbox_local_1: mbox1@9a000 {
      compatible = "nordic,mbox-nrf-ids";
      reg = <0x9a000 0x1000>;
      interrupts = <97 NRF_DEFAULT_IRQ_PRIORITY>;
      instance = <1>;
      #mbox-cells = <1>;
   };
};

      • Example after:

        &cpuapp_bellboard {
   interrupts = <96 NRF_DEFAULT_IRQ_PRIORITY>, <97 NRF_DEFAULT_IRQ_PRIORITY>;
   interrupt-names = "irq0", "irq1";
   nordic,interrupt-mapping = <0x0000000f 0>, /* irq0 (#96) handles channels 0-3 */
                              <0x000000f0 1>; /* irq1 (#97) handles channels 4-7 */
};

  • VPR co-processors:

    • Two properties of nordic,nrf-vpr-coprocessor nodes have been updated:

      • loader-img-src is renamed to source-memory.

      • loader-img-dst is renamed to execution-memory. The size of this region can be less than or equal to that of source-memory (if set).

    • Mapping global peripheral interrupts to a VPR can now be described using standard devicetree properties. The custom global-irqs property has been removed.

      • Example before:

        &spi130 {
   status = "reserved";
   global-irqs = <421 421 13>;
};

      • Example after:

        &spi130 {
   status = "reserved";
   interrupt-parent = <&cpuppr_clic>;
};

        This can be placed in Application core’s DTS, in order to map the SPI130 IRQ from Application to PPR.

  • Buttons on a custom board may need to include the new zephyr,code property. The nRF54H20 DK uses the values INPUT_KEY_0 through INPUT_KEY_3. See ncs/zephyr/include/zephyr/dt-bindings/input/input-event-codes.h for all supported values.

Matter

With the inheritance of Zephyr’s sysbuild in the |NCS|, some changes are provided to the Matter samples and applications:

  • CONFIG_CHIP_FACTORY_DATA_BUILD Kconfig option is deprecated and you need to use the SB_CONFIG_MATTER_FACTORY_DATA_GENERATE Kconfig option instead to enable or disable creating the factory data set during building a Matter sample. To enable factory data support on your device, you still need to set the CONFIG_CHIP_FACTORY_DATA to y.

  • Factory data output files are now located in the <application_name>/zephyr/ directory within the build directory.

  • CONFIG_CHIP_FACTORY_DATA_MERGE_WITH_FIRMWARE Kconfig option is deprecated in sysbuild and you need to use the SB_CONFIG_MATTER_FACTORY_DATA_MERGE_WITH_FIRMWARE Kconfig option instead to enable or disable merging the factory data HEX file with the final firmware HEX file.

  • SB_CONFIG_MATTER_OTA Kconfig option has been added to enable or disable generating Matter OTA package during the building process.

  • CONFIG_CHIP_OTA_IMAGE_FILE_NAME Kconfig option is deprecated and you need to use the SB_CONFIG_MATTER_OTA_IMAGE_FILE_NAME Kconfig option instead to define Matter OTA output filename.

Note

If you want to build a sample without using sysbuild, you need to use the old Kconfig options.

Libraries

This section describes the changes related to libraries.

MQTT helper library

For applications using the MQTT helper library:

  • The CONFIG_MQTT_HELPER_CERTIFICATES_FILE is now replaced by CONFIG_MQTT_HELPER_CERTIFICATES_FOLDER. The new option is a folder path where the certificates are stored. The folder path must be relative to the root of the project.

    If you are using the MQTT helper library, you must update the Kconfig option to use the new option.

  • When using the CONFIG_MQTT_HELPER_PROVISION_CERTIFICATES Kconfig option, the certificate files must be in standard PEM format. This means that the PEM files need not be converted to string format anymore.

FEM abstraction layer

For applications using FEM abstraction layer: