.. _migration_cs3_to_to_2_7_app:

Migrate your application for the nRF54H20 DK to |NCS| v2.7.0 (for v2.4.99-cs3 users)
####################################################################################

.. contents::
   :local:
   :depth: 2

This document describes the changes you should be aware of when migrating your application from the |NCS| v2.4.99-cs3 to the |NCS| v2.7.0.

Overview
********

|NCS| 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 |NCS| toolchain
  The |NCS| toolchain has been updated.
  See :ref:`transition_cs3_to_2_7_env` for more info on how to upgrade your current |NCS| installation based on version 2.4.99-cs3.

Sysbuild
  A new build system was recently introduced in the |NCS|.
  For more information, see the :ref:`Migrating to sysbuild <child_parent_to_sysbuild_migration>` userguide.

Hardware Model v2
  A new hardware model was recently introduced in the |NCS|.
  For more information, see :ref:`hwmv1_to_v2_migration`.

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.

SDFW and SCFW firmware bundle
  The Secure Domain Firmware (SDFW) and System Controller Firmware (SCFW) are no longer built from the source during the application build process.
  They are provided as a firmware bundle (v0.5.0) and provisioned to the nRF54H20 during the bring-up steps.
  The nRF54H20 DK must be in lifecycle state ``EMPTY`` to be provisioned with the new firmware bundle.
  For additional details, see :ref:`transition_cs3_to_2_7_env_bringup`.

nRF Util is now the main command line backend utility.
  nRF Command Line Tools still remains as a general |NCS| requirement.

Updated boards
  SOC1-based boards have been removed and FP1-based board have been added.
  The board names for the Application, Radio, and PPR core have been updated.

Lifecycle State changes
  To correctly operate the nRF54H20 DK, its lifecycle state must be set to ``RoT`` after the bring-up.

  Also, it is no longer possible to perform an unauthenticated backward LCS transitions.
  This means that once set to ``RoT``, it is no longer possible to revert to LCS state ``EMPTY``.

.. note::
   Not all the features supported in |NCS| v2.4.99-cs3 have been ported to v2.7.0.
   Additional features will be provided in future releases.

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

.. toggle::

   * The nRF54H20 DK samples and applications are now using the following FP1-based board names:

     * Application core: ``nrf54h20dk_nrf54h20_cpuapp`` (Previously ``nrf54h20pdk_nrf54h20_cpuapp@soc1``)
     * Radio core: ``nrf54h20dk_nrf54h20_cpurad`` (Previously ``nrf54h20pdk_nrf54h20_cpurad@soc1``)
     * PPR core: ``nrf54h20dk_nrf54h20_cpuppr`` (Previously ``nrf54h20pdk_nrf54h20_cpuppr@soc1``)

     The previously used SOC1-based board files have been removed.

   * Sysbuild
     A new build system was recently introduced in |NCS|
     For more information, see the :ref:`Migrating to sysbuild <child_parent_to_sysbuild_migration>` userguide.

   * Hardware Model v2
     A new hardware model was recently introduced in the |NCS|.
     For more information, see :ref:`hwmv1_to_v2_migration`.

Applications using the :file:`dfu_application.zip` file
-------------------------------------------------------

.. toggle::

   For all applications using the :file:`dfu_application.zip` file generated by the |NCS| build system:

     * Make sure that your DFU host tools support the :file:`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 |NCS| v2.6 release to obtain a reference file :file:`dfu_application.zip` with format version ``0``.
       * Manually align the content of the :file:`dfu_application.zip` file generated with format version ``1``:

         * Align the properties described in the :file:`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 |NCS| releases.

Devicetree
----------

