.. _migration_2_6_99_cs2_to_2_7_app:

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

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

This document describes the changes you should be aware of when migrating your application from the |NCS| v2.6.99-cs2 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.

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

SDFW and SCFW firmware bundle
  A new version (v0.5.0) of the SDFW and SCFW firmware bundle was released.
  This is the only version compatible with the |NCS| v2.7.0.
  The nRF54H20 DK must be in lifecycle state ``EMPTY`` to be provisioned with the new firmware bundle.

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

.. toggle::

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

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.

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