.. toggle::

  * 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 label(s)                   | New label(s)                   | 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 :file:`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 :file:`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:

        .. code-block:: devicetree

           / {
              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:

        .. code-block:: devicetree

           / {
              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 :file:`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:

        .. code-block:: devicetree

           &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:

        .. code-block:: devicetree

           &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 :file:`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 :file:`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:

      .. code-block:: devicetree

         &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 :file:`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:

        .. code-block:: devicetree

           &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:

        .. code-block:: devicetree

           &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:

        .. code-block:: devicetree

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

      * Example after:

        .. code-block:: devicetree

           &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 :file:`ncs/zephyr/include/zephyr/dt-bindings/input/input-event-codes.h` for all supported values.

Matter
------

.. toggle::

   With the inheritance of Zephyr's :ref:`sysbuild in the |NCS| <configuration_system_overview_sysbuild>`, some changes are provided to the Matter samples and applications:

     * :kconfig:option:`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 :kconfig:option:`CONFIG_CHIP_FACTORY_DATA` to ``y``.
     * Factory data output files are now located in the ``<application_name>/zephyr/`` directory within the build directory.
     * :kconfig:option:`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.
     * :kconfig:option:`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.

Security
========

.. toggle::

   * For samples using ``CONFIG_NRF_SECURITY``:

     * RSA keys are no longer enabled by default.
       This reduces the code size by 30 kB if not using RSA keys.
       This also breaks the configuration if using the RSA keys without explicitly enabling an RSA key size.
       Enable the required key size to fix the configuration, for example by setting the Kconfig option :kconfig:option:`CONFIG_PSA_WANT_RSA_KEY_SIZE_2048` if 2048-bit RSA keys are required.

     * The PSA config is now validated by the :file:`ncs/nrf/ext/oberon/psa/core/library/check_crypto_config.h` file.
       Users with invalid configurations must update their PSA configuration according to the error messages that the :file:`check_crypto_config.h` file provides.

   * For the :ref:`crypto_persistent_key` sample:

     * The Kconfig option ``CONFIG_PSA_NATIVE_ITS`` is replaced by the Kconfig option :kconfig:option:`CONFIG_TRUSTED_STORAGE`, which enables the new :ref:`trusted_storage_readme` library.
       The :ref:`trusted_storage_readme` library provides the PSA Internal Trusted Storage (ITS) API for build targets without TF-M.
       It is not backward compatible with the previous PSA ITS implementation.
       Migrating from the PSA ITS implementation, enabled by the ``CONFIG_PSA_NATIVE_ITS`` option, to the new :ref:`trusted_storage_readme` library requires manual data migration.

   * For :ref:`lib_wifi_credentials` library and Wi-Fi samples:

     * ``CONFIG_WIFI_CREDENTIALS_BACKEND_PSA_UID_OFFSET`` has been removed because it was specific to the previous solution that used PSA Protected Storage instead of PSA Internal Trusted Storage (ITS).
       Use :kconfig:option:`CONFIG_WIFI_CREDENTIALS_BACKEND_PSA_OFFSET` to specify the key offset for PSA ITS.
       Be aware that Wi-Fi credentials stored in Protected Storage will not appear in ITS when switching.
       To avoid re-provisioning Wi-Fi credentials, manually read out the old credentials from Protected Storage in the previously used UID and store to ITS.

zcbor
=====

.. toggle::

   * If you have zcbor-generated code that relies on the zcbor libraries through Zephyr, you must regenerate the files using zcbor 0.8.1.
     Note that the names of generated types and members has been overhauled, so the code using the generated code must likely be changed.

     For example:

      * Leading single underscores and all double underscores are largely gone.
      * Names sometimes gain suffixes like ``_m`` or ``_l`` for disambiguation.
      * All enum (choice) names have now gained a ``_c`` suffix, so the enum name no longer matches the corresponding member name exactly (because this previously broke the C++ namespace rules).

    * The functions :c:func:`zcbor_new_state`, :c:func:`zcbor_new_decode_state` and the macro :c:macro:`ZCBOR_STATE_D` have gained new parameters related to the decoding of unordered maps.
      If you are not using this functionality, you can set the functions and the macro to ``NULL`` or ``0``.
    * The functions :c:func:`zcbor_bstr_put_term` and :c:func:`zcbor_tstr_put_term` have gained a new parameter ``maxlen``, referring to the maximum length of the parameter ``str``.
      This parameter is passed directly to :c:func:`strnlen` under the hood.
    * The function :c:func:`zcbor_tag_encode` has been renamed to :c:func:`zcbor_tag_put`.
    * Printing has been changed significantly, for example, :c:func:`zcbor_print` is now called :c:func:`zcbor_log`, and :c:func:`zcbor_trace` with no parameters is gone, and in its place are :c:func:`zcbor_trace_file` and :c:func:`zcbor_trace`, both of which take a ``state`` parameter.

Libraries
=========

This section describes the changes related to libraries.

MQTT helper library
-------------------

.. toggle::

   For applications using the :ref:`lib_mqtt_helper` library:

     * The ``CONFIG_MQTT_HELPER_CERTIFICATES_FILE`` is now replaced by :kconfig:option:`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 :ref:`lib_mqtt_helper` library, you must update the Kconfig option to use the new option.

     * When using the :kconfig:option:`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
---------------------

.. toggle::

   For applications using :ref:`fem_al_lib`:

     * The function :c:func:`fem_tx_power_control_set` replaces the function :c:func:`fem_tx_gain_set`.
     * The function :c:func:`fem_default_tx_output_power_get` replaces the function :c:func:`fem_default_tx_gain_get`.

Recommended changes
*******************

The following changes are recommended for your application to work optimally after the migration.

General
=======

.. toggle::

   * Applications that use :file:`prj_<board>.conf` Kconfig configurations should be transitioned to using :file:`boards/<board>.conf` Kconfig fragments.

Samples and applications
========================

Applications using build types
------------------------------

.. toggle::

   For applications using build types:

     * The :makevar:`CONF_FILE` used for :ref:`app_build_additions_build_types` is now deprecated and is being replaced with the :makevar:`FILE_SUFFIX` variable, inherited from Zephyr.
       You can read more about it in :ref:`app_build_file_suffixes`, :ref:`cmake_options`, and the :ref:`related Zephyr documentation <zephyr:application-file-suffixes>`.
       If your application uses build types, it is recommended to update the :file:`sample.yaml` to use the new variable instead of :makevar:`CONF_FILE`.

   For applications using child images:

     * With the inheritance of Zephyr's :ref:`sysbuild in the |NCS| <configuration_system_overview_sysbuild>`, the :ref:`ug_multi_image` are deprecated.
       If your application uses parent and child images, it is recommended to migrate your application to sysbuild before the multi-image builds are removed in one of the upcoming |NCS| releases.
       See :ref:`child_parent_to_sysbuild_migration`.
       See the :ref:`documentation in Zephyr <zephyr:sysbuild>` for more information about sysbuild.

Matter
------

.. toggle::

   * For the Matter samples and applications:
      * All Partition Manager configuration files (:file:`pm_static` files) have been removed from the :file:`configuration` directory.
        Instead, a :file:`pm_static_<BOARD>` file has been created for each target board and placed in the samples' directories.
        Setting the ``PM_STATIC_YML_FILE`` argument in the :file:`CMakeLists.txt` file has been removed, as it is no longer needed.

      * Configuration files :file:`Kconfig.mcuboot.defaults`, :file:`Kconfig.hci_ipc.defaults`, and :file:`Kconfig.multiprotocol_rpmsg.defaults` that stored a default configuration for the child images have been removed.
        This was done because of the :ref:`configuration_system_overview_sysbuild` integration and the child images deprecation.

        The Matter samples and applications have been migrated to use sysbuild, though you can still use the child images.
        To migrate an application from the previous to the new version and keep using child images, complete the following steps:

        1. Copy the content of the image configuration file :file:`prj.conf` located in the :file:`sysbuild/<image_name>` directory (for example, :file:`sysbuild/mcuboot`) to the :file:`prj.conf` file located in the :file:`child_image/<image_name>` directory.
        #. Copy the content of the board configuration file located in the :file:`sysbuild/<image_name>/boards` directory (for example, :file:`sysbuild/mcuboot/boards/nrf52840dk_nrf52840.conf`) to the board file located in the :file:`child_image/<image_name>/boards` directory.

      * All Partition Manager configuration files (:file:`pm_static` files) with the suffix ``release`` have been removed from all samples.
        Those files are now redundant, since the new build system allows using the file without the additional suffix if you use :makevar:`FILE_SUFFIX` and it is available in the project's directory.

        For example, if you add ``-DFILE_SUFFIX=release`` to the CMake arguments while building an |NCS| Matter sample on the ``nrf52840dk/nrf52840`` target, the file :file:`pm_static_nrf52840dk_nrf52840.yaml` will be used as a fallback.
        This means that the file :file:`pm_static_nrf52840dk_nrf52840_release.yaml` with the exact same contents is not needed anymore.
        The :makevar:`CONF_FILE` argument is deprecated, but if you want to keep using it within your project, you need to create the :file:`pm_static_nrf52840dk_nrf52840_release.yaml` file and copy the content of the :file:`pm_static_nrf52840dk_nrf52840.yaml` file to it.

Libraries
=========

This section describes the changes related to libraries.

LwM2M carrier library
---------------------

.. toggle::

   * Many event defines have received new values.
     If you are using the values directly in your application, you need to check the events listed in :file:`lwm2m_carrier.h`.

Application migration examples
******************************

The following are examples of the changes that were introduced to certain applications to migrate them to the |NCS| v2.7.0.

CoreMark
========

Several changes have been made to migrate the :ref:`coremark_sample` sample to the |NCS| v2.7.0:

* The build system has been aligned to the hardware model v2.
* Because the |NCS| v2.7.0 does not support ARM Coresight System Trace Macrocell (STM) logging for the nRF54 device, STM logging has been removed from the sample.
  The sample now uses usual UART logging, which allows for sending logs from only one core for each UART instance.
  The nRF54 device has only two UART instances, so the sample can now be run on two cores at most.
  The sample is always run on the application core, and depending on configuration, it can be run on either the radio core or the PPR core.
  See the ``SB_CONFIG_APP_CPUNET_RUN`` and ``SB_CONFIG_APP_CPUPPR_RUN`` Kconfig options for more details.
* The DTS overlays have been updated:

  * The PPR core memory region no longer needs to be defined in the DTS overlay.
  * The ``cpuppr`` and ``clic_cpuppr`` nodes no longer needs to be enabled in the application DTS overlay.
  * The ``ieee802154_app`` and ``rng`` nodes no longer needs to be disabled in the application DTS overlay.
  * The GPIOTE channels allocation has been aligned to their availability.
* The :file:`system_nrf.h` library has been included explicitly in the :file:`main.c` file to print the CPU frequency.
* The ``SB_CONFIG_PARTITION_MANAGER`` Kconfig option has been disabled in the :file:`sysbuild.conf` file to avoid conflicts with the Partition Manager.
* The :kconfig:option:`CONFIG_APP_MODE_FLASH_AND_RUN` Kconfig option has been made promptless and enabled for the PPR core.
  Currently, the PPR core does not have access to buttons and thus, the :kconfig:option:`CONFIG_APP_MODE_FLASH_AND_RUN` Kconfig option must be enabled for this core to run the benchmark.
* The PPR core is now run from PPR TCM (Tightly Coupled Memory) RAM for better CPU performance.
  This configuration differs from the one in the nRF54 customer sampling release v2.4.99-cs3, where the PPR core is run from MRAM with the execution in place (XIP) method.
* To make the sample run on the PPR core, pass the ``-DSB_CONFIG_APP_CPUNET_RUN=n -DSB_CONFIG_APP_CPUPPR_RUN=y -Dcoremark_SNIPPET=nordic-ppr`` build-time arguments to the build system.
  The ``coremark_SNIPPET`` argument is set to make the application core start the PPR core.
  Alternatively, you can build the sample from the :file:`sample.yaml` file using the following command:

  .. code-block:: console

     west build -p -b nrf54h20dk/nrf54h20/cpuapp -T sample.benchmark.coremark_ppr .

nRF Desktop
===========

Several changes have been made to migrate the :ref:`nrf_desktop` application to the |NCS| v2.7.0:

* The :ref:`ipc_radio` image is a universal network core image serves are a substitute for the  ``hci_ipc``, :ref:`ble_rpc_host`, and IEEE 802.15.4 remote images from the deprecated ``sdk-nrf-next`` repository.
  Due to this, the radio core now uses the :ref:`ipc_radio` application from ``sdk-nrf`` instead of the ``hci_rpmsg`` sample from ``sdk-zephyr``.

  The radio core image configuration files have been moved from the :file:`configuration/nrf54h20dk_nrf54h20_cpuapp/child_image/hci_rpmsg` directory to the :file:`configuration/nrf54h20dk_nrf54h20_cpurad/images/ipc_radio` directory.

* Due to transition to sysbuild, the configuration enabling the radio core image has been moved from the main application image configuration to the sysbuild configuration.
* The :file:`dfu_mcumgr_suit.c` module has been merged with :file:`dfu_mcumgr.c`.
  The ``CONFIG_DESKTOP_DFU_MCUMGR_SUIT_ENABLE`` Kconfig option had been removed and replaced by :ref:`CONFIG_DESKTOP_DFU_BACKEND_SUIT <config_desktop_app_options>`.
  The :file:`dfu_mcumgr_suit.c` is no longer needed as in |NCS| v2.7 the dfu_mcumgr module can be properly adapted to support the SUIT DFU.
* The USB High-Speed is supported only in the USB-next stack.
  New USB-next stack has been integrated into the nRF Desktop application and can be enabled using the :kconfig:option:`CONFIG_DESKTOP_USB_STACK_NEXT` Kconfig option.
  It is now enabled by default in the nRF54H20 DK configurations.
  An USB HID-class instance is now configured through a separate DTS node compatible with ``zephyr,hid-device``.
  See :ref:`nrf_desktop_usb_state` documentation for details related to USB-next stack integration.
* Aligned flash memory writes in the :ref:`nrf_desktop_dfu` to the flash memory write block size of the non-volatile memory.
  This is needed because the :ref:`CONFIG_SOC_FLASH_NRF_MRAM_ONE_BYTE_WRITE_ACCESS <config_desktop_app_options>` Kconfig option is no longer available and MRAMC requires writes of the size of the whole MRAM word to the MRAM.
