diff --git a/applications/machine_learning/app_desc.rst b/applications/machine_learning/app_desc.rst index e745e9ba2701..a6959c9d4edb 100644 --- a/applications/machine_learning/app_desc.rst +++ b/applications/machine_learning/app_desc.rst @@ -437,6 +437,8 @@ nRF54H20 DK west build -b nrf54h20dk/nrf54h20/cpuapp -T applications.machine_learning.sensor_hub.zdebug . + .. include:: /includes/nRF54H20_erase_UICR.txt + Selecting a build type ====================== diff --git a/applications/matter_weather_station/README.rst b/applications/matter_weather_station/README.rst index 7a72d407a261..f916bc8d1b8b 100644 --- a/applications/matter_weather_station/README.rst +++ b/applications/matter_weather_station/README.rst @@ -223,7 +223,7 @@ To build this application to work with the nRF7002 Wi-Fi expansion board: Generating factory data ======================= -To enable factory data support, you need to select the ``overlay-factory_data`` configuration overlay from the available application :ref:`build configuration overlays `, set the :kconfig:option:`SB_CONFIG_MATTER_FACTORY_DATA_GENERATE` kconfig option to ``y``, and use the ``factory_data`` file suffix. +To enable factory data support, you need to select the ``overlay-factory_data`` configuration overlay from the available application :ref:`build configuration overlays `, set the ``SB_CONFIG_MATTER_FACTORY_DATA_GENERATE`` kconfig option to ``y``, and use the ``factory_data`` file suffix. You can generate new factory data set when building for the given board target by invoking the following command: .. code-block:: console diff --git a/applications/nrf_desktop/bootloader_dfu.rst b/applications/nrf_desktop/bootloader_dfu.rst index 6f1088010c66..b407c3d26c6e 100644 --- a/applications/nrf_desktop/bootloader_dfu.rst +++ b/applications/nrf_desktop/bootloader_dfu.rst @@ -212,13 +212,13 @@ You can also enable :kconfig:option:`CONFIG_SUIT_DFU_CANDIDATE_PROCESSING_MINIMA SUIT also has the following options in the sysbuild configuration: - * :kconfig:option:`SB_CONFIG_SUIT_ENVELOPE` - Required to create the SUIT envelope. + * ``SB_CONFIG_SUIT_ENVELOPE`` - Required to create the SUIT envelope. Turned on by default on the ``nrf54h20dk`` board. The envelope is used directly as a DFU update file by the DFU tools. - * :kconfig:option:`SB_CONFIG_SUIT_ENVELOPE_SEQUENCE_NUM` - The nRF Desktop application uses the sequence number to define an application version. + * ``SB_CONFIG_SUIT_ENVELOPE_SEQUENCE_NUM`` - The nRF Desktop application uses the sequence number to define an application version. .. note:: - The :kconfig:option:`SB_CONFIG_SUIT_ENVELOPE_SIGN` is disabled, so the generated SUIT envelope is not signed. + The ``SB_CONFIG_SUIT_ENVELOPE_SIGN`` is disabled, so the generated SUIT envelope is not signed. On the ``nrf54h20dk`` board, the dedicated DFU partition called ``dfu_partition`` is defined by default in the DTS. The partition is used to store the incoming SUIT envelope with an update candidate. diff --git a/applications/nrf_desktop/description.rst b/applications/nrf_desktop/description.rst index eb93031ff39d..5592bd277a1e 100644 --- a/applications/nrf_desktop/description.rst +++ b/applications/nrf_desktop/description.rst @@ -892,6 +892,8 @@ The nRF Desktop application is built the same way to any other |NCS| application .. include:: /includes/build_and_run.txt +.. include:: /includes/nRF54H20_erase_UICR.txt + .. note:: Information about the known issues in nRF Desktop can be found in |NCS|'s :ref:`release_notes` and on the :ref:`known_issues` page. diff --git a/doc/nrf/config_and_build/bootloaders/bootloader_adding_sysbuild.rst b/doc/nrf/config_and_build/bootloaders/bootloader_adding_sysbuild.rst index 89023b530d09..008134b9133b 100644 --- a/doc/nrf/config_and_build/bootloaders/bootloader_adding_sysbuild.rst +++ b/doc/nrf/config_and_build/bootloaders/bootloader_adding_sysbuild.rst @@ -38,7 +38,7 @@ The following sections describe how to add either |NSIB| or MCUboot as an immuta Adding |NSIB| as an immutable bootloader ======================================== -To build |NSIB| with a Zephyr or |NCS| sample, enable the :kconfig:option:`SB_CONFIG_SECURE_BOOT_APPCORE` in the application's :file:`sysbuild.conf` file or using the command line: +To build |NSIB| with a Zephyr or |NCS| sample, enable the ``SB_CONFIG_SECURE_BOOT_APPCORE`` in the application's :file:`sysbuild.conf` file or using the command line: .. code-block:: console @@ -68,7 +68,7 @@ The following sections describe different configuration options available for |N Adding a custom signature key file ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To add a signature key file to this bootloader, set the :kconfig:option:`SB_CONFIG_SECURE_BOOT_SIGNING_KEY_FILE` option in the application's :file:`sysbuild.conf` file or using the command line: +To specify a signature key file for this bootloader, set the ``SB_CONFIG_SECURE_BOOT_SIGNING_KEY_FILE`` option in the application's :file:`sysbuild.conf` file or using the command line: .. tabs:: @@ -130,11 +130,11 @@ For example, if a directory named :file:`_keys` located in :file:`/home/user/ncs .. note:: - The public key string must be a list of files in the following ways: + The public key string must contain a list of files where each item can be indicated as follows: - * The relative path to a file from the application configuration directory (if this is not set, then it will be the same as the application source directory). - - * The absolute path to a file. + * Using the relative path to a file from the application configuration directory. + When not specified, it is assumed as the default application source directory. + * Using the absolute path to a file. Environment variables (like :envvar:`$HOME`, :envvar:`$PWD`, or :envvar:`$USER`) and the ``~`` character on Unix systems are not expanded when setting an absolute path from a :file:`sysbuild.conf` file but are expanded correctly in key file paths from the command line that are not given as strings. @@ -144,8 +144,8 @@ See :ref:`ug_fw_update_keys` for information on how to generate custom keys for Additionally, the |NSIB| supports the following methods for signing images with private keys: -* :ref:`ug_fw_update_keys_openssl` - Uses the :kconfig:option:`SB_CONFIG_SECURE_BOOT_SIGNING_OPENSSL` Kconfig option. -* :ref:`Using a custom command ` - Uses the :kconfig:option:`SB_CONFIG_SECURE_BOOT_SIGNING_CUSTOM` Kconfig option. +* Uses the ``SB_CONFIG_SECURE_BOOT_SIGNING_OPENSSL`` Kconfig option. +* :ref:`Using a custom command ` - Uses the ``SB_CONFIG_SECURE_BOOT_SIGNING_CUSTOM`` Kconfig option. The OpenSSL method is handled internally by the build system, whereas using custom commands requires more configuration steps. @@ -196,14 +196,13 @@ To use a custom signing command with this bootloader, set the following options Escaped quotations avoid malformed-string warnings from Kconfig. .. note:: + The public key string must contain a list of files where each item can be indicated as follows: - The public key string must be a list of files in the following ways (as mentioned previously in :ref:`ug_bootloader_adding_sysbuild_immutable_keys`): - - * The relative path to a file from the application configuration directory (if this is not set, then it will be the same as the application source directory). - - * The absolute path to a file. + * Using the relative path to a file from the application configuration directory. + When not specified, it is assumed as the default application source directory. + * Using the absolute path to a file. -See :kconfig:option:`SB_CONFIG_SECURE_BOOT_SIGNING_COMMAND` for specifics about what a usable signing command must do. +See ``SB_CONFIG_SECURE_BOOT_SIGNING_COMMAND`` for specifics about what a usable signing command must do. The command string can include its own arguments like a typical terminal command, including arguments specific to the build system: .. parsed-literal:: @@ -211,20 +210,20 @@ The command string can include its own arguments like a typical terminal command my_command *[options]* ** ** -See the description of :kconfig:option:`SB_CONFIG_SECURE_BOOT_SIGNING_COMMAND` for which arguments can be sent to the build system in this way. +See the description of ``SB_CONFIG_SECURE_BOOT_SIGNING_COMMAND`` for which arguments can be sent to the build system in this way. .. note:: Whitespace, hyphens, and other non-alphanumeric characters must be escaped appropriately when setting the string from the command line. If the custom signing command uses its own options or arguments, it is recommended to define the string in a :file:`sysbuild.conf` file to avoid tracking backslashes. - Like public key paths, environment variables are not expanded when using them in a command string set from one of these files. + Like public key paths, environment variables are not expanded when using them in a command string set from the file. .. _ug_bootloader_adding_sysbuild_immutable_mcuboot: Adding MCUboot as an immutable bootloader ========================================= -To build :doc:`MCUboot ` with a Zephyr or |NCS| sample, enable the :kconfig:option:`SB_CONFIG_BOOTLOADER_MCUBOOT` in the application's :file:`sysbuild.conf` file or using the command line: +To build :doc:`MCUboot ` with a Zephyr or |NCS| sample, enable the ``SB_CONFIG_BOOTLOADER_MCUBOOT`` in the application's :file:`sysbuild.conf` file or using the command line: .. code-block:: console @@ -243,7 +242,7 @@ The following sections describe different configuration options available for MC Adding a custom signature key file ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To pass the signature key file into sysbuild by setting :kconfig:option:`SB_CONFIG_BOOT_SIGNATURE_KEY_FILE` option to the selected private key file. +You can specify the signature key file for this bootloader by setting the ``SB_CONFIG_BOOT_SIGNATURE_KEY_FILE`` option to the selected private key file. You can set the option in :file:`sysbuild.conf` or using the command line: .. tabs:: @@ -304,7 +303,7 @@ Adding MCUboot as an upgradable bootloader To use MCUboot as an upgradable bootloader to your application, complete the following steps: 1. :ref:`Add nRF Secure Immutable Bootloader as the immutable bootloader `. -#. Add MCUboot to the boot chain by including the :kconfig:option:`SB_CONFIG_BOOTLOADER_MCUBOOT` Kconfig option with either the build command or in the application's :file:`sysbuild.conf` file: +#. Add MCUboot to the boot chain by including the ``SB_CONFIG_BOOTLOADER_MCUBOOT`` Kconfig option with either the build command or in the application's :file:`sysbuild.conf` file: .. code-block:: diff --git a/doc/nrf/config_and_build/bootloaders/bootloader_downgrade_protection.rst b/doc/nrf/config_and_build/bootloaders/bootloader_downgrade_protection.rst index 702e6bf40769..7e43d74defb7 100644 --- a/doc/nrf/config_and_build/bootloaders/bootloader_downgrade_protection.rst +++ b/doc/nrf/config_and_build/bootloaders/bootloader_downgrade_protection.rst @@ -29,12 +29,18 @@ Software-based downgrade protection The |NCS| supports MCUboot's software-based downgrade prevention for application images, using semantic versioning. This feature offers protection against any outdated firmware that is uploaded to a device. -To enable this feature, set the configuration option :kconfig:option:`CONFIG_MCUBOOT_DOWNGRADE_PREVENTION` for the MCUboot image and :kconfig:option:`SB_CONFIG_MCUBOOT_MODE_OVERWRITE_ONLY` for sysbuild. +To enable this feature, set the configuration option :kconfig:option:`CONFIG_MCUBOOT_DOWNGRADE_PREVENTION` for the MCUboot image and ``SB_CONFIG_MCUBOOT_MODE_OVERWRITE_ONLY`` for sysbuild. .. caution:: - Enabling :kconfig:option:`SB_CONFIG_MCUBOOT_MODE_OVERWRITE_ONLY` prevents the fallback recovery of application images. + Enabling ``SB_CONFIG_MCUBOOT_MODE_OVERWRITE_ONLY`` prevents the fallback recovery of application images. Consult its Kconfig description and the :doc:`MCUboot Design documentation ` for more information on how to use it. + For nRF53 Series devices, this mode is generally the most appropriate for MCUboot. + The default mode applies only to the application core and not the network core, potentially resulting in a version mismatch. + + In such cases, the application could roll back to a previous working version, but the network core would remain unchanged, leading to inconsistencies. + If the network core remains compatible with a previous version, these issues may go unnoticed for an extended period, making them difficult to debug. + You can compile your application with this feature as follows: .. parsed-literal:: @@ -87,6 +93,7 @@ To enable anti-rollback protection with monotonic counter for |NSIB|, set the fo Special handling is needed when updating the S1 variant of an image when :ref:`ug_bootloader_adding_upgradable`. See :ref:`ug_bootloader_adding_presigned_variants` for details. +See :ref:`zephyr:sysbuild_kconfig_namespacing` for information on how to set options for built images in Sysbuild. .. bootloader_monotonic_counter_nsib_end @@ -99,6 +106,6 @@ Downgrade protection using MCUboot To enable anti-rollback protection with monotonic counter for MCUboot, set the following configurations using sysbuild: -* :kconfig:option:`SB_CONFIG_MCUBOOT_HARDWARE_DOWNGRADE_PREVENTION` -* :kconfig:option:`SB_CONFIG_MCUBOOT_HW_DOWNGRADE_PREVENTION_COUNTER_SLOTS` -* :kconfig:option:`SB_CONFIG_MCUBOOT_HW_DOWNGRADE_PREVENTION_COUNTER_VALUE` +* ``SB_CONFIG_MCUBOOT_HARDWARE_DOWNGRADE_PREVENTION`` +* ``SB_CONFIG_MCUBOOT_HW_DOWNGRADE_PREVENTION_COUNTER_SLOTS`` +* ``SB_CONFIG_MCUBOOT_HW_DOWNGRADE_PREVENTION_COUNTER_VALUE`` diff --git a/doc/nrf/config_and_build/config_and_build_system.rst b/doc/nrf/config_and_build/config_and_build_system.rst index c0a61320aa61..509b1f415a60 100644 --- a/doc/nrf/config_and_build/config_and_build_system.rst +++ b/doc/nrf/config_and_build/config_and_build_system.rst @@ -238,7 +238,12 @@ The sysbuild build configuration is generated using the sysbuild's :file:`CMakeL .. note:: In the |NCS|, building with sysbuild is :ref:`enabled by default `. -For more information about sysbuild, see the :ref:`documentation in Zephyr `. +For more information about sysbuild, see the following pages: + +* :ref:`Sysbuild documentation in Zephyr ` +* :ref:`sysbuild_images` +* :ref:`zephyr_samples_sysbuild` +* :ref:`sysbuild_forced_options` .. _app_build_additions: @@ -271,8 +276,10 @@ To disable these warnings, disable the :kconfig:option:`CONFIG_WARN_EXPERIMENTAL Sysbuild enabled by default =========================== -In the :ref:`nRF repositories `, building an application using the :ref:`standard building procedure ` automatically includes :ref:`configuration_system_overview_sysbuild` (the ``--sysbuild`` parameter). -For this reason, unlike in Zephyr, ``--sysbuild`` does not have to be explicitly mentioned in the command prompt when building the application using the :ref:`dm_code_base`. +When building :ref:`workspace applications ` copied from :ref:`nRF repositories `, using the :ref:`standard building procedure ` automatically includes :ref:`configuration_system_overview_sysbuild` (the ``--sysbuild`` parameter). +For this reason, unlike in Zephyr, ``--sysbuild`` does not have to be explicitly mentioned in the command prompt when building the application. + +This rule does not apply if you work with out-of-tree :ref:`freestanding applications `, for which you need to manually pass ``--sysbuild`` to build commands in every case. You can disable building with sysbuild by using the ``--no-sysbuild`` parameter in the build command. diff --git a/doc/nrf/config_and_build/configuring_app/output_build_files.rst b/doc/nrf/config_and_build/configuring_app/output_build_files.rst index 12763fd3ce5c..6d55147dc2a2 100644 --- a/doc/nrf/config_and_build/configuring_app/output_build_files.rst +++ b/doc/nrf/config_and_build/configuring_app/output_build_files.rst @@ -35,6 +35,7 @@ Which files you are going to use depends on the application configuration and no | :file:`zephyr.hex` | Default full image. | * Programming board targets with :ref:`NSPE ` or single-image. | | | In a project with multiple images, several :file:`zephyr.hex` files are generated, one for each image. | * Testing DFU procedure with nrfjprog (programming directly to device). | | | ``zephyr`` is the value of :kconfig:option:`CONFIG_KERNEL_BIN_NAME`. | | +| | The file is located in the :file:`build//zephyr` directory. | | +--------------------------------------+--------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+ | :file:`merged.hex` | The result of merging all HEX files for all images for a specific core | * Programming multi-core application. | | | In multi-core builds, several :file:`merged_.hex` fields | * Testing DFU procedure with nrfjprog (programming directly to device). | @@ -51,12 +52,14 @@ Which files you are going to use depends on the application configuration and no | | that are transferred with nrfjprog when emulating an update procedure. | | | | :ref:`Compatible with MCUboot `. | | | | ``zephyr`` is the value of :kconfig:option:`CONFIG_KERNEL_BIN_NAME`. | | +| | The file is located in the :file:`build//zephyr` directory. | | +--------------------------------------+--------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+ | :file:`zephyr.signed.hex` | HEX file variant of the :file:`.signed.bin` file. | Programming single or multi-core board targets | | | Can also be used standalone for a single-image DFU. | | | | Contains the signed version of the application. | | | | :ref:`Compatible with MCUboot `. | | | | ``zephyr`` is the value of :kconfig:option:`CONFIG_KERNEL_BIN_NAME`. | | +| | The file is located in the :file:`build//zephyr` directory. | | +--------------------------------------+--------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+ | :file:`zephyr.signed.bin` in | Secondary slot variant of the :file:`zephyr.signed.bin` file. | DFU process for single-core board targets. | | :file:`mcuboot_secondary_app` folder | :ref:`Compatible with MCUboot ` in the :doc:`direct-xip mode `. | | @@ -66,12 +69,12 @@ Which files you are going to use depends on the application configuration and no | :file:`mcuboot_secondary_app` folder | :ref:`Compatible with MCUboot ` in the :doc:`direct-xip mode `. | | | | ``zephyr`` is the value of :kconfig:option:`CONFIG_KERNEL_BIN_NAME`. | | +--------------------------------------+--------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+ -| :file:`dfu_application.zip` | Zip file containing both the MCUboot-compatible update image for one or more cores and a manifest | DFU process for both single-core and multi-core applications. | +| :file:`dfu_application.zip` | Zip file containing both the MCUboot-compatible update images for one or more cores and a manifest | DFU process for both single-core and multi-core applications. | | | describing its contents. | | +--------------------------------------+--------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+ | :file:`matter.ota` | :ref:`ug_matter`-specific OTA image that contains a Matter-compliant header and a DFU multi-image | DFU over Matter for both single-core and multi-core applications. | | | package that bundles user-selected firmware images. | | -| | ``matter.ota`` is the value of :kconfig:option:`SB_CONFIG_MATTER_OTA_IMAGE_FILE_NAME`. | | +| | ``matter.ota`` is the value of ``SB_CONFIG_MATTER_OTA_IMAGE_FILE_NAME``. | | +--------------------------------------+--------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+ | :file:`.zigbee` | :ref:`ug_zigbee`-specific OTA image that contains the Zigbee application with the Zigbee OTA header | DFU over Zigbee for both single-core and multi-core applications | | | used for providing information about the image to the OTA server. | in the |NCS| v2.0.0 and later. | @@ -86,7 +89,7 @@ MCUboot output build files ************************** .. note:: - MCUboot's :doc:`direct-xip mode ` and the related :kconfig:option:`SB_CONFIG_MCUBOOT_MODE_DIRECT_XIP` and :kconfig:option:`SB_CONFIG_MCUBOOT_MODE_DIRECT_XIP_WITH_REVERT` Kconfig options are currently supported only on the single-core devices such as the nRF52 Series. + MCUboot's :doc:`direct-xip mode ` and the related ``SB_CONFIG_MCUBOOT_MODE_DIRECT_XIP`` and ``SB_CONFIG_MCUBOOT_MODE_DIRECT_XIP_WITH_REVERT`` Kconfig options are currently supported only on the single-core devices such as the nRF52 Series. For more details, see the :ref:`more information ` section of the :ref:`ug_nrf52_developing` page. +-----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -97,10 +100,10 @@ MCUboot output build files | | * The MCUboot-compatible update image for one or more cores when MCUboot is *not* in the :doc:`direct-xip mode ` and a manifest describing its contents (all related :file:`*.bin` files and a :file:`manifest.json` file). | | | * The MCUboot-compatible update image for the primary and secondary slots when MCUboot is in the :doc:`direct-xip mode ` and manifest describing its contents (all related :file:`*.bin` files and a :file:`manifest.json` file). | +-----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :file:`dfu_mcuboot.zip` | Contains two versions of MCUboot linked against different address spaces corresponding to slot0 (s0) and slot1 (s1) and a manifest JSON file describing their MCUboot version number (:kconfig:option:`SB_CONFG_SECURE_BOOT_MCUBOOT_VERSION`), | +| :file:`dfu_mcuboot.zip` | Contains two versions of MCUboot linked against different address spaces corresponding to slot0 (s0) and slot1 (s1) and a manifest JSON file describing their MCUboot version number (``SB_CONFG_SECURE_BOOT_MCUBOOT_VERSION``), | | | :ref:`bootloader` (NSIB) version number (:kconfig:option:`CONFIG_FW_INFO`), board type. This file can be used by FOTA servers (for example, nRF Cloud) to serve both s0 and s1 to the device. | | | The device can then select the firmware file for the slot that is currently not in use. | -| | Created when the options :kconfig:option:`SB_CONFIG_SECURE_BOOT_APPCORE` and :kconfig:option:`SB_CONFIG_BOOTLOADER_MCUBOOT` are set. | +| | Created when the options ``SB_CONFIG_SECURE_BOOT_APPCORE`` and ``SB_CONFIG_BOOTLOADER_MCUBOOT`` are set. | +-----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :file:`zephyr.signed.bin` | Signed variant of the firmware in binary format (as opposed to HEX). | | | It can be uploaded to a server as a FOTA image. | diff --git a/doc/nrf/config_and_build/configuring_app/sysbuild_forced_options.rst b/doc/nrf/config_and_build/configuring_app/sysbuild_forced_options.rst index fc0442fb1a4f..3afb96112909 100644 --- a/doc/nrf/config_and_build/configuring_app/sysbuild_forced_options.rst +++ b/doc/nrf/config_and_build/configuring_app/sysbuild_forced_options.rst @@ -5,102 +5,102 @@ Sysbuild forced options Sysbuild controls some Kconfig options in images that are part of a project, this means that these Kconfig options can only be changed from within sysbuild itself and cannot be changed directly in an image (doing so will result in the new value being overwritten with the sysbuild value). -+-------------------------------------------------------------------------+---------------------------------------------------------------------------+----------------------+ -| Kconfig | Sysbuild Kconfig | Image(s) | -+=========================================================================+===========================================================================+======================+ -| :kconfig:option:`CONFIG_PARTITION_MANAGER_ENABLED` + :kconfig:option:`SB_CONFIG_PARTITION_MANAGER` | All | -+-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | -| :kconfig:option:`CONFIG_BUILD_OUTPUT_BIN` + :kconfig:option:`SB_CONFIG_BUILD_OUTPUT_BIN` | | -+-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | -| :kconfig:option:`CONFIG_BUILD_OUTPUT_HEX` + :kconfig:option:`SB_CONFIG_BUILD_OUTPUT_HEX` | | -+-------------------------------------------------------------------------+---------------------------------------------------------------------------+----------------------+ -| :kconfig:option:`CONFIG_BT_FAST_PAIR` + :kconfig:option:`SB_CONFIG_BT_FAST_PAIR` | Main application | -+-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | -| :kconfig:option:`CONFIG_WIFI_NRF700X` + :kconfig:option:`SB_CONFIG_WIFI_NRF700X` | | -+-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | -| :kconfig:option:`CONFIG_NRF_WIFI_PATCHES_EXT_FLASH_DISABLED` + :kconfig:option:`SB_CONFIG_WIFI_PATCHES_EXT_FLASH_DISABLED` | | -+-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | -| :kconfig:option:`CONFIG_NRF_WIFI_PATCHES_EXT_FLASH_XIP` + :kconfig:option:`SB_CONFIG_WIFI_PATCHES_EXT_FLASH_XIP` | | -+-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | -| :kconfig:option:`CONFIG_NRF_WIFI_PATCHES_EXT_FLASH_STORE` + :kconfig:option:`SB_CONFIG_WIFI_PATCHES_EXT_FLASH_STORE` | | -+-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | -| :kconfig:option:`CONFIG_NRF700X_SYSTEM_MODE` + :kconfig:option:`SB_CONFIG_WIFI_NRF700X_SYSTEM_MODE` | | -+-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | -| :kconfig:option:`CONFIG_NRF700X_SCAN_ONLY` + :kconfig:option:`SB_CONFIG_WIFI_NRF700X_SCAN_ONLY` | | -+-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | -| :kconfig:option:`CONFIG_NRF700X_RADIO_TEST` + :kconfig:option:`SB_CONFIG_WIFI_NRF700X_RADIO_TEST` | | -+-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | -| :kconfig:option:`CONFIG_NRF700X_SYSTEM_WITH_RAW_MODES` + :kconfig:option:`SB_CONFIG_WIFI_NRF700X_SYSTEM_WITH_RAW_MODES` | | -+-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | -| :kconfig:option:`CONFIG_NRF_WIFI_FW_PATCH_DFU` + :kconfig:option:`SB_CONFIG_DFU_MULTI_IMAGE_PACKAGE_WIFI_FW_PATCH` | | -+-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | -| :kconfig:option:`CONFIG_MCUBOOT_BOOTLOADER_MODE_SINGLE_APP` + :kconfig:option:`SB_CONFIG_MCUBOOT_MODE_SINGLE_APP` | | -+-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | -| :kconfig:option:`CONFIG_MCUBOOT_BOOTLOADER_MODE_SWAP_WITHOUT_SCRATCH` + :kconfig:option:`SB_CONFIG_MCUBOOT_MODE_SWAP_WITHOUT_SCRATCH` | | -+-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | -| :kconfig:option:`CONFIG_MCUBOOT_BOOTLOADER_MODE_SWAP_SCRATCH` + :kconfig:option:`SB_CONFIG_MCUBOOT_MODE_SWAP_SCRATCH` | | -+-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | -| :kconfig:option:`CONFIG_MCUBOOT_BOOTLOADER_MODE_OVERWRITE_ONLY` + :kconfig:option:`SB_CONFIG_MCUBOOT_MODE_OVERWRITE_ONLY` | | -+-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | -| :kconfig:option:`CONFIG_MCUBOOT_BOOTLOADER_MODE_DIRECT_XIP` + :kconfig:option:`SB_CONFIG_MCUBOOT_MODE_DIRECT_XIP` | | -+-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | -| :kconfig:option:`CONFIG_MCUBOOT_BOOTLOADER_MODE_DIRECT_XIP_WITH_REVERT` + :kconfig:option:`SB_CONFIG_MCUBOOT_MODE_DIRECT_XIP_WITH_REVERT` | | -+-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | -| :kconfig:option:`CONFIG_MCUBOOT_BOOTLOADER_MODE_FIRMWARE_UPDATER` + :kconfig:option:`SB_CONFIG_MCUBOOT_MODE_FIRMWARE_UPDATER` | | -+-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | -| :kconfig:option:`CONFIG_MCUBOOT_HARDWARE_DOWNGRADE_PREVENTION` + :kconfig:option:`SB_CONFIG_MCUBOOT_HARDWARE_DOWNGRADE_PREVENTION` | | -+-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | -| :kconfig:option:`CONFIG_MCUBOOT_HW_DOWNGRADE_PREVENTION_COUNTER_SLOTS` + :kconfig:option:`SB_CONFIG_MCUBOOT_HW_DOWNGRADE_PREVENTION_COUNTER_SLOTS` | | -+-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | -| :kconfig:option:`CONFIG_MCUBOOT_HW_DOWNGRADE_PREVENTION_COUNTER_VALUE` + :kconfig:option:`SB_CONFIG_MCUBOOT_HW_DOWNGRADE_PREVENTION_COUNTER_VALUE` | | -+-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | -| :kconfig:option:`CONFIG_UPDATEABLE_IMAGE_NUMBER` + :kconfig:option:`SB_CONFIG_SB_CONFIG_MCUBOOT_UPDATEABLE_IMAGES` if | | -| + :kconfig:option:`SB_CONFIG_MCUBOOT_APP_SYNC_UPDATEABLE_IMAGES` is enabled | | -+-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | -| :kconfig:option:`CONFIG_CHIP` + :kconfig:option:`SB_CONFIG_MATTER` | | -+-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | -| :kconfig:option:`CONFIG_CHIP_OTA_REQUESTOR` + :kconfig:option:`SB_CONFIG_MATTER_OTA` | | -+-------------------------------------------------------------------------+ | | -| :kconfig:option:`CONFIG_CHIP_OTA_IMAGE_BUILD` + | | -+-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | -| :kconfig:option:`CONFIG_SUIT_MPI_APP_RECOVERY` + :kconfig:option:`SB_CONFIG_SUIT_BUILD_RECOVERY` | | -+-------------------------------------------------------------------------+ | | -| :kconfig:option:`CONFIG_SUIT_MPI_RAD_RECOVERY` + | | -+-------------------------------------------------------------------------+---------------------------------------------------------------------------+----------------------+ -| :kconfig:option:`CONFIG_SINGLE_APPLICATION_SLOT` + :kconfig:option:`SB_CONFIG_MCUBOOT_MODE_SINGLE_APP` | MCUboot | -+-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | -| :kconfig:option:`CONFIG_BOOT_SWAP_USING_MOVE` + :kconfig:option:`SB_CONFIG_MCUBOOT_MODE_SWAP_WITHOUT_SCRATCH` | | -+-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | -| :kconfig:option:`CONFIG_BOOT_SWAP_USING_SCRATCH` + :kconfig:option:`SB_CONFIG_MCUBOOT_MODE_SWAP_SCRATCH` | | -+-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | -| :kconfig:option:`CONFIG_BOOT_UPGRADE_ONLY` + :kconfig:option:`SB_CONFIG_MCUBOOT_MODE_OVERWRITE_ONLY` | | -+-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | -| :kconfig:option:`CONFIG_BOOT_DIRECT_XIP` + :kconfig:option:`SB_CONFIG_MCUBOOT_MODE_DIRECT_XIP` | | -+-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | -| :kconfig:option:`CONFIG_BOOT_DIRECT_XIP_REVERT` + :kconfig:option:`SB_CONFIG_MCUBOOT_MODE_DIRECT_XIP_WITH_REVERT` | | -+-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | -| :kconfig:option:`CONFIG_BOOT_FIRMWARE_LOADER` + :kconfig:option:`SB_CONFIG_MCUBOOT_MODE_FIRMWARE_UPDATER` | | -+-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | -| :kconfig:option:`CONFIG_PCD_APP` + :kconfig:option:`SB_CONFIG_NETCORE_APP_UPDATE` | | -+-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | -| :kconfig:option:`CONFIG_UPDATEABLE_IMAGE_NUMBER` + :kconfig:option:`SB_CONFIG_SB_CONFIG_MCUBOOT_UPDATEABLE_IMAGES` | | -+-------------------------------------------------------------------------+---------------------------------------------------------------------------+----------------------+ -| :kconfig:option:`CONFIG_MCUBOOT_HW_DOWNGRADE_PREVENTION` + :kconfig:option:`SB_CONFIG_MCUBOOT_HARDWARE_DOWNGRADE_PREVENTION` | | -+-------------------------------------------------------------------------+ | | -| :kconfig:option:`CONFIG_SECURE_BOOT_STORAGE` + | | -+-------------------------------------------------------------------------+ | | -| :kconfig:option:`CONFIG_SECURE_BOOT_CRYPTO` + | | -+-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | -| :kconfig:option:`CONFIG_PM_EXTERNAL_FLASH_MCUBOOT_SECONDARY` + :kconfig:option:`SB_CONFIG_PM_EXTERNAL_FLASH_MCUBOOT_SECONDARY` | Main application, | -+-------------------------------------------------------------------------+---------------------------------------------------------------------------+ MCUboot | -| :kconfig:option:`CONFIG_PM_OVERRIDE_EXTERNAL_DRIVER_CHECK` + :kconfig:option:`SB_CONFIG_PM_OVERRIDE_EXTERNAL_DRIVER_CHECK` | | -+-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | -| :kconfig:option:`CONFIG_FW_INFO` + :kconfig:option:`SB_CONFIG_SECURE_BOOT_APPCORE` | | -+-------------------------------------------------------------------------+---------------------------------------------------------------------------+----------------------+ -| :kconfig:option:`CONFIG_NCS_MCUBOOT_IN_BUILD` + :kconfig:option:`SB_CONFIG_BOOTLOADER_MCUBOOT` | b0, | -| + | b0n | -+-------------------------------------------------------------------------+---------------------------------------------------------------------------+----------------------+ -| :kconfig:option:`CONFIG_SECURE_BOOT` + :kconfig:option:`SB_CONFIG_SECURE_BOOT_APPCORE` or | Main application, | -| + :kconfig:option:`SB_CONFIG_SECURE_BOOT_NETCORE` | Net core main image, | -| + | MCUboot | -+-------------------------------------------------------------------------+---------------------------------------------------------------------------+----------------------+ ++-------------------------------------------------------------------------+---------------------------------------------------------------------------+-------------------------+ +| Kconfig | Sysbuild Kconfig | Image(s) | ++=========================================================================+===========================================================================+=========================+ +| :kconfig:option:`CONFIG_PARTITION_MANAGER_ENABLED` + ``SB_CONFIG_PARTITION_MANAGER`` | All | ++-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | +| :kconfig:option:`CONFIG_BUILD_OUTPUT_BIN` + ``SB_CONFIG_BUILD_OUTPUT_BIN`` | | ++-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | +| :kconfig:option:`CONFIG_BUILD_OUTPUT_HEX` + ``SB_CONFIG_BUILD_OUTPUT_HEX`` | | ++-------------------------------------------------------------------------+---------------------------------------------------------------------------+-------------------------+ +| :kconfig:option:`CONFIG_BT_FAST_PAIR` + ``SB_CONFIG_BT_FAST_PAIR`` | Main application | ++-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | +| :kconfig:option:`CONFIG_WIFI_NRF700X` + ``SB_CONFIG_WIFI_NRF700X`` | | ++-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | +| :kconfig:option:`CONFIG_NRF_WIFI_PATCHES_EXT_FLASH_DISABLED` + ``SB_CONFIG_WIFI_PATCHES_EXT_FLASH_DISABLED`` | | ++-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | +| :kconfig:option:`CONFIG_NRF_WIFI_PATCHES_EXT_FLASH_XIP` + ``SB_CONFIG_WIFI_PATCHES_EXT_FLASH_XIP`` | | ++-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | +| :kconfig:option:`CONFIG_NRF_WIFI_PATCHES_EXT_FLASH_STORE` + ``SB_CONFIG_WIFI_PATCHES_EXT_FLASH_STORE`` | | ++-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | +| :kconfig:option:`CONFIG_NRF700X_SYSTEM_MODE` + ``SB_CONFIG_WIFI_NRF700X_SYSTEM_MODE`` | | ++-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | +| :kconfig:option:`CONFIG_NRF700X_SCAN_ONLY` + ``SB_CONFIG_WIFI_NRF700X_SCAN_ONLY`` | | ++-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | +| :kconfig:option:`CONFIG_NRF700X_RADIO_TEST` + ``SB_CONFIG_WIFI_NRF700X_RADIO_TEST`` | | ++-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | +| :kconfig:option:`CONFIG_NRF700X_SYSTEM_WITH_RAW_MODES` + ``SB_CONFIG_WIFI_NRF700X_SYSTEM_WITH_RAW_MODES`` | | ++-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | +| :kconfig:option:`CONFIG_NRF_WIFI_FW_PATCH_DFU` + ``SB_CONFIG_DFU_MULTI_IMAGE_PACKAGE_WIFI_FW_PATCH`` | | ++-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | +| :kconfig:option:`CONFIG_MCUBOOT_BOOTLOADER_MODE_SINGLE_APP` + ``SB_CONFIG_MCUBOOT_MODE_SINGLE_APP`` | | ++-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | +| :kconfig:option:`CONFIG_MCUBOOT_BOOTLOADER_MODE_SWAP_WITHOUT_SCRATCH` + ``SB_CONFIG_MCUBOOT_MODE_SWAP_WITHOUT_SCRATCH`` | | ++-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | +| :kconfig:option:`CONFIG_MCUBOOT_BOOTLOADER_MODE_SWAP_SCRATCH` + ``SB_CONFIG_MCUBOOT_MODE_SWAP_SCRATCH`` | | ++-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | +| :kconfig:option:`CONFIG_MCUBOOT_BOOTLOADER_MODE_OVERWRITE_ONLY` + ``SB_CONFIG_MCUBOOT_MODE_OVERWRITE_ONLY`` | | ++-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | +| :kconfig:option:`CONFIG_MCUBOOT_BOOTLOADER_MODE_DIRECT_XIP` + ``SB_CONFIG_MCUBOOT_MODE_DIRECT_XIP`` | | ++-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | +| :kconfig:option:`CONFIG_MCUBOOT_BOOTLOADER_MODE_DIRECT_XIP_WITH_REVERT` + ``SB_CONFIG_MCUBOOT_MODE_DIRECT_XIP_WITH_REVERT`` | | ++-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | +| :kconfig:option:`CONFIG_MCUBOOT_BOOTLOADER_MODE_FIRMWARE_UPDATER` + ``SB_CONFIG_MCUBOOT_MODE_FIRMWARE_UPDATER`` | | ++-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | +| :kconfig:option:`CONFIG_MCUBOOT_HARDWARE_DOWNGRADE_PREVENTION` + ``SB_CONFIG_MCUBOOT_HARDWARE_DOWNGRADE_PREVENTION`` | | ++-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | +| :kconfig:option:`CONFIG_MCUBOOT_HW_DOWNGRADE_PREVENTION_COUNTER_SLOTS` + ``SB_CONFIG_MCUBOOT_HW_DOWNGRADE_PREVENTION_COUNTER_SLOTS`` | | ++-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | +| :kconfig:option:`CONFIG_MCUBOOT_HW_DOWNGRADE_PREVENTION_COUNTER_VALUE` + ``SB_CONFIG_MCUBOOT_HW_DOWNGRADE_PREVENTION_COUNTER_VALUE`` | | ++-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | +| :kconfig:option:`CONFIG_UPDATEABLE_IMAGE_NUMBER` + ``SB_CONFIG_SB_CONFIG_MCUBOOT_UPDATEABLE_IMAGES`` if | | +| + ``SB_CONFIG_MCUBOOT_APP_SYNC_UPDATEABLE_IMAGES`` is enabled | | ++-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | +| :kconfig:option:`CONFIG_CHIP` + ``SB_CONFIG_MATTER`` | | ++-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | +| :kconfig:option:`CONFIG_CHIP_OTA_REQUESTOR` + ``SB_CONFIG_MATTER_OTA`` | | ++-------------------------------------------------------------------------+ | | +| :kconfig:option:`CONFIG_CHIP_OTA_IMAGE_BUILD` + | | ++-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | +| :kconfig:option:`CONFIG_SUIT_MPI_APP_RECOVERY` + ``SB_CONFIG_SUIT_BUILD_RECOVERY`` | | ++-------------------------------------------------------------------------+ | | +| :kconfig:option:`CONFIG_SUIT_MPI_RAD_RECOVERY` + | | ++-------------------------------------------------------------------------+---------------------------------------------------------------------------+-------------------------+ +| :kconfig:option:`CONFIG_SINGLE_APPLICATION_SLOT` + ``SB_CONFIG_MCUBOOT_MODE_SINGLE_APP`` | MCUboot | ++-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | +| :kconfig:option:`CONFIG_BOOT_SWAP_USING_MOVE` + ``SB_CONFIG_MCUBOOT_MODE_SWAP_WITHOUT_SCRATCH`` | | ++-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | +| :kconfig:option:`CONFIG_BOOT_SWAP_USING_SCRATCH` + ``SB_CONFIG_MCUBOOT_MODE_SWAP_SCRATCH`` | | ++-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | +| :kconfig:option:`CONFIG_BOOT_UPGRADE_ONLY` + ``SB_CONFIG_MCUBOOT_MODE_OVERWRITE_ONLY`` | | ++-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | +| :kconfig:option:`CONFIG_BOOT_DIRECT_XIP` + ``SB_CONFIG_MCUBOOT_MODE_DIRECT_XIP`` | | ++-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | +| :kconfig:option:`CONFIG_BOOT_DIRECT_XIP_REVERT` + ``SB_CONFIG_MCUBOOT_MODE_DIRECT_XIP_WITH_REVERT`` | | ++-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | +| :kconfig:option:`CONFIG_BOOT_FIRMWARE_LOADER` + ``SB_CONFIG_MCUBOOT_MODE_FIRMWARE_UPDATER`` | | ++-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | +| :kconfig:option:`CONFIG_PCD_APP` + ``SB_CONFIG_NETCORE_APP_UPDATE`` | | ++-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | +| :kconfig:option:`CONFIG_UPDATEABLE_IMAGE_NUMBER` + ``SB_CONFIG_SB_CONFIG_MCUBOOT_UPDATEABLE_IMAGES`` | | ++-------------------------------------------------------------------------+---------------------------------------------------------------------------+-------------------------+ +| :kconfig:option:`CONFIG_MCUBOOT_HW_DOWNGRADE_PREVENTION` + ``SB_CONFIG_MCUBOOT_HARDWARE_DOWNGRADE_PREVENTION`` | | ++-------------------------------------------------------------------------+ | | +| :kconfig:option:`CONFIG_SECURE_BOOT_STORAGE` + | | ++-------------------------------------------------------------------------+ | | +| :kconfig:option:`CONFIG_SECURE_BOOT_CRYPTO` + | | ++-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | +| :kconfig:option:`CONFIG_PM_EXTERNAL_FLASH_MCUBOOT_SECONDARY` + ``SB_CONFIG_PM_EXTERNAL_FLASH_MCUBOOT_SECONDARY`` | Main application, | ++-------------------------------------------------------------------------+---------------------------------------------------------------------------+ MCUboot | +| :kconfig:option:`CONFIG_PM_OVERRIDE_EXTERNAL_DRIVER_CHECK` + ``SB_CONFIG_PM_OVERRIDE_EXTERNAL_DRIVER_CHECK`` | | ++-------------------------------------------------------------------------+---------------------------------------------------------------------------+ | +| :kconfig:option:`CONFIG_FW_INFO` + ``SB_CONFIG_SECURE_BOOT_APPCORE`` | | ++-------------------------------------------------------------------------+---------------------------------------------------------------------------+-------------------------+ +| :kconfig:option:`CONFIG_NCS_MCUBOOT_IN_BUILD` + ``SB_CONFIG_BOOTLOADER_MCUBOOT`` |:ref:`b0 `, | +| + |:ref:`b0n ` | ++-------------------------------------------------------------------------+---------------------------------------------------------------------------+-------------------------+ +| :kconfig:option:`CONFIG_SECURE_BOOT` + ``SB_CONFIG_SECURE_BOOT_APPCORE`` or | Main application, | +| + ``SB_CONFIG_SECURE_BOOT_NETCORE`` | Network core main image,| +| + | MCUboot | ++-------------------------------------------------------------------------+---------------------------------------------------------------------------+-------------------------+ diff --git a/doc/nrf/config_and_build/configuring_app/sysbuild_images.rst b/doc/nrf/config_and_build/configuring_app/sysbuild_images.rst index fcb90605a180..cc8d0463ee94 100644 --- a/doc/nrf/config_and_build/configuring_app/sysbuild_images.rst +++ b/doc/nrf/config_and_build/configuring_app/sysbuild_images.rst @@ -3,19 +3,27 @@ Sysbuild images ############### +Sysbuild allows you to add additional images to your builds. + Enabling images =============== -Sysbuild allows you to add additional images to a build by modifying the central sysbuild configuration. +To add an additional image using sysbuild, you must modify the central sysbuild configuration. This is typically done in a `sysbuild.conf` file within an application, which is a Kconfig fragment applied to the default sysbuild configuration when a project is configured. + +.. note:: + On the nRF54H20 SoC, do not use any ``SECURE_BOOT`` or ``MCUBOOT`` option. + The nRF54H20 SoC boot sequence is based on the Secure Domain, and it cannot be disabled. + For more information, see :ref:`ug_nrf54h20_architecture_boot`. + The following sysbuild Kconfig options can be used to enable images in a build: +-------------------------------------------------+-----------------------------------------------------------------------------------------+ | Sysbuild Kconfig option | Description | +=================================================+=========================================================================================+ -| :kconfig:option:`SB_CONFIG_SECURE_BOOT_APPCORE` | Enable secure boot for application core (or main core if device only has a single core) | +| ``SB_CONFIG_SECURE_BOOT_APPCORE`` | Enable secure boot for application core (or main core if device only has a single core).| +-------------------------------------------------+-----------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_BOOTLOADER_MCUBOOT` | Build MCUboot image | +| ``SB_CONFIG_BOOTLOADER_MCUBOOT`` | Build MCUboot image. | +-------------------------------------------------+-----------------------------------------------------------------------------------------+ The following sysbuild Kconfig options are also available for nRF53-based devices. @@ -24,21 +32,21 @@ These options determine whether the secure boot image is included on the network +---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ | Sysbuild Kconfig option | Description | +=========================================================+===========================================================================================================+ -| :kconfig:option:`SB_CONFIG_SECURE_BOOT_NETCORE` | Enable secure boot for network core | +| ``SB_CONFIG_SECURE_BOOT_NETCORE`` | Enable secure boot for network core. | +---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_NETCORE_EMPTY` | |NCS| empty network core image :zephyr_file:`samples/nrf5340/empty_net_core` | +| ``SB_CONFIG_NETCORE_EMPTY`` | |NCS| empty network core image :ref:`nrf5340_empty_net_core`. | +---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_NETCORE_HCI_IPC` | Zephyr hci_ipc Bluetooth image :zephyr_file:`samples/bluetooth/hci_ipc` | +| ``SB_CONFIG_NETCORE_HCI_IPC`` | Zephyr hci_ipc Bluetooth image :ref:`zephyr:bluetooth-hci-ipc-sample`. | +---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_NETCORE_RPC_HOST` | |NCS| rpc_host Bluetooth image :zephyr_file:`samples/bluetooth/rpc_host` | +| ``SB_CONFIG_NETCORE_RPC_HOST`` | |NCS| rpc_host Bluetooth image :ref:`ble_rpc_host`. | +---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_NETCORE_802154_RPMSG` | Zephyr 802.15.4 image :zephyr_file:`samples/boards/nrf/ieee802154/802154_rpmsg` | +| ``SB_CONFIG_NETCORE_802154_RPMSG`` | Zephyr 802.15.4 image :ref:`zephyr:nrf-ieee802154-rpmsg-sample`. | +---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_NETCORE_MULTIPROTOCOL_RPMSG` | |NCS| multiprotocol_rpmsg Bluetooth and 802.15.4 image :zephyr_file:`samples/nrf5340/multiprotocol_rpmsg` | +| ``SB_CONFIG_NETCORE_MULTIPROTOCOL_RPMSG`` | |NCS| multiprotocol_rpmsg Bluetooth and 802.15.4 image :ref:`multiprotocol-rpmsg-sample`. | +---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_NETCORE_IPC_RADIO` | |NCS| ipc_radio image :zephyr_file:`applications/ipc_radio` | +| ``SB_CONFIG_NETCORE_IPC_RADIO`` | |NCS| ipc_radio image :ref:`ipc_radio`. | +---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_NETCORE_NONE` | No network core image | +| ``SB_CONFIG_NETCORE_NONE`` | No network core image. | +---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ .. _sysbuild_images_adding_custom_images: @@ -53,7 +61,10 @@ Custom images can be added directly to a project (or board) or to a Zephyr modul Adding to a single project -------------------------- -Adding an image to a single project requires the `Kconfig.sysbuild` file to include Kconfig options that will be added to the sysbuild configuration (if the image selection is optional, it can be omitted if the image selection is mandatory) and a `sysbuild.cmake` file to incorporate the image into the project. +To add an image to a single project, you need a ``sysbuild.cmake`` file in the root folder of your project to incorporate the image into the project. +If the image selection is optional, a ``Kconfig.sysbuild`` file in the root folder of your project is also required to include Kconfig options for the sysbuild configuration. +If the image selection is mandatory, the ``Kconfig.sysbuild`` file can be omitted. + Kconfig.sysbuild: @@ -187,7 +198,7 @@ Then, add this folder to the Zephyr module file: .. code-block:: yaml build: - sysbuild-cmake: sysbuild # Only needed is a sysbuild CMakeLists.txt file is being added + sysbuild-cmake: sysbuild # Only needed if a sysbuild CMakeLists.txt file is being added sysbuild-kconfig: sysbuild/Kconfig.sysbuild The ``CMakeLists.txt`` file is the same as the ``sysbuild.cmake`` file from the previous examples. @@ -227,3 +238,8 @@ Kconfig.sysbuild: endif # !NETCORE_NONE endmenu + +Next steps +========== + +For more information on sysbuild, see :ref:`zephyr:sysbuild`, :ref:`zephyr_samples_sysbuild`, and :ref:`sysbuild_forced_options`. diff --git a/doc/nrf/config_and_build/configuring_app/zephyr_samples_sysbuild.rst b/doc/nrf/config_and_build/configuring_app/zephyr_samples_sysbuild.rst index 0d5953a0f7f4..8b56750703f4 100644 --- a/doc/nrf/config_and_build/configuring_app/zephyr_samples_sysbuild.rst +++ b/doc/nrf/config_and_build/configuring_app/zephyr_samples_sysbuild.rst @@ -4,44 +4,53 @@ Using Zephyr samples with sysbuild ################################## With the introduction of sysbuild in |NCS|, images for devices that have multiple cores must now configure which images they need in order to be built successfully and run. -For applications and samples in the |NCS| repository, this is handled automatically but for samples that are in the ``zephyr`` directory that come from upstream Zephyr, these images must be selected manually when building an image for nRF53 devices (for nRF52 as this is a single core device, no additional images are needed for Bluetooth samples). - -+---------------------------------------------------------+-------------------------+-----------+----------+-----------------------------------------------------------------------------------------------------------------------+ -| Sysbuild Kconfig option | Image | Bluetooth | 802.15.4 | Details | -+=========================================================+=========================+===========+==========+=======================================================================================================================+ -| :kconfig:option:`SB_CONFIG_NETCORE_EMPTY` | ``empty_net_core`` | ✕ | ✕ | | -+---------------------------------------------------------+-------------------------+-----------+----------+-----------------------------------------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_NETCORE_HCI_IPC` | ``hci_ipc`` | ✓ | ✕ | | -+---------------------------------------------------------+-------------------------+-----------+----------+-----------------------------------------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_NETCORE_RPC_HOST` | ``rpc_host`` | ✓ | ✕ | Requires that application be setup for this mode | -+---------------------------------------------------------+-------------------------+-----------+----------+-----------------------------------------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_NETCORE_802154_RPMSG` | ``802154_rpmsg`` | ✕ | ✓ | | -+---------------------------------------------------------+-------------------------+-----------+----------+-----------------------------------------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_NETCORE_MULTIPROTOCOL_RPMSG` | ``multiprotocol_rpmsg`` | ✓ | ✓ | | -+---------------------------------------------------------+-------------------------+-----------+----------+-----------------------------------------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_NETCORE_IPC_RADIO` | ``ipc_radio`` | ✓ | ✓ | Requires additional configuration. The following Kconfigs provide predefined configurations: | -| | | | | :kconfig:option:`SB_CONFIG_NETCORE_IPC_RADIO_BT_HCI_IPC` enables HCI serialization | -| | | | | for Bluetooth, :kconfig:option:`SB_CONFIG_NETCORE_IPC_RADIO_BT_RPC` enables nRF RPC serialization for Bluetooth, or | -| | | | | :kconfig:option:`SB_CONFIG_NETCORE_IPC_RADIO_IEEE802154` enables spinel serialization for IEEE 802.15.4. | -+---------------------------------------------------------+-------------------------+-----------+----------+-----------------------------------------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_NETCORE_NONE` | No image | - | - | | -+---------------------------------------------------------+-------------------------+-----------+----------+-----------------------------------------------------------------------------------------------------------------------+ - -The default for Thingy:53 is the ``empty_net_core`` sample application. +For applications and samples in the |NCS| repository, this is handled automatically but for samples that are in the ``zephyr`` directory that come from upstream Zephyr, these images must be selected manually when building an image for nRF53 devices. + +.. note:: + As nRF52 is`` a single core device, no additional images are needed for Bluetooth samples. + ++---------------------------------------------------------+-------------------------------------------+-----------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| Sysbuild Kconfig option | Image | Bluetooth | 802.15.4 | Details | ++=========================================================+===========================================+===========+==========+=======================================================================================================================+ +| ``SB_CONFIG_NETCORE_EMPTY`` | :ref:`nrf5340_empty_net_core` | ✕ | ✕ | | ++---------------------------------------------------------+-------------------------------------------+-----------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ``SB_CONFIG_NETCORE_HCI_IPC`` | :ref:`zephyr:bluetooth-hci-ipc-sample` | ✓ | ✕ | | ++---------------------------------------------------------+-------------------------------------------+-----------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ``SB_CONFIG_NETCORE_RPC_HOST`` | :ref:`ble_rpc_host` | ✓ | ✕ | Requires that application be setup for this mode. | ++---------------------------------------------------------+-------------------------------------------+-----------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ``SB_CONFIG_NETCORE_802154_RPMSG`` | :ref:`zephyr:nrf-ieee802154-rpmsg-sample` | ✕ | ✓ | | ++---------------------------------------------------------+-------------------------------------------+-----------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ``SB_CONFIG_NETCORE_MULTIPROTOCOL_RPMSG`` | :ref:`multiprotocol-rpmsg-sample` | ✓ | ✓ | | ++---------------------------------------------------------+-------------------------------------------+-----------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ``SB_CONFIG_NETCORE_IPC_RADIO`` | :ref:`ipc_radio` | ✓ | ✓ | Requires additional configuration. The following Kconfig options provide predefined configurations: | +| | | | | ``SB_CONFIG_NETCORE_IPC_RADIO_BT_HCI_IPC`` enables HCI serialization | +| | | | | for Bluetooth, ``SB_CONFIG_NETCORE_IPC_RADIO_BT_RPC`` enables nRF RPC serialization for Bluetooth, or | +| | | | | ``SB_CONFIG_NETCORE_IPC_RADIO_IEEE802154`` enables spinel serialization for IEEE 802.15.4. | ++---------------------------------------------------------+-------------------------------------------+-----------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ``SB_CONFIG_NETCORE_NONE`` | No image | n/a | n/a | | ++---------------------------------------------------------+-------------------------------------------+-----------+----------+-----------------------------------------------------------------------------------------------------------------------+ + +The default for Thingy:53 is the :ref:`nrf5340_empty_net_core` sample application. The default for other nRF53 devices is having no image added to the build. -When configuring an application, such as :zephyr_file:`zephyr/samples/bluetooth/peripheral_hr`, you must configure it with a supported network core image to ensure proper functionality. -For basic Bluetooth samples, you can use `hci_ipc`, `multiprotocol_rpmsg`, or `ipc_radio`. -The following instructions demonstrate how to build a sample with the `hci_ipc` network image selected: +When configuring an application, such as :ref:`zephyr:peripheral_hr`, you must configure it with a supported network core image to ensure proper functionality. +For basic Bluetooth samples, you can use :ref:`zephyr:bluetooth-hci-ipc-sample`, :ref:`multiprotocol-rpmsg-sample`, or :ref:`ipc_radio` (one of the :ref:`companion components `). +Use one of the following command patterns to build a sample with the :ref:`zephyr:bluetooth-hci-ipc-sample` network image selected (with the relevant *board_target*, path to your application *app_dir*, and path to Zephyr's shared sysbuild directory */share/sysbuild*): .. tabs:: .. group-tab:: west - west build -b -- -DSB_CONFIG_NETCORE_HCI_IPC=y + .. parsed-literal:: + :class: highlight - .. group-tab:: cmake + west build -b *board_target* -- -DSB_CONFIG_NETCORE_HCI_IPC=y - cmake -GNinja -DBOARD= -DSB_CONFIG_NETCORE_HCI_IPC=y -DAPP_DIR= + .. group-tab:: CMake + + .. parsed-literal:: + :class: highlight + + cmake -GNinja -DBOARD=*board_target* -DSB_CONFIG_NETCORE_HCI_IPC=y -DAPP_DIR=*app_dir* */share/sysbuild* When building and programming such a project, both the main application and the selected network core image will be programmed to the device and the sample application will run as expected. diff --git a/doc/nrf/config_and_build/multi_image.rst b/doc/nrf/config_and_build/multi_image.rst index 6cb1f052f5fb..5856bfdb633a 100644 --- a/doc/nrf/config_and_build/multi_image.rst +++ b/doc/nrf/config_and_build/multi_image.rst @@ -7,7 +7,7 @@ Multi-image builds using child and parent images :local: :depth: 2 -.. important:: +.. caution:: |sysbuild_related_deprecation_note| The firmware programmed to a device can be composed of either one application or several separate images. diff --git a/doc/nrf/device_guides/nrf52/fota_update.rst b/doc/nrf/device_guides/nrf52/fota_update.rst index 4ad4243a07f9..e9a218a7413e 100644 --- a/doc/nrf/device_guides/nrf52/fota_update.rst +++ b/doc/nrf/device_guides/nrf52/fota_update.rst @@ -49,7 +49,7 @@ To enable support for FOTA updates, do the following: .. fota_upgrades_over_ble_mandatory_mcuboot_start -* Use MCUboot as the upgradable bootloader (:kconfig:option:`SB_CONFIG_BOOTLOADER_MCUBOOT` must be enabled). +* Use MCUboot as the upgradable bootloader (``SB_CONFIG_BOOTLOADER_MCUBOOT`` must be enabled). For more information, go to the :ref:`ug_bootloader_adding` page. .. fota_upgrades_over_ble_mandatory_mcuboot_end @@ -85,18 +85,18 @@ For more information about the direct-xip mode and the revert mechanism support, To use MCUboot in the direct-xip mode together with FOTA updates, do the following: -* Enable the :kconfig:option:`SB_CONFIG_MCUBOOT_MODE_DIRECT_XIP` Kconfig option in sysbuild. +* Enable the ``SB_CONFIG_MCUBOOT_MODE_DIRECT_XIP`` Kconfig option in sysbuild. See how to build the :ref:`peripheral_lbs` sample with MCUboot in the direct-xip mode when the revert mechanism support is disabled: .. parsed-literal:: :class: highlight - west build -b *board_target* -- -DSB_CONFIG_BOOTLOADER_MCUBOOT=y -DSB_CONFIG_BOOT_DIRECT_XIP=y -DCONFIG_NCS_SAMPLE_MCUMGR_BT_OTA_DFU=y + west build -b *board_target* -- -DSB_CONFIG_BOOTLOADER_MCUBOOT=y -DSB_CONFIG_MCUBOOT_MODE_DIRECT_XIP=y -DCONFIG_NCS_SAMPLE_MCUMGR_BT_OTA_DFU=y Optionally, if you want to enable the revert mechanism support, complete the following: -* Enable the :kconfig:option:`SB_CONFIG_MCUBOOT_MODE_DIRECT_XIP_WITH_REVERT` Kconfig option in sysbuild instead of :kconfig:option:`SB_CONFIG_MCUBOOT_MODE_DIRECT_XIP`. +* Enable the ``SB_CONFIG_MCUBOOT_MODE_DIRECT_XIP_WITH_REVERT`` Kconfig option in sysbuild instead of ``SB_CONFIG_MCUBOOT_MODE_DIRECT_XIP``. See how to build the :ref:`peripheral_lbs` sample with MCUboot in direct-xip mode when the revert mechanism support is enabled: @@ -111,7 +111,7 @@ See how to build the :ref:`peripheral_lbs` sample with MCUboot in direct-xip mod If the application is built without this option, it will fail to boot. It must, however, be disabled when building update images. -Both the :kconfig:option:`SB_CONFIG_MCUBOOT_MODE_DIRECT_XIP` and :kconfig:option:`SB_CONFIG_MCUBOOT_MODE_DIRECT_XIP_WITH_REVERT` Kconfig options automatically build application update images for both slots. +Both the ``SB_CONFIG_MCUBOOT_MODE_DIRECT_XIP`` and ``SB_CONFIG_MCUBOOT_MODE_DIRECT_XIP_WITH_REVERT`` Kconfig options automatically build application update images for both slots. To read about the files that are built when the option is enabled, refer to the :ref:`app_build_mcuboot_output` page. .. fota_upgrades_over_ble_mcuboot_direct_xip_nrfcdm_note_start diff --git a/doc/nrf/device_guides/nrf70/fw_patches_ext_flash.rst b/doc/nrf/device_guides/nrf70/fw_patches_ext_flash.rst index 8873b8a32aef..2cbb70ea0ea7 100644 --- a/doc/nrf/device_guides/nrf70/fw_patches_ext_flash.rst +++ b/doc/nrf/device_guides/nrf70/fw_patches_ext_flash.rst @@ -56,7 +56,7 @@ Using XIP access If the application supports XIP from external memory, then the firmware patches can be loaded as part of the nRF Wi-Fi driver code (RODATA) and then relocated to the external memory. The nRF Wi-Fi driver accesses the firmware patches using XIP feature and downloads the firmware patches to the nRF70 device. -To enable this feature, set the :kconfig:option:`SB_CONFIG_WIFI_PATCHES_EXT_FLASH_XIP` sysbuild Kconfig option to ``y``. +To enable this feature, set the ``SB_CONFIG_WIFI_PATCHES_EXT_FLASH_XIP`` sysbuild Kconfig option to ``y``. Once the build is complete, the feature can be verified by checking the memory regions summary in the build output. A new memory region called ``EXTFLASH`` is added to the memory regions summary, and the firmware patches are placed in this region. The size of the ``FLASH`` used is reduced by the size of the firmware patches. @@ -87,7 +87,7 @@ Configuration The following configuration options are available: -* :kconfig:option:`SB_CONFIG_WIFI_PATCHES_EXT_FLASH_STORE` - Enables the option to store the firmware patch in external non-XIP memory. +* ``SB_CONFIG_WIFI_PATCHES_EXT_FLASH_STORE`` - Enables the option to store the firmware patch in external non-XIP memory. * :kconfig:option:`CONFIG_NRF_WIFI_FW_FLASH_CHUNK_SIZE` - Defines the size of the chunks used to read the firmware patches from the external non-XIP memory. The default value is 8192 bytes. @@ -126,7 +126,8 @@ Building See :ref:`nrf7002dk_nrf5340` for general instructions on building. -Additionally, you must enable the ``nrf70-fw-patch-ext-flash`` snippet, set :kconfig:option:`SB_CONFIG_WIFI_PATCHES_EXT_FLASH_STORE`, and disable :kconfig:option:`SB_CONFIG_PARTITION_MANAGER`. +Additionally, you can build the sample either with the ``nrf70-fw-patch-ext-flash`` snippet or with Partition Manager (``SB_CONFIG_PARTITION_MANAGER``). +When using the ``nrf70-fw-patch-ext-flash`` snippet, set ``SB_CONFIG_WIFI_PATCHES_EXT_FLASH_STORE``, and disable ``SB_CONFIG_PARTITION_MANAGER``. For example, to build the :ref:`wifi_shell_sample` sample for the nRF5340 DK with the ``nrf70-fw-patch-ext-flash`` snippet enabled, run the following commands. diff --git a/doc/nrf/device_guides/nrf70/nrf70_fw_patch_update.rst b/doc/nrf/device_guides/nrf70/nrf70_fw_patch_update.rst index 75fea2293777..15595064df2a 100644 --- a/doc/nrf/device_guides/nrf70/nrf70_fw_patch_update.rst +++ b/doc/nrf/device_guides/nrf70/nrf70_fw_patch_update.rst @@ -13,8 +13,8 @@ This guide explains the available option for updating the nRF70 Series firmware External memory refers to the memory that is outside the System-on-Chip (SoC), for example, an external flash memory chip, or an external nonvolatile memory (NVM) chip. .. note:: - Currently, you cannot build an example with the both :kconfig:option:`SB_CONFIG_WIFI_PATCHES_EXT_FLASH_STORE` and :kconfig:option:`CONFIG_XIP_SPLIT_IMAGE` Kconfig options enabled. - To enable XIP support use the :kconfig:option:`SB_CONFIG_WIFI_PATCHES_EXT_FLASH_XIP` Kconfig option instead of the :kconfig:option:`SB_CONFIG_WIFI_PATCHES_EXT_FLASH_STORE` Kconfig option. + Currently, you cannot build an example with the both ``SB_CONFIG_WIFI_PATCHES_EXT_FLASH_STORE`` and :kconfig:option:`CONFIG_XIP_SPLIT_IMAGE` Kconfig options enabled. + To enable XIP support use the ``SB_CONFIG_WIFI_PATCHES_EXT_FLASH_XIP`` Kconfig option instead of the ``SB_CONFIG_WIFI_PATCHES_EXT_FLASH_STORE`` Kconfig option. Overview ======== @@ -35,7 +35,7 @@ To use this feature, ensure that the following prerequisites are met: * The external memory has sufficient capacity to accommodate the firmware patches. This includes additional space for potential patch upgrades, such as those required for DFU. The combined size of all firmware patches should not exceed 128 kB. -* MCUboot is enabled, and the :kconfig:option:`SB_CONFIG_BOOTLOADER_MCUBOOT` Kconfig option is set to ``y``. +* MCUboot is enabled, and the ``SB_CONFIG_BOOTLOADER_MCUBOOT`` Kconfig option is set to ``y``. Supported platforms =================== @@ -164,12 +164,12 @@ To enable the DFU procedure for the nRF70 Series firmware patch, complete the fo * For the nRF5340 DK without the network core: 1. Set the :kconfig:option:`CONFIG_NRF_WIFI_FW_PATCH_DFU` Kconfig option to ``y``. - #. Set the :kconfig:option:`SB_CONFIG_MCUBOOT_UPDATEABLE_IMAGES` Kconfig option to ``2``. + #. Set the ``SB_CONFIG_MCUBOOT_UPDATEABLE_IMAGES`` Kconfig option to ``2``. * For the nRF5340 DK with the network core: 1. Set the :kconfig:option:`CONFIG_NRF_WIFI_FW_PATCH_DFU`` Kconfig option to ``y``. - #. Set the :kconfig:option:`SB_CONFIG_MCUBOOT_UPDATEABLE_IMAGES` Kconfig option to ``3``. + #. Set the ``SB_CONFIG_MCUBOOT_UPDATEABLE_IMAGES`` Kconfig option to ``3``. For example, to build the sample with the DFU procedure for the nRF70 Series firmware patch on the nRF5340 DK platform, which includes the network core image, run the following commands: @@ -198,7 +198,7 @@ For example, to build the sample with the DFU procedure for the nRF70 Series fir -- -DSHIELD=nrf7002ek -DSB_CONFIG_WIFI_PATCHES_EXT_FLASH_STORE=y -DCONFIG_NRF_WIFI_FW_PATCH_DFU=y -DSB_CONFIG_MCUBOOT_UPDATEABLE_IMAGES=3 -If you want to use the :ref:`ug_multi_image` feature, you need to set the :kconfig:option:`SB_CONFIG_DFU_MULTI_IMAGE_PACKAGE_WIFI_FW_PATCH` Kconfig option to ``y``, and must also set the :kconfig:option:`CONFIG_DFU_MULTI_IMAGE_MAX_IMAGE_COUNT` Kconfig option to one of the following values: +If you want to use the :ref:`sysbuild_images` feature, you need to set the ``SB_CONFIG_DFU_MULTI_IMAGE_PACKAGE_WIFI_FW_PATCH`` Kconfig option to ``y``, and must also set the :kconfig:option:`CONFIG_DFU_MULTI_IMAGE_MAX_IMAGE_COUNT` Kconfig option to one of the following values: * For the nRF5340 DK without the network core: ``2`` * For the nRF5340 DK with the network core: ``3`` diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_architecture_boot.rst b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_architecture_boot.rst index f356ea06b4d1..8392e6a61f41 100644 --- a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_architecture_boot.rst +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_architecture_boot.rst @@ -45,10 +45,10 @@ Boot stages .. to review -The Secure Domain boots the System Controller, the Application Core, and the Radio Core: +The Secure Domain boots the System Controller, the application core, and the radio core: * VPRs (PPR, FLPR) are started by their owners when the owners decide. -* PPR and FLPR are owned by the Application Core in most applications, but any of them can be reassigned to the Radio Core. +* PPR and FLPR are owned by the application core in most applications, but any of them can be reassigned to the radio core. See the following overview of the boot sequence, where the left-most block indicates what starts first from when power-on reset is applied. diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_architecture_cpu.rst b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_architecture_cpu.rst index 58b683520ea4..1c82309fa242 100644 --- a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_architecture_cpu.rst +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_architecture_cpu.rst @@ -27,25 +27,25 @@ The CPU cores in the nRF54H20 are based on two types of CPU architectures: The VPR (pronounced “Viper”) is a small, efficient CPU developed by Nordic Semiconductor. It is compatible with the RISC-V instruction set. -Application Core +Application core **************** -The following image shows the Application Core: +The following image shows the application core: .. figure:: images/nRF54H20_appcore.svg - :alt: Application Core + :alt: Application core - Application Core + Application core -The Application Core contains the Arm Cortex-M33 CPU with the highest processing power in the system. +The application core contains the Arm Cortex-M33 CPU with the highest processing power in the system. Its purpose is to run the main application. It is also designed to have the highest active power efficiency, meaning it can run computing-intensive operations at an optimal power consumption. Due to Dynamic Voltage and Frequency Scaling (DVFS) support and power efficiency optimizations, it takes some time for it to start and stop. -That is why the workloads that require frequent starting and stopping are better suited to run either on the Radio Core or the PPR and FLPR processors. +That is why the workloads that require frequent starting and stopping are better suited to run either on the radio core or the PPR and FLPR processors. Moreover, the clock speed of the processor is very high compared to the low-leakage peripherals running at 16 MHz. -This means that in a code frequently accessing peripheral registers, the Application Core wastes multiple cycles waiting for the peripherals to respond. +This means that in a code frequently accessing peripheral registers, the application core wastes multiple cycles waiting for the peripherals to respond. Code requiring a lot of accesses to low-leakage peripherals in the Global Domain is better suited to run on the PPR processor if efficiency is a key concern. 32 kB of local RAM, which is configured like a Tightly Coupled Memory (TCM) and is accessible single-cycle, is provided. @@ -56,17 +56,17 @@ This can be used by timing-sensitive code that cannot tolerate variable latency Dynamic switching of voltage and frequency will be enabled at a later date. In later versions, developers will be able to select an optimal clock frequency at run time, depending on the task at hand. -Radio Core +Radio core ********** -The following image shows the Radio Core: +The following image shows the radio core: .. figure:: images/nRF54H20_radiocore.svg - :alt: Radio Core + :alt: Radio core - Radio Core + Radio core -The Radio Core is intended to run the radio protocol stacks, such as Bluetooth® Low Energy, IEEE 802.15.4, Thread, Enhanced ShockBurst (ESB), or other proprietary protocols. +The radio core is intended to run the radio protocol stacks, such as Bluetooth® Low Energy, IEEE 802.15.4, Thread, Enhanced ShockBurst (ESB), or other proprietary protocols. It is also possible to implement a combination of protocols that use multiprotocol support. .. note:: @@ -75,18 +75,18 @@ It is also possible to implement a combination of protocols that use multiprotoc Any remaining processing power of this core can be used for tasks other than the ones required by the radio protocol stacks. The main CPU in the Radio Domain is an Arm Cortex-M33 running at a fixed clock speed of 256 MHz and is optimized for quick starts and stops, which are frequent in protocol stack workloads. -Other workloads with similar characteristics are also well suited for running on the Radio Core. +Other workloads with similar characteristics are also well suited for running on the radio core. .. note:: The protocol stack software may need to run at the highest priority to meet its timing requirements. If that is the case, the user code needs to run at lower priority. -The Radio Core has 192 kB of local RAM, making single-cycle memory accesses possible. +The radio core has 192 kB of local RAM, making single-cycle memory accesses possible. -For performance reasons, the Radio Core includes its own AES-128 hardware accelerator for implementing link-layer encryption. +For performance reasons, the radio core includes its own AES-128 hardware accelerator for implementing link-layer encryption. For asymmetric cryptography, it relies on services provided by the Secure Domain. -The Radio Core is user-programmable, allowing you to modify or add code. +The radio core is user-programmable, allowing you to modify or add code. You can also leave the core running Nordic's default protocol stack software and only engage with its high-level interface. While the Radio CPU or any peripheral in Radio's local APB2 bus (including the radio) is active, the 32 MHz crystal oscillator is enabled, and the radio itself is clocked from this clock source. @@ -96,7 +96,7 @@ Global Domain The Global Domain contains most of the memory and peripherals of the nRF54H20. This offers flexibility to assign memory regions and peripherals to different cores. -If this flexibility is not needed, it is possible to use the |NCS| defaults, where most of the memory and peripherals are assigned to the Application Core. +If this flexibility is not needed, it is possible to use the |NCS| defaults, where most of the memory and peripherals are assigned to the application core. The Global Domain includes two sets of power domains: @@ -157,12 +157,12 @@ Cores managed by Nordic Semiconductor This means that the components can be modified by Nordic Semiconductor only. Cores managed by the user and Nordic Semiconductor - Firmware for the Radio Core will come as part of the |NCS|. - You can either use the default Nordic’s Radio Core firmware, modify it, or provide a custom implementation. + Firmware for the radio core will come as part of the |NCS|. + You can either use the default Nordic’s radio core firmware, modify it, or provide a custom implementation. If you rely on Nordic to provide the firmware, the default correct controller library will be used depending on the short-range protocol selected in the software configuration. Cores managed by the user - Although there are multiple distinctive cores in the system, you will be responsible mostly for preparing the firmware for the Application Core. + Although there are multiple distinctive cores in the system, you will be responsible mostly for preparing the firmware for the application core. If the application firmware is executed in non-secure mode, the secure firmware (TF-M) is delivered as part of the |NCS|. - You can choose to move some of the processing from the Application Core to the Peripheral Processor (PPR) or to the Fast Lightweight Processor (FLPR). + You can choose to move some of the processing from the application core to the Peripheral Processor (PPR) or to the Fast Lightweight Processor (FLPR). diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_architecture_ipc.rst b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_architecture_ipc.rst index e745508db887..011720430619 100644 --- a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_architecture_ipc.rst +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_architecture_ipc.rst @@ -87,7 +87,7 @@ The following tables show signals received only by specified cores. FLPR 13 ================= ========== - Radio Core: + Radio core: This assignment applies only when BBPROC owner is set to the Radio. @@ -105,8 +105,8 @@ MAC, Network, Transport The layers responsible for maintaining a stable full-duplex stream of data between two cores (MAC, Network, Transport) are implemented in an IPC transport library. The default IPC transport library for nRF54H20 is :ref:`ICMsg `. This lightweight library maintains the connection between a pair of cores for each IPC instance with minimal memory overhead. -Each IPC instance between the Application Core and the PPR core requires an instance of the ICMsg library. -Each IPC instance between the Application Core and cores other than PPR (like the Radio Core) requires an instance of the ICBMsg library. +Each IPC instance between the application core and the PPR core requires an instance of the ICMsg library. +Each IPC instance between the application core and cores other than PPR (like the radio core) requires an instance of the ICBMsg library. Each ICMsg library instance requires the following: @@ -172,15 +172,15 @@ The following figures show the IPC connection schemes in the nRF54H20 SoC: Radio core ========== -The Radio core exposes radio communication services to the Application Core through IPC. +The Radio core exposes radio communication services to the application core through IPC. These services include: * Bluetooth® (HCI or host API) * IEEE 802.15.4 radio driver API -These services are hidden behind Zephyr APIs available in the Application Core, like the Bluetooth host API or the IEEE 802.15.4 driver API. +These services are hidden behind Zephyr APIs available in the application core, like the Bluetooth host API or the IEEE 802.15.4 driver API. All services can be enabled simultaneously using separated endpoints in a shared IPC instance. -You can implement other services running in the Radio Core and expose them to the Application Core using more endpoints from the shared IPC instance. +You can implement other services running in the radio core and expose them to the application core using more endpoints from the shared IPC instance. Secure Domain core ================== @@ -223,4 +223,4 @@ Peripheral Processor (PPR) The Peripheral Processor (PPR) exposes IPC communication for its owner to manage its operations. The communication details depends on the PPR role in the system. -In the :ref:`nrf_machine_learning_app` application, PPR uses an :ref:`event_manager_proxy` through IPC to extend the Event Manager framework running in the Application Core. +In the :ref:`nrf_machine_learning_app` application, PPR uses an :ref:`event_manager_proxy` through IPC to extend the Event Manager framework running in the application core. diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_architecture_memory.rst b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_architecture_memory.rst index a1087ffdc255..c2e3d43ae787 100644 --- a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_architecture_memory.rst +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_architecture_memory.rst @@ -39,15 +39,15 @@ Local RAM Local RAM is present in each of local domains -Application Core RAM +Application core RAM -------------------- .. image:: images/nrf54h20_memory_map_app.svg :width: 300 px -The Application Core contains 32 KB of local RAM. -Accessing this memory from the Application Core CPU has minimal latency, but accessing it from any other core adds significant latency. -Because of this property, the local RAM in the application domain should be used mainly to store data frequently accessed by the Application Core, or to store timing-critical parts of the code executed by Application Core. +The application core contains 32 KB of local RAM. +Accessing this memory from the application core CPU has minimal latency, but accessing it from any other core adds significant latency. +Because of this property, the local RAM in the application domain should be used mainly to store data frequently accessed by the application core, or to store timing-critical parts of the code executed by the application core. Address range 0x22000000 - 0x22008000 @@ -56,24 +56,24 @@ Size 32 KB Access control - Application domain local RAM is accessible by the Application Core. - Any core (like FLPR or PPR) or peripheral configured to be owned by Application Core (like UARTE or SAADC) can access this memory as well. + Application domain local RAM is accessible by the application core. + Any core (like FLPR or PPR) or peripheral configured to be owned by application core (like UARTE or SAADC) can access this memory as well. Any core with access to this memory can execute code from it. - If the TrustZone feature is enabled for Application Core, this memory can be partitioned in one secure and one non-secure region. + If the TrustZone feature is enabled for the application core, this memory can be partitioned in one secure and one non-secure region. The secure region is accessible only by code executed with the secure attribute, while the non-secure region is accessible by any code. .. note:: Code executed by VPRs (like FLPR or PPR) has its secure attribute matching the given VPR security configuration in the SPU. Local RAM cannot include a Non-Secure Callable section. -Radio Core RAM +Radio core RAM -------------- -The Radio Core contains 96 KB of local RAM. -Any access to this memory has minimal latency if originated either from Radio Core CPU or from peripherals with EasyDMA located in the Radio Core. +The radio core contains 96 KB of local RAM. +Any access to this memory has minimal latency if originated either from radio core CPU or from peripherals with EasyDMA located in the radio core. Any access from any other core has a significant latency. -Because of this property, local RAM in the Radio Core should be used mainly to store data frequently accessed by the Radio Core CPU or the radio protocol frames to be accessed by CCM or RADIO peripherals, or to store timing critical parts of the code executed by the Radio Core CPU. +Because of this property, local RAM in the radio core should be used mainly to store data frequently accessed by the radio core CPU or the radio protocol frames to be accessed by CCM or RADIO peripherals, or to store timing critical parts of the code executed by the radio core CPU. Address range 0x23000000 - 0x23030000 @@ -82,11 +82,11 @@ Size 192 KB Access control - The Radio Core local RAM is accessible by the Radio Core. - Any core (like FLPR or PPR) or peripheral configured to be owned by the Radio Core (like UARTE or SAADC) can access this memory as well. + The radio core local RAM is accessible by the radio core. + Any core (like FLPR or PPR) or peripheral configured to be owned by the radio core (like UARTE or SAADC) can access this memory as well. Any core with access to this memory can execute code from it. - If the TrustZone feature is enabled for the Radio Core, this memory can be partitioned in one secure and one non-secure region. + If the TrustZone feature is enabled for the radio core, this memory can be partitioned in one secure and one non-secure region. The secure region is accessible only by code executed with the secure attribute, while the non-secure region is accessible by any code. .. note:: @@ -98,7 +98,7 @@ BBPROC memory The Lower 32 KB of local RAM in the Radio Domain is tightly coupled with BBPROC. Any access to this memory has minimal latency if originated from BBPROC. -Any access originated from the Radio Core or from peripherals with EasyDMA located in radio domain have a little greater latency while accessing BBPROC memory. +Any access originated from the radio core or from peripherals with EasyDMA located in radio domain have a little greater latency while accessing BBPROC memory. Access from other domains is possible, but with significant latency. BBPROC memory is the only memory from which BBPROC can fetch its instructions. @@ -135,7 +135,7 @@ Access to this memory is relatively fast from all the local domains (like the Ap Access to this memory from DMA used by USB has minimal latency. This memory is intended to store the majority of the data used by local cores (and does not fit in local domains' RAM) including shared memory used for Inter-Processor Communication (IPC) between local cores. -Buffers for USB data must be stored in this memory part, in the region owned by the core owning USB (usually the Application Core in typical applications). +Buffers for USB data must be stored in this memory part, in the region owned by the core owning USB (usually the application core in typical applications). Address range 0x2F000000 - 0x2F0C0000 @@ -212,8 +212,8 @@ Access control Because of this property, the FLPR's owner indirectly obtains access to the entire RAM21 memory region. To avoid security risks, all the partitions in RAM21 must be assigned to the FLPR's owner. Also, all peripherals with DMA buffers in this memory must be assigned to the FLPR's owner. - The FLPR and the fast peripherals are by default owned by the Application Core. - This ownership and matching memory access rights can be reassigned to the Radio Core in the UICR. + The FLPR and the fast peripherals are by default owned by the application core. + This ownership and matching memory access rights can be reassigned to the radio core in the UICR. The security attribute of memory partitions DMA engines must follow the FLPR security settings. @@ -235,7 +235,7 @@ Size Access control The PPR and its owner have access to all the partitions assigned to the PPR and its Inter-Processor Communication. Each of the memory partition assigned for DMA of the slow peripherals is accessible from the core owning the given set of peripherals. - The PPR and the slow peripherals are by default owned by the Application Core. + The PPR and the slow peripherals are by default owned by the application core. The ownership and matching memory access rights can be customized in UICRs. The security attribute of memory partitions must follow PPR and DMA engines' security settings. @@ -255,7 +255,7 @@ The MRAM_10 is a part of the non-volatile memory intended to keep firmware image Access to this memory has minimal latency to avoid CPU stalls on instruction fetches. This part of the memory is not writable while the main application is running (it is writable only during the Firmware Upgrade procedure) to avoid any latency caused by write operations. Apart from executable code images, this part of the memory stores the Secure Information Configuration Registers (SICR) used by the programs running in the Secure Domain Core. -If code and data for the Application Core do not fit in MRAM_10, it can be partially or fully placed in MRAM_11. +If code and data for the application core do not fit in MRAM_10, it can be partially or fully placed in MRAM_11. Address range 0x0E000000 - 0x0E100000 @@ -264,7 +264,7 @@ Size 1024 KB Access control - The Application Core and the Radio Core have read and execute access to memory regions assigned to them. + The application core and the radio core have read and execute access to memory regions assigned to them. If TrustZone is disabled for any of these cores, then the assigned memory region is a single block containing secure code and data. If TrustZone is enabled for any of these cores, then the assigned memory region is split in three blocks: @@ -289,7 +289,7 @@ When a core is reading or executing code from MRAM_11, the impact of the additio Each of the local cores (Application, Radio, Secure Domain) has an allocated partition in MRAM_11 to store their non-volatile data. Each of the cores has full control on the data layout and management in the assigned MRAM partition. There is also a Device Firmware Upgrade partition used to store firmware images used during the upgrade procedure. -If code and data for the Application Core do not fit in MRAM_10, it can be partially or fully placed in MRAM_11. +If code and data for the application core do not fit in MRAM_10, it can be partially or fully placed in MRAM_11. .. to review @@ -300,10 +300,10 @@ Size 1024 KB Access control - The Application Core and the Radio Core have read and write access to their assigned non-volatile data regions. + The application core and the radio core have read and write access to their assigned non-volatile data regions. The non-volatile data region assigned to the core having TrustZone disabled is marked as Secure, while the non-volatile data region assigned to the core having TrustZone enabled is marked as Non-Secure. - If code or data for the Application Core is placed in MRAM_11, the Application Core has *read and execute* access to this partition. + If code or data for the application core is placed in MRAM_11, the application core has *read and execute* access to this partition. This access can be configured as follows: * Default configuration, in which all the application code and data is placed in MRAM_10. @@ -315,5 +315,5 @@ Access control Because of the continuous memory address range, it is possible to use a single memory region to describe such data block. The Secure Domain has access to all the parts of MRAM_11. - The Application Core has read and write access to the DFU partition. - The security configuration of this partition follows the TrustZone configuration of the Application Core (Secure if TrustZone is disabled, or Non-Secure if TrustZone is enabled). + The application core has read and write access to the DFU partition. + The security configuration of this partition follows the TrustZone configuration of the application core (Secure if TrustZone is disabled, or Non-Secure if TrustZone is enabled). diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_configuration.rst b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_configuration.rst index a4c35be69e49..f546291a7ae6 100644 --- a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_configuration.rst +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_configuration.rst @@ -38,7 +38,7 @@ The following is the DTS file structure implemented for all the SoCs of the 54H * Product-specific overlays applicable to all cores​ * Project-wide overlays -The following is the include tree for the Application Core of the nRF54H20 (cpuapp): +The following is the include tree for the application core of the nRF54H20 (cpuapp): .. figure:: images/cpuapp_include_tree.svg :alt: nRF54H20 CPUAPP include tree @@ -63,9 +63,9 @@ Generated HEX files When building an application for the nRF54H20 DK, you are building all domain images at once. During this process, the following :file:`zephyr.hex` images are built: -* Application Core application +* Application core application * PPR core application -* Radio Core firmware +* Radio core firmware Additionally, the following user information configuration registers (UICR) contents (:file:`uicr.hex`) are generated for setup access for domains: diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_debugging.rst b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_debugging.rst index 054cfbdcd7bd..dc51d72a5f1f 100644 --- a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_debugging.rst +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_debugging.rst @@ -39,10 +39,10 @@ To debug single-core applications, you can use the ``west debug`` command to sta Debugging multi-core applications ********************************* -To debug the firmware running also on cores other than the Application Core, you need to set up a separate debug session for each one of the cores you want to debug. -When debugging another core, the Application Core debug session runs in the background and you can debug both cores if needed. +To debug the firmware running also on cores other than the application core, you need to set up a separate debug session for each one of the cores you want to debug. +When debugging another core, the application core debug session runs in the background and you can debug both cores if needed. -If you want to reset the other cores while debugging, make sure to first reset the Application Core and execute the code. +If you want to reset the other cores while debugging, make sure to first reset the application core and execute the code. Using GDB as an external debugger ********************************* @@ -52,9 +52,9 @@ The DAP is a standard Arm® CoreSight™ serial wire debug port (SWJ-DP) that im There are several access ports that connect to different parts of the system: - * AHB-AP 0: Application Core access port ID - * AHB-AP 1: Radio core access port ID - * AHB-AP 2: Secure domain access port ID + * AHB-AP 0: application core access port ID + * AHB-AP 1: radio core access port ID + * AHB-AP 2: Secure Domain access port ID * AHB-AP 3: Auxiliary access port ID * CTRL-AP 4: Device level control access port ID * APB-AP 5: CoreSight™ subsystem access port ID @@ -66,7 +66,7 @@ Selecting the core To debug a specific core using ``JLinkExe`` do the following: -1. Run J-Link on the Application Core:: +1. Run J-Link on the application core:: JLinkExe -USB -if SWD -Device Cortex-M33 @@ -82,7 +82,7 @@ To debug a specific core using ``JLinkExe`` do the following: .. note:: PPR core debugging is not functional in the initial limited sampling. -#. Connect to the Application Core:: +#. Connect to the application core:: exec CORESIGHT_SetIndexAHBAPToUse = connect diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_gs.rst b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_gs.rst index 4ce37f983844..abfa96eece6a 100644 --- a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_gs.rst +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_gs.rst @@ -7,16 +7,9 @@ Getting started with the nRF54H20 DK :local: :depth: 2 -This section gets you started with your nRF54H20 Development Kit (DK) using the |NCS|. +This document gets you started with your nRF54H20 Development Kit (DK) using the |NCS|. It tells you how to install the :zephyr:code-sample:`sysbuild_hello_world` sample and perform a quick test of your DK. -If you have already set up your nRF54H20 DK and want to learn more, see the following documentation: - -* :ref:`configuration_and_build` documentation to learn more about the |NCS| development environment. -* :ref:`ug_nrf54h` documentation for more advanced topics related to the nRF54H20. - -If you want to go through an online training course to familiarize yourself with Bluetooth® Low Energy and the development of Bluetooth LE applications, enroll in the `Bluetooth LE Fundamentals course`_ in the `Nordic Developer Academy`_. - .. _ug_nrf54h20_gs_requirements: Minimum requirements @@ -27,51 +20,57 @@ Make sure you have all the required hardware and that your computer has one of t Hardware ======== -* nRF54H20 DK version PCA10175 v0.7.x or v0.8.0 (ES3). - Check the version number on your DK's sticker to verify its compatibility with |NCS| version 2.6.99-cs2. +* nRF54H20 DK version PCA10175 v0.7.2 (ES3) or PCA10175 v0.8.0 (ES3.3, ES4). + These are the only versions of the nRF54H20 DK compatible with the |NCS| v2.7.0. + Check the version number on your DK's sticker to verify its compatibility with the |NCS| version v2.7.0. * USB-C cable. - Software ======== On your computer, one of the following operating systems: -* Microsoft Windows -* Ubuntu Linux -* macOS +.. include:: ../../../../nrf/installation/recommended_versions.rst + :start-after: os_table_start + :end-before: os_table_end + +See :ref:`supported_OS` for more information about the tier definitions. |supported OS| You also need the following: -* `Git`_ or `Git for Windows`_ (on Linux and Mac, or Windows, respectively) -* `curl`_ -* On Windows, SEGGER USB Driver for J-Link included in `J-Link version 7.88j`_ -* SEGGER `J-Link version 7.94e`_ +* `Git`_ or `Git for Windows`_ (on Linux and Mac, or Windows, respectively). +* `curl`_. +* The latest version of the `nRF Command Line Tools`_ package. + After downloading and installing the tools, add the nrfjprog executable to the system path, on Linux and MacOS, or to the environment variables, on Windows. + This allows you to run it from anywhere on the system. -.. note:: - The SEGGER USB Driver for J-Link is not included in J-Link v7.94e. - To install the driver, do the following: + .. note:: + Before running the initial J-Link installation from the `nRF Command Line Tools`_ package, ensure not to have any other J-Link executables on your system. + If you have other J-Link installations, uninstall them before proceeding. + +* On Windows, SEGGER USB Driver for J-Link from SEGGER `J-Link version 7.94e`_. - 1. Install `J-Link version 7.88j`_ - When installing SEGGER J-Link 7.88j on Windows, select the following optional components in the installer: + .. note:: + To install the SEGGER USB Driver for J-Link on Windows, you must manually reinstall J-Link v7.94e from the command line using the ``-InstUSBDriver=1`` parameter, updating the installation previously run by the `nRF Command Line Tools`_: - * :guilabel:`Install USB Driver for J-Link (requires admin rights)`. - * Under :guilabel:`Choose destination`, select :guilabel:`Install a new instance`. + 1. Navigate to the download location of the J-Link executable and run one of the following commands: - See the following screenshot: + * From the Command Prompt:: - .. figure:: images/jlink788j_install.png - :alt: Optional components in the J-Link v7.88j installation + JLink_Windows_V794e_x86_64.exe -InstUSBDriver=1 - #. Update to `J-Link version 7.94e`_ - When updating SEGGER J-Link to version 7.94e on Windows, select :guilabel:`Update existing installation` under :guilabel:`Choose destination` in the :guilabel:`choose optional components` window. + * From PowerShell:: - See the following screenshot: + .\JLink_Windows_V794e_x86_64.exe -InstUSBDriver=1 - .. figure:: images/jlink794e_install.png - :alt: Optional components in the J-Link v7.94e installation + #. In the :guilabel:`Choose optional components` window, select :guilabel:`update existing installation`. + #. Add the J-Link executable to the system path on Linux and MacOS, or to the environment variables on Windows, to run it from anywhere on the system. + +* The latest version of |VSC| for your operating system from the `Visual Studio Code download page`_. +* In |VSC|, the latest version of the `nRF Connect for VS Code Extension Pack`_. +* On Linux, the `nrf-udev`_ module with udev rules required to access USB ports on Nordic Semiconductor devices and program the firmware. .. _ug_nrf54h20_gs_installing_software: @@ -82,175 +81,109 @@ To work with the nRF54H20 DK, follow the instructions in the next sections to in .. _ug_nrf54h20_install_toolchain: -Installing the toolchain -======================== - -You can install the toolchain for the customer sampling of the |NCS| by running an installation script. -Follow these steps: - -.. tabs:: - - .. tab:: Windows - - 1. Open Git Bash. - #. Download and run the :file:`bootstrap-toolchain.sh` installation script file using the following command: - - .. parsed-literal:: - :class: highlight - - curl --proto '=https' --tlsv1.2 -sSf https://files.nordicsemi.com/artifactory/swtools/external/scripts/bootstrap-toolchain.sh | NCS_TOOLCHAIN_VERSION=v2.6.99-cs2 sh - - Depending on your connection, this might take some time. - #. Open a new terminal window with the |NCS| toolchain environment by running the following command: - - .. parsed-literal:: - :class: highlight - - c:/ncs-lcs/nrfutil.exe toolchain-manager launch --terminal --chdir "c:/ncs-lcs/work-dir" --ncs-version v2.6.99-cs2 - - This setup allows you to access west and other development tools. - Alternatively, you can set up the environment variables manually by running the following command:: - - c:/ncs-lcs/nrfutil.exe toolchain-manager env --as-script - - Copy-paste the output into the terminal and execute it to enable the use of west directly in that window. - - .. note:: - WWhen working with west in the customer sampling release, you must always use a terminal window with the |NCS| toolchain environment. - - If you run into errors during the installation process, delete the :file:`.west` folder inside the :file:`C:\\ncs-lcs` directory, and start over. - - .. tab:: Linux - - 1. Open a terminal window. - #. Download and run the :file:`bootstrap-toolchain.sh` installation script file using the following command: - - .. parsed-literal:: - :class: highlight - - curl --proto '=https' --tlsv1.2 -sSf https://files.nordicsemi.com/artifactory/swtools/external/scripts/bootstrap-toolchain.sh | NCS_TOOLCHAIN_VERSION=v2.6.99-cs2 sh - - Depending on your connection, this might take some time. - #. Open a new terminal window with the |NCS| toolchain environment by running the following command: - - .. parsed-literal:: - :class: highlight - - $HOME/ncs-lcs/nrfutil toolchain-manager launch --shell --chdir "$HOME/ncs-lcs/work-dir" --ncs-version v2.6.99-cs2 +Installing the |NCS| v2.7.0 and its toolchain +********************************************* - .. note:: - When working with west in the customer sampling release, you must always use a shell window with the |NCS| toolchain environment. +You can install the |NCS| v2.7.0 and its toolchain by using Toolchain Manager. - If you run into errors during the installation process, delete the :file:`.west` folder inside the :file:`ncs-lcs` directory, and start over. +Toolchain Manager is a tool available from `nRF Connect for Desktop`_, a cross-platform tool that provides different applications that simplify installing the |NCS|. +Both the tool and the application are available for Windows, Linux, and MacOS. - .. tab:: macOS +To install the toolchain and the SDK using the Toolchain Manager app, complete the following steps: - 1. Open a terminal window. - #. Install `Homebrew`_: +1. Install Toolchain Manager: - .. code-block:: bash + a. `Download nRF Connect for Desktop`_ for your operating system. + #. Install and run the tool on your machine. + #. In the **APPS** section, click :guilabel:`Install` next to Toolchain Manager. - /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" + The app is installed on your machine, and the :guilabel:`Install` button changes to :guilabel:`Open`. - #. Use the ``brew`` command to install the required dependencies: +#. Install the |NCS| source code: - .. code-block:: bash + a. Open Toolchain Manager in nRF Connect for Desktop. - brew install cmake ninja gperf python3 ccache qemu dtc wget libmagic + .. figure:: ../../../../nrf/installation/images/gs-assistant_tm.png + :alt: The Toolchain Manager window - Ensure that these dependencies are installed with their versions as specified in the :ref:`Required tools table `. - To check the installed versions, run the following command: + The Toolchain Manager window - .. parsed-literal:: - :class: highlight + #. Click :guilabel:`SETTINGS` in the navigation bar to specify where you want to install the |NCS|. + #. In :guilabel:`SDK ENVIRONMENTS`, click the :guilabel:`Install` button next to the |NCS| version 2.7.0. - brew list --versions + The |NCS| version 2.7.0 is installed on your machine. + The :guilabel:`Install` button changes to :guilabel:`Open VS Code`. - #. Download and run the :file:`bootstrap-toolchain.sh` installation script file using the following command: +#. Set up the preferred building method: - .. parsed-literal:: - :class: highlight + .. tabs:: - curl --proto '=https' --tlsv1.2 -sSf https://files.nordicsemi.com/artifactory/swtools/external/scripts/bootstrap-toolchain.sh | NCS_TOOLCHAIN_VERSION=v2.6.99-cs2 sh + .. tab:: nRF Connect for Visual Studio Code - Depending on your connection, this might take some time. + To build on the |nRFVSC|, complete the following steps: - .. note:: - On macOS, the install directory is :file:`/opt/nordic/ncs`. - This means that creating the directory requires root access. - You will be prompted to grant the script admin rights for the creation of the folder on the first install. - The folder will be created with the necessary access rights to the user, so subsequent installs do not require root access. + a. In Toolchain Manager, click the :guilabel:`Open VS Code` button. - Do not run the toolchain-manager installation as root (for example, using `sudo`). - It restricts access to the root user only, meaning you will need the root access for any subsequent installations. - If you run the script as root, to fix permissions delete the installation folder and run the script again as a non-root user. + A notification appears with a list of missing extensions that you need to install, including those from the `nRF Connect for Visual Studio Code`_ extension pack. + #. Click **Install missing extensions**, then close VS Code. + #. Once the extensions are installed, click **Open VS Code** button again. - #. Open a new terminal window with the |NCS| toolchain environment by running the following command: + You can then follow the instructions in :ref:`creating_vsc`. - .. parsed-literal:: - :class: highlight + .. tab:: Command line - /Users/*yourusername*/ncs-lcs/nrfutil toolchain-manager launch --shell --chdir "/Users/*yourusername*/ncs-lcs/work-dir" --ncs-version v2.6.99-cs2 + To build on the command line, complete the following steps: - .. note:: - When working with west in the customer sampling release, you must always use a shell window with the |NCS| toolchain environment. + 1. With admin permissions enabled, download and install the `nRF Command Line Tools`_. + #. Restart the Toolchain Manager application. + #. Click the dropdown menu for the installed nRF Connect SDK version. - #. Run the following commands in your terminal to install the correct lxml dependency: + .. figure:: ../../../../nrf/installation/images/gs-assistant_tm_dropdown.png + :alt: The Toolchain Manager dropdown menu for the installed nRF Connect SDK version, cropped - .. parsed-literal:: - :class: highlight + The Toolchain Manager dropdown menu options - pip uninstall -y lxml - pip install lxml + #. Select :guilabel:`Open command prompt`. - If you run into errors during the installation process, delete the :file:`.west` folder inside the :file:`ncs-lcs` directory, and start over. + You can then follow the instructions in :ref:`creating_cmd`. -We recommend adding the nRF Util path to your environmental variables. - -.. _ug_nrf54h20_install_ncs: - -Installing the |NCS| -==================== - -After you have installed the toolchain, complete the following steps to get the customer sampling version of the |NCS|: +Installing the Terminal application +*********************************** -1. In the terminal window opened during the toolchain installation, initialize west with the revision of the |NCS| from the customer sampling: +On your computer, install `nRF Connect for Desktop`_. +You must also install a terminal emulator, such as `nRF Connect Serial Terminal`_ (from the nRF Connect for Desktop application) or the nRF Terminal (part of the `nRF Connect for Visual Studio Code`_ extension). - .. parsed-literal:: - :class: highlight +Installing nRF Util and its commands +************************************ - west init -m https://github.com/nrfconnect/sdk-nrf --mr v2.6.99-cs2 +Using the nRF54H20 DK with the |NCS| v2.7.0 requires the following: -#. Enter the following command to clone the project repositories:: +* nRF Util version 7.11.1 or above +* nRF Util ``device`` version 2.4.0 - west update +1. Download the nrfutil executable file from the `nRF Util development tool`_ product page. +#. Add nRF Util to the system path on Linux and MacOS, or environment variables on Windows, to run it from anywhere on the system. + On Linux and MacOS, use one of the following options: - Depending on your connection, this might take some time. + * Add nRF Util's directory to the system path. + * Move the file to a directory in the system path. -#. Export a :ref:`Zephyr CMake package `. - This allows CMake to automatically load the boilerplate code required for building |NCS| applications:: +#. On MacOS and Linux, give ``nrfutil`` execute permissions by typing ``chmod +x nrfutil`` in a terminal or using a file browser. + This is typically a checkbox found under file properties. +#. On MacOS, To run the nrfutil executable you need to allow it in the system settings. +#. Verify the version of the nRF Util installation on your machine by running the following command:: - west zephyr-export + nrfutil --version -Your directory structure now looks similar to this:: +#. If your version is below 7.11.1, run the following command to update nRF Util:: - ncs-lcs/work-dir - |___ .west - |___ bootloader - |___ modules - |___ nrf - |___ nrfxlib - |___ zephyr - |___ ... + nrfutil self-upgrade -Note that there are additional folders, and that the structure might change. -The full set of repositories and folders is defined in the manifest file. +#. Install the nRF Util ``device`` command to version 2.4.0 as follows:: -Installing the Terminal application -*********************************** + nrfutil install device=2.4.0 --force -On your computer, install `nRF Connect for Desktop`_. -You must also install a terminal emulator, such as `nRF Connect Serial Terminal`_ (from the nRF Connect for Desktop application) or the nRF Terminal (part of the `nRF Connect for Visual Studio Code`_ extension). +For more information, consult the `nRF Util`_ documentation. .. _ug_nrf54h20_gs_bringup: @@ -268,6 +201,12 @@ The Board Information Configuration Registers (BICR) are non-volatile memory (NV To prepare the nRF54H20 DK for first use, you must manually program the values of the BICR using a precompiled BICR binary file (:file:`bicr_ext_loadcap.hex`). 1. Download the `BICR binary file`_ . +#. Connect the nRF54H20 DK to your computer using the **DEBUGGER** port on the DK. + +.. note:: + On MacOS, connecting the DK might cause a popup containing the message ``“Disk Not Ejected Properly`` to repeatedly appear on screen. + To disable this, run ``JLinkExe``, then run ``MSDDisable`` in the J-Link Commander interface. + #. List all the connected development kits to see their serial number (matching the one on the DK's sticker):: nrfutil device list @@ -281,11 +220,15 @@ To prepare the nRF54H20 DK for first use, you must manually program the values o Programming the SDFW and SCFW ============================= -After programming the BICR, the nRF54H20 SoC requires the provisioning of a bundle ( :file:`nrf54h20_soc_binaries_v0.3.3.zip`) containing the precompiled firmware for the Secure Domain and System Controller. +After programming the BICR, the nRF54H20 SoC requires the provisioning of a bundle ( :file:`nrf54h20_soc_binaries_v0.5.0.zip`) containing the precompiled firmware for the Secure Domain and System Controller. To program the Secure Domain Firmware (SDFW, also known as ``urot``) and the System Controller Firmware (SCFW) from the firmware bundle to the nRF54H20 DK, do the following: -1. Download the `nRF54H20 firmware bundle`_. -#. Move the :file:`ZIP` bundle to a folder of your choice, then run nRF Util to program the binaries using the following command:: +1. Download the `nRF54H20 firmware bundle v0.5.0`_. + + .. note:: + On MacOS, ensure that the ZIP file is not unpacked automatically upon download. + +#. Move the :file:`.zip` bundle to a folder of your choice, then run nRF Util to program the binaries using the following command:: nrfutil device x-provision-nrf54h --firmware --serial-number @@ -294,6 +237,10 @@ To program the Secure Domain Firmware (SDFW, also known as ``urot``) and the Sys Updating the FICR ================= +.. caution:: + This step is required only if your nRF54H20 DK is version PCA10175 v0.7.2 or v0.8.0 ES3.3. + Jump to the next step if your DK is version ES4, meaning v0.8.0 with no ES markings. + After programming the SDFW and SCFW from the firmware bundle, you must update the Factory Information Configuration Registers (FICR) to correctly configure some trims of the nRF54H20 SoC. To update the FICR, you must run a J-Link script: @@ -301,9 +248,15 @@ To update the FICR, you must run a J-Link script: curl -LO https://files.nordicsemi.com/artifactory/swtools/external/scripts/nrf54h20es_trim_adjust.jlink -#. Run the script:: +#. Run the script: + + * Linux and Mac OS:: + + JLinkExe -CommanderScript nrf54h20es_trim_adjust.jlink - JLinkExe -CommanderScript nrf54h20es_trim_adjust.jlink + * Windows:: + + jlink.exe -CommanderScript nrf54h20es_trim_adjust.jlink .. rst-class:: numbered-step @@ -381,21 +334,18 @@ To transition the LCS to ``RoT``, do the following: Programming the sample ********************** -The :zephyr:code-sample:`sysbuild_hello_world` sample is a multicore sample running on both the Application Core (``cpuapp``) and the Peripheral Processor (PPR, ``cpuppr``). +The :zephyr:code-sample:`sysbuild_hello_world` sample is a multicore sample running on both the application core (``cpuapp``) and the Peripheral Processor (PPR, ``cpuppr``). It uses the ``nrf54h20dk/nrf54h20/cpuapp`` board target. To build and program the sample to the nRF54H20 DK, complete the following steps: 1. Connect the nRF54H20 DK to your computer using the **DEBUGGER** port on the DK. -#. Navigate to the :file:`zephyr/samples/sysbuild/hello_world` folder containing the sample. +#. Open nRF Connect for Desktop, navigate to the Toolchain Manager, select the v2.7.0 toolchain, and click the :guilabel:`Open terminal` button. +#. In the terminal window, navigate to the :file:`zephyr/samples/sysbuild/hello_world` folder containing the sample. #. Build the sample for application and radio cores by running the following command:: west build -p -b nrf54h20dk/nrf54h20/cpuapp -T sample.sysbuild.hello_world.nrf54h20dk_cpuapp_cpurad . -#. Alternatively, build the sample for the application and PPR cores by running the following command:: - - west build -p -b nrf54h20dk/nrf54h20/cpuapp -T sample.sysbuild.hello_world.nrf54h20dk_cpuapp_cpuppr . - #. Program the sample. If you have multiple Nordic Semiconductor devices, make sure that only the nRF54H20 DK you want to program is connected. @@ -403,7 +353,7 @@ To build and program the sample to the nRF54H20 DK, complete the following steps west flash -The sample will be automatically built and programmed on both the Application Core and the Peripheral Processor (PPR) of the nRF54H20. +The sample will be automatically built and programmed on both the application core and the Peripheral Processor (PPR) of the nRF54H20. .. include:: /includes/nRF54H20_erase_UICR.txt @@ -412,28 +362,19 @@ The sample will be automatically built and programmed on both the Application Co Reading the logs **************** -With the :zephyr:code-sample:`sysbuild_hello_world` sample programmed, the nRF54H20 DK outputs logs for the Application Core and the configured remote processor. +With the :zephyr:code-sample:`sysbuild_hello_world` sample programmed, the nRF54H20 DK outputs logs for the application core and the configured remote processor. The logs are output over UART. To read the logs from the :zephyr:code-sample:`sysbuild_hello_world` sample programmed to the nRF54H20 DK, complete the following steps: 1. Connect to the DK with a terminal emulator (for example, `nRF Connect Serial Terminal`_) using the :ref:`default serial port connection settings `. #. Press the **Reset** button on the PCB to reset the DK. -#. Observe the console output for both cores: - - * For the Application Core, the output should look like the following: +#. Observe the console output for the application core: - .. code-block:: console - - *** Booting nRF Connect SDK zephyr-v3.5.0-3517-g9458a1aaf744 *** - Hello world from nrf54h20dk/nrf54h20/cpuapp - - * For the remote core, like PPR, the output should be as follows: - - .. code-block:: console + .. code-block:: console - *** Booting nRF Connect SDK zephyr-v3.5.0-3517-g9458a1aaf744 *** - Hello world from nrf54h20dk/nrf54h20/cpuppr + *** Booting nRF Connect SDK zephyr-v3.5.0-3517-g9458a1aaf744 *** + Hello world from nrf54h20dk/nrf54h20/cpuapp .. note:: If no output is shown when using nRF Serial Terminal, select a different serial port in the terminal application. @@ -448,3 +389,7 @@ See the following links for where to go next: * :ref:`ug_nrf54h20_architecture` for information about the multicore System on Chip, such as the responsibilities of the cores and their interprocessor interactions, the memory mapping, and the boot sequence. * The :ref:`introductory documentation ` for more information on the |NCS| and the development environment. +* :ref:`configuration_and_build` documentation to learn more about the |NCS| development environment. +* :ref:`ug_nrf54h` documentation for more advanced topics related to the nRF54H20. + +If you want to go through an online training course to familiarize yourself with Bluetooth® Low Energy and the development of Bluetooth LE applications, enroll in the `Bluetooth LE Fundamentals course`_ in the `Nordic Developer Academy`_. diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_matter_thread.rst b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_matter_thread.rst deleted file mode 100644 index 1c71b6fddc73..000000000000 --- a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_matter_thread.rst +++ /dev/null @@ -1,299 +0,0 @@ -:orphan: - -.. _ug_nrf54h20_matter_thread: - -Working with nRF54H20 and Matter and Thread -########################################### - -.. contents:: - :local: - :depth: 2 - -The nRF54H20 DK supports the following Matter and Thread samples: - -* :ref:`Matter door lock sample ` -* :ref:`Matter template sample ` -* :ref:`Thread CLI sample ` - -The Matter support is currently limited to Matter over Thread, and support for both Matter and Thread is currently :ref:`experimental `. -Read the following sections for more information about support in the nRF54H20 DK and the platform design for the nRF54H20 SoC. - -For more information about Matter and Thread in the |NCS|, read the documentation in the :ref:`ug_matter` and :ref:`ug_thread` protocol sections. - -Platform designs for the nRF54H20 SoC -************************************* - -Matter in the |NCS| supports the *System-on-Chip, multiprotocol* platform design for the nRF54H20 SoC using Matter over Thread. -You can read more about other available platform designs for Matter on the :ref:`Matter platform design page`. - -Thread in the |NCS| supports the *System-on-Chip, single protocol* and *System-on-Chip, multiprotocol* platform designs for the nRF54H20 SoC. -You can read more about other available platform designs for Thread on the :ref:`OpenThread architectures page`. - -For more information about the multiprotocol feature, see :ref:`ug_multiprotocol_support`. - -System-on-Chip, single protocol -=============================== - -In this design, the OpenThread stack runs on several cores and domains of a single nRF54H20 SoC. - -This platform designs is suitable for the following development kit: - -##TODO add to /includes/sample_board_rows.txt - -In this design: - -* The Application Core runs the OpenThread stack. -* The Radio Core runs the component of the OpenThread stack that is related to the 802.15.4 IEEE Radio Driver. -* The Secure Domain stores all the secure components, including keys and certificates. - It also manages the access to peripherals, memory, and other components. - - .. note:: - The PSA crypto API level 3 for storing security components is not yet implemented on the Secure Domain. - -* The Global Domain manages clocks, power, global RAM, and global NVM. - -For more information, see :ref:`ug_nrf54h20_architecture_cpu`. - -The following figure demonstrates the architecture. -The Global Domain is not included. - -.. figure:: images/thread_platform_design_nRF54h20.svg - :alt: Multiprotocol Thread and Bluetooth LE architecture (nRF54H20) - - Single protocol Thread architecture on the nRF54H20 SoC - -System-on-Chip, multiprotocol -============================= - -In this design, the OpenThread stack and the Bluetooth® Low Energy (LE) stack run on several cores and domains of a single nRF54H20 SoC. - -This platform design is suitable for the following development kit: - -##TODO add to /includes/sample_board_rows.txt - -In this design: - -* The Application Core runs the OpenThread stack, and a part of the Bluetooth LE Controller. -* The Radio Core runs both the Bluetooth LE Controller and the component of the OpenThread stack that is related to the 802.15.4 IEEE Radio Driver. -* The Secure Domain stores all the secure components, including keys and certificates. - It also manages the access to peripherals, memory, and other components. - - .. note:: - The PSA crypto API level 3 for storing security components is not yet implemented on the Secure Domain. - -* The Global Domain manages clocks, power, global RAM, and global NVM. - -For more information, see :ref:`ug_nrf54h20_architecture_cpu`. - -The following figure demonstrates the architecture. -The Global Domain is not included. - -.. _nrf54h20_platform_multi_figure: - -.. figure:: images/thread_platform_design_nRF54h20_multi.svg - :alt: Multiprotocol Thread and Bluetooth LE architecture (nRF54H20) - - Multiprotocol Thread and Bluetooth LE architecture on the nRF54H20 SoC - -Matter over Thread -================== - -In this design, the Matter stack, the OpenThread stack, and the Bluetooth® Low Energy (LE) stack run on several cores and domains of a single nRF54H20 SoC. - -This platform design is suitable for the following development kit: - -##TODO add to /includes/sample_board_rows.txt - -In this design: - -* The Application Core runs the Matter stack, the OpenThread stack, and a part of the Bluetooth LE Controller. -* The Radio Core runs both the Bluetooth LE Controller and the component of the OpenThread stack that is related to the 802.15.4 IEEE Radio Driver. -* The Secure Domain stores all the secure components, including keys and certificates. - It also manages the access to peripherals, memory, and other components. - - .. note:: - The PSA crypto API level 3 for storing security components is not yet implemented on the Secure Domain. - -* The Global Domain manages clocks, power, global RAM, and global NVM. - -For more information, see :ref:`ug_nrf54h20_architecture_cpu`. - -Refer to the :ref:`nrf54h20_platform_multi_figure` figure to see the architecture of the SoC. -The Global Domain is not included. - -Additional requirements on the nRF54H20 DK -****************************************** - -In addition to the standard requirements for the |NCS|, such as the :ref:`ug_matter_gs_tools_gn` for Matter, you need the following to run Matter-enabled or Thread-enabled applications on the nRF54H20 DK: - -* For DFU - J-Link and a USB cable. -* nrfjprog from the `nRF Command Line Tools`_. - -Configuring Matter and Thread on the nRF54H20 DK -************************************************ - -Currently, only the configuration for Matter over Thread is supported for Matter. -Follow the configuration steps on the :ref:`ug_matter_gs_testing` page to configure the Matter environment for the supported Matter samples. - -Currently, only the :ref:`ot_cli_sample` sample is supported for Thread. -See the sample documentation for how to configure it. - -The Matter and Thread samples can work on the corresponding networks with standard devices of the same protocol. - -Programming Matter and Thread samples on the nRF54H20 DK -======================================================== - -To program the compatible Matter or Thread samples on the nRF54H20 DK, follow the :ref:`ug_nrf54h20_gs_sample` steps. -Read also programming guides prepared for specific Matter samples: :ref:`Matter door lock sample `, and :ref:`Matter template sample `. - -.. note:: - :ref:`Testing using Bluetooth LE with Nordic UART Service ` on the :ref:`Matter door lock sample ` is disabled by default. - -Logging for Matter and Thread samples on the nRF54H20 DK -======================================================== - -To read logs for Matter samples on the nRF54H20 DK, complete the following steps: - -1. Connect to the nRF54H20 DK using a USB cable. -#. Select the first available port to read the logs from. - -For more information, see :ref:`ug_nrf54h20_logging`. - -.. _ug_nrf54h20_matter_thread_matter_wifi: - -Matter over Wi-Fi -================= - -Matter over Wi-Fi is currently supported on the :ref:`Matter door lock sample ` and :ref:`Matter template sample `. - -In this design, the Matter stack, the Wi-Fi stack, and the Bluetooth® Low Energy (LE) stack run on several cores and domains of a single nRF54H20 SoC. - -To run Matter over Wi-Fi on the nRF54H20 DK you need the additional ``nrf7002_ek`` shield attached through the nRF54H20 DK to the nRF7002 EK interposer board. - -In this design: - -* The Application Core runs the Matter stack, the Wi-Fi stack, and a part of the Bluetooth LE Controller. -* The Radio Core runs both the Bluetooth LE Controller and the component of the OpenThread stack that is related to the 802.15.4 IEEE Radio Driver. -* The Secure Domain stores all the secure components, including keys and certificates. - It also manages the access to peripherals, memory, and other components. - - .. note:: - The PSA crypto API level 3 for storing security components is not yet implemented on the Secure Domain. - -* The Global Domain manages clocks, power, global RAM, and global NVM. - -To build the sample with Matter over Wi-Fi support run the following command: - -.. code-block:: console - - west build -b nrf54h20dk/nrf54h20/cpuapp -- -DSHIELD=nrf700x_nrf54h20dk -DCONFIG_CHIP_WIFI=y - - -.. _ug_nrf54h20_matter_thread_suit_dfu: - -SUIT Device Firmware Upgrade support on the nRF54H20 DK -======================================================= - -The :ref:`SUIT Device Firmware Upgrade ` feature has been implemented on the nRF54H20 DK and you can use it in the :ref:`Matter door lock sample `. -In this solution, both Application and Radio Cores can be upgraded sequentially to the newest version using :ref:`SUIT hierarchical manifests `. -The SUIT DFU feature uses :ref:`SUIT manifests ` that contain components and images of the firmware and are used by the Secure Domain to replace, verify and run the firmware. -In the Matter Lock sample, we use the Simple Management Protocol (SMP) over Bluetooth LE transport to deliver the new firmware to the device's DFU partition and then the SUIT processor installs the image according to the instructions that are described in the manifest. -By default, the root manifest contains both Application and Radio Core images, but for the Matter sample the images need to be split to the separate cores and perform upgrades sequentially. -Currently, there is no protection against incompatibility between the new Radio Core and old Application Core images, so you need to ensure that compatibility. -We have prepared manifest templates in the ``configurations/nrf54h20dk_nrf54h20_cpuapp`` directory in the Matter lock sample which are prepared to generate two separate SUIT envelopes - one for the Application Core and another for the Radio Core. They are as follows: - - * :file:`app_envelope.yaml.jinja2` - Contains the procedures for SUIT directives that allow for the Application Core image to be updated. - * :file:`app_envelope.yaml.jinja2.digest` - Contains the digital signature of the SUIT manifest prepared for the Application Core image. - * :file:`multiprotocol_rad_envelope.yaml.jinja2` - Contains the procedures for SUIT directives that allow for the Radio Core image to be updated. - * :file:`multiprotocol_rad_envelope.yaml.jinja2.digest` - Contains the digital signature of the SUIT manifest prepared for the Radio Core image. - * :file:`root_hierarchical_envelope.yaml.jinja2` - Contains the procedures for SUIT directives to run the current firmware. - * :file:`root_hierarchical_envelope.yaml.jinja2.digest` - Contains the digital signature of the SUIT manifest prepared for running the current firmware. - -You can edit the templates for other purposes. -To learn how to do edit the manifest templates, see the :ref:`ug_nrf54h20_suit_customize_dfu` guide. - -To build the firmware with the SUIT DFU support, run the following command with the *number* replaced with the new image number, that should be higher than the previous one: - -.. parsed-literal:: - :class: highlight - - west build -b nrf54h20dk/nrf54h20/cpuapp -- -DSB_CONFIG_SUIT_ENVELOPE_SEQUENCE_NUM=*number* - -You can perform a DFU using the nRF Connect Device Manager mobile application or the :ref:`Mcumgr command-line tool `. -After building the sample you can find two SUIT envelopes created in the build directory and depending on the core type you can search for: - - * the :file:`build/zephyr/app.suit` file to get the SUIT envelope for the Application Core. - * the :file:`build/multiprotocol_rpmsg/zephyr/multiprotocol_rpmsg_subimage.suit` file to get the SUIT envelope for the Radio Core. - -To learn how to perform a DFU using the nRFConnect Device Manager mobile application read instructions in the ``suit smp transfer `` guide. - -Performing DFU on nRF54H20 DK using Mcumgr command-line tool ------------------------------------------------------------- - - 1. Follow the instructions in the :ref:`Mcumgr command-line tool ` guide to install Mcumgr. - #. Press **Button 1** to enable Bluetooth LE SMP advertising on the nRF54H20 DK. - #. Run the following command to upgrade the Radio Core: - - .. parsed-literal:: - :class: highlight - - mcumgr --conntype ble --hci *hci number* --connstring peer_name=*peer name* image upload *path to multiprotocol_rpmsg_subimage.suit* -n 0 -w 1 - - Where: - - * *hci number* is the Bluetooth LE device ID on your host device (by default it is ``0``). - * *peer name* is the Bluetooth LE name which is advertised by the nRF54H20 DK (by default ``"Matter Lock"``). - * *path to multiprotocol_rpmsg_subimage.suit* is a path to the SUIT envelope that contains Radio Core image. - - For example: - - .. parsed-literal:: - :class: highlight - - mcumgr --conntype ble --hci 0 --connstring peer_name="MatterLock" image upload build/multiprotocol_rpmsg/zephyr/multiprotocol_rpmsg_subimage.suit -n 0 -w 1 - - #. Press **Button 1** to enable Bluetooth LE SMP advertising on the nRF54H20 DK again, because the previous operation disabled it after applying the image. - #. Run the same command as in Step 3 to upgrade the Application Core image, but this time provide a path to the ``app.suit`` file. - - For example: - - .. parsed-literal:: - :class: highlight - - mcumgr --conntype ble --hci 0 --connstring peer_name="MatterLock" image upload build/zephyr/app.suit -n 0 -w 1 - - -Implementing support for the nRF54H20 DK -======================================== - -If you want to implement support for the nRF54H20 DK in your Matter-enabled or Thread-enabled application, read the :ref:`ug_nrf54h20_configuration` guide. - -.. _ug_nrf54h20_matter_thread_limitations: - -Limitations for Matter and Thread on the nRF54H20 DK -**************************************************** - -Matter and Thread support has the following limitations on the nRF54H20 DK: - -* DFU over Matter or Serial Link is not yet implemented. -* The current implementation is not power-optimized. -* The cryptographic operations related to Matter and Thread are performed on the Application Core, rather than on the Secure Domain. -* The ``west flash --erase`` command is blocked. - See :ref:`ug_nrf54h20_gs_sample` for more information. -* The factory reset functionality does not work properly. - After clearing all NVM storage, the device cannot reboot automatically and falls into a hard fault. - - As a workaround, press the reset button on the nRF54H20 DK board after performing a factory reset. -* Matter over Thread commissioning might be unstable due to the lack of true random generator support on nRF54H20. - - After each reboot or factory reset, the device will always have the same Bluetooth LE and IEEE 80215.4 addresses. - This might impact working within the Thread network because after the second and following connections, Thread Border Router will reject these connections until deleted from the database and commissioning to Matter will take more and more time. - - As a workaround, after each factory reset and before performing the next commissioning to Matter, connect to the device's serial port and run the following command: - - .. parsed-literal:: - :class: highlight - - ot extaddr *address* - - Replace the *address* argument with an 8-byte randomly generated MAC address, for example ``87fb47d5730ac0a0``. diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_customize_dfu.rst b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_customize_dfu.rst index 1b6e4c4145e0..aa8852459896 100644 --- a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_customize_dfu.rst +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_customize_dfu.rst @@ -95,7 +95,7 @@ Changing the source of manifest templates allows you to create manifest files on The source of the manifest templates can be configured by setting the following Kconfig options: -* :kconfig:option:`SB_CONFIG_SUIT_ENVELOPE_ROOT_TEMPLATE` +* ``SB_CONFIG_SUIT_ENVELOPE_ROOT_TEMPLATE`` * :kconfig:option:`CONFIG_SUIT_ENVELOPE_TEMPLATE` - For each of the images (application and radio core images) diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_external_memory.rst b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_external_memory.rst index b41157a68e1e..f8b18afce0f7 100644 --- a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_external_memory.rst +++ b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_external_memory.rst @@ -56,7 +56,7 @@ To enable the external memory, you must add the ``-DFILE_SUFFIX="extflash"`` arg .. note:: This step is needed only on nRF54H20 DK. Skip this step if you are using different hardware. -#. Enable the :kconfig:option:`SB_CONFIG_SUIT_BUILD_FLASH_COMPANION` sysbuild Kconfig option, which enables the build of the reference companion image. +#. Enable the ``SB_CONFIG_SUIT_BUILD_FLASH_COMPANION`` sysbuild Kconfig option, which enables the build of the reference companion image. See the :ref:`suit_flash_companion` user guide for instructions on how to configure the companion image using sysbuild. #. Enable the :kconfig:option:`CONFIG_SUIT_STREAM_SOURCE_FLASH` Kconfig option, which enables SUIT processor on the application core to read and parse DFU cache partitions. @@ -131,7 +131,7 @@ To enable the external memory, you must add the ``-DFILE_SUFFIX="extflash"`` arg The build system will automatically use :ref:`configuration_system_overview_sysbuild` and generate a :file:`build/dfu_suit.zip` archive, which contains the SUIT envelope and candidate images. -#. Build a new version of the application with the incremented :kconfig:option:`SB_CONFIG_SUIT_ENVELOPE_SEQUENCE_NUM` value. +#. Build a new version of the application with the incremented ``SB_CONFIG_SUIT_ENVELOPE_SEQUENCE_NUM`` value. #. Download the new :file:`dfu_suit.zip` archive to your mobile device. diff --git a/doc/nrf/gsg_guides.rst b/doc/nrf/gsg_guides.rst index ea4b762d2ecd..efcc04a42c37 100644 --- a/doc/nrf/gsg_guides.rst +++ b/doc/nrf/gsg_guides.rst @@ -17,6 +17,8 @@ This is not a comprehensive section that includes all of the available getting s * To get started with the nRF91x1 DKs, complete the steps in the `Quick Start`_ app, available from `nRF Connect for Desktop`_. * To get started with the nRF54L15 PDK, the installation of the |NCS| is required. See :ref:`ug_nrf54l15_gs`. + * To get started with the nRF54H20 DK, the installation of the |NCS| is required. + See :ref:`ug_nrf54h20_gs`. * To get started with the nPM1300 EK, see the `Get started `_ section of the nPM1300 EK product page. * To get started with the nRF7002 EB, see the `Get started `_ section of the nRF7002 EB product page. @@ -30,3 +32,4 @@ This is not a comprehensive section that includes all of the available getting s gsg_guides/nrf5340_gs gsg_guides/thingy53_gs gsg_guides/nrf52_gs + gsg_guides/gsg_other diff --git a/doc/nrf/gsg_guides/gsg_other.rst b/doc/nrf/gsg_guides/gsg_other.rst new file mode 100644 index 000000000000..34041cb5edc2 --- /dev/null +++ b/doc/nrf/gsg_guides/gsg_other.rst @@ -0,0 +1,12 @@ +.. _gsg_other: + +Getting started with other DKs +############################## + +Use the following guides to familiarize yourself with the |NCS| tools and components for the following devices supported by the SDK: + + * To get started with the nRF91x1 DKs, complete the steps in the `Quick Start`_ app, available from `nRF Connect for Desktop`_. + * To get started with the nRF54L15 PDK, see :ref:`ug_nrf54l15_gs`. + * To get started with the nRF54H20 DK, see :ref:`ug_nrf54h20_gs`. + * To get started with the nPM1300 EK, see the `Get started `_ section of the nPM1300 EK product page. + * To get started with the nRF7002 EB, see the `Get started `_ section of the nRF7002 EB product page. diff --git a/doc/nrf/includes/nRF54H20_erase_UICR.txt b/doc/nrf/includes/nRF54H20_erase_UICR.txt index 982623cee783..49e63588e2ba 100644 --- a/doc/nrf/includes/nRF54H20_erase_UICR.txt +++ b/doc/nrf/includes/nRF54H20_erase_UICR.txt @@ -2,11 +2,16 @@ Programming the nRF54H20 SoC can sometimes fail due to conflicts in the resource configuration. This can happen if, for example, an application programmed to the nRF54H20 SoC configured the UICRs for one or more cores in a way that is incompatible with the configuration required by the application you are trying to program on the SoC. - To fix this error and erase the UICRs, run the following commands:: + To fix this error and erase the UICR for the application core, run the following command:: - nrfutil device x-boot-mode-set --boot-mode safe --serial-number - nrfutil device erase --all --serial-number --core Application - nrfutil device erase --all --serial-number --core Network - nrfutil device x-boot-mode-set --boot-mode normal --serial-number + nrfutil device recover --core Application You can then run ``west flash`` to program your application. + For more information on the command, run:: + + nrfutil device recover --help + +If your sample also uses the radio core, you must also erase the UICRs for the radio core. +To erase the UICR for the radio core, run the following command:: + + nrfutil device recover --core Network diff --git a/doc/nrf/installation/install_ncs.rst b/doc/nrf/installation/install_ncs.rst index 2e1992c2e5b2..5b2401a65d7a 100644 --- a/doc/nrf/installation/install_ncs.rst +++ b/doc/nrf/installation/install_ncs.rst @@ -293,20 +293,20 @@ For more information about the repository and development model, see the :ref:`d .. -If you used the default locations, your directory structure now looks similar to this: +If you used the default locations (:file:`C:\ncs` on Windows, :file:`/ncs` on Linux and MacOS), your directory structure now looks similar to this: .. code-block:: none - / - ├─── toolchains/ + ncs + ├─── toolchains │ └─── - └─── / - ├─── .west/ - ├─── bootloader/ - ├─── modules/ - ├─── nrf/ - ├─── nrfxlib/ - ├─── zephyr/ + └─── + ├─── .west + ├─── bootloader + ├─── modules + ├─── nrf + ├─── nrfxlib + ├─── zephyr └─── ... In this simplified structure preview, ** corresponds to :file:`ncs/` and ** and ** correspond to the version names you installed. @@ -601,11 +601,13 @@ To install the |NCS| system-wide, complete the following steps: .. _gs_assistant: .. _auto_installation_tcm_setup: -Legacy installation with Toolchain Manager -****************************************** +Installation with Toolchain Manager +*********************************** -.. important:: - Toolchain Manager installation is recommended for the |NCS| v1.9.x and earlier. +.. note:: + + The Toolchain Manager installation is recommended only when using the nRF54H20 DK with the |NCS| v2.7.0. + When using any other DK, the Toolchain Manager installation is recommended for the |NCS| v1.9.x and earlier versions. .. toggle:: diff --git a/doc/nrf/libraries/bluetooth_services/services/fast_pair.rst b/doc/nrf/libraries/bluetooth_services/services/fast_pair.rst index 0b2d99392062..1483611207a3 100644 --- a/doc/nrf/libraries/bluetooth_services/services/fast_pair.rst +++ b/doc/nrf/libraries/bluetooth_services/services/fast_pair.rst @@ -135,7 +135,9 @@ Firmware Revision characteristic The Fast Pair specification requires enabling GATT Device Information Service and the Firmware Revision characteristic. For this reason, the default values of the Kconfig options :kconfig:option:`CONFIG_BT_DIS` and :kconfig:option:`CONFIG_BT_DIS_FW_REV`, respectively, are set to enabled. -The default value of :kconfig:option:`CONFIG_BT_DIS_FW_REV_STR` is set to :kconfig:option:`CONFIG_MCUBOOT_IMGTOOL_SIGN_VERSION` if :kconfig:option:`SB_CONFIG_BOOTLOADER_MCUBOOT` is enabled. +The default value of :kconfig:option:`CONFIG_BT_DIS_FW_REV_STR` is set to :kconfig:option:`CONFIG_MCUBOOT_IMGTOOL_SIGN_VERSION` if :kconfig:option:`CONFIG_BOOTLOADER_MCUBOOT` is enabled. +The option is enforced by sysbuild when ``SB_CONFIG_BOOTLOADER_MCUBOOT`` is enabled. + Otherwise, it is set to ``0.0.0+0``. This requirement does not apply for the locator tag use case as specified in the `Fast Pair Device Feature Requirements for Locator Tags`_ documentation. diff --git a/doc/nrf/libraries/dfu/dfu_multi_image.rst b/doc/nrf/libraries/dfu/dfu_multi_image.rst index 1992bc70bb73..c663d10cd595 100644 --- a/doc/nrf/libraries/dfu/dfu_multi_image.rst +++ b/doc/nrf/libraries/dfu/dfu_multi_image.rst @@ -23,18 +23,19 @@ To enable the DFU multi-image library, set the :kconfig:option:`CONFIG_DFU_MULTI To configure the maximum number of images that the DFU multi-image library is able to process, use the :kconfig:option:`CONFIG_DFU_MULTI_IMAGE_MAX_IMAGE_COUNT` Kconfig option. -To enable building the DFU multi-image package that contains commonly used update images, such as the application core firmware, the network core firmware, or MCUboot images, set the :kconfig:option:`SB_CONFIG_DFU_MULTI_IMAGE_PACKAGE_BUILD` Kconfig option. The following options control what images are included: +To enable building the DFU multi-image package that contains commonly used update images, such as the application core firmware, the network core firmware, or MCUboot images, set the ``SB_CONFIG_DFU_MULTI_IMAGE_PACKAGE_BUILD`` Kconfig option. +The following options control which images are included: +-------------------------------------------------------------------+---------------------------------------+ | Kconfig | Description | +===================================================================+=======================================+ -| :kconfig:option:`SB_CONFIG_DFU_MULTI_IMAGE_PACKAGE_APP` | Include application update | +| ``SB_CONFIG_DFU_MULTI_IMAGE_PACKAGE_APP`` | Include application update. | +-------------------------------------------------------------------+---------------------------------------+ -| :kconfig:option:`SB_CONFIG_DFU_MULTI_IMAGE_PACKAGE_NET` | Include network core image update | +| ``SB_CONFIG_DFU_MULTI_IMAGE_PACKAGE_NET`` | Include network core image update. | +-------------------------------------------------------------------+---------------------------------------+ -| :kconfig:option:`SB_CONFIG_DFU_MULTI_IMAGE_PACKAGE_MCUBOOT` | Include MCUboot update | +| ``SB_CONFIG_DFU_MULTI_IMAGE_PACKAGE_MCUBOOT`` | Include MCUboot update. | +-------------------------------------------------------------------+---------------------------------------+ -| :kconfig:option:`SB_CONFIG_DFU_MULTI_IMAGE_PACKAGE_WIFI_FW_PATCH` | Include nRF700x WiFi firmware patches | +| ``SB_CONFIG_DFU_MULTI_IMAGE_PACKAGE_WIFI_FW_PATCH`` | Include nRF700x WiFi firmware patches.| +-------------------------------------------------------------------+---------------------------------------+ Dependencies diff --git a/doc/nrf/libraries/zigbee/zigbee_fota.rst b/doc/nrf/libraries/zigbee/zigbee_fota.rst index 17f5dbc469e4..0d77c3aca229 100644 --- a/doc/nrf/libraries/zigbee/zigbee_fota.rst +++ b/doc/nrf/libraries/zigbee/zigbee_fota.rst @@ -100,7 +100,7 @@ Additionally, the following limitations apply on the nRF5340 SoCs: * It is required to use external flash to enable the Zigbee FOTA library. * By default, only the full upgrades (to both application and network core) are allowed. Disable the :kconfig:option:`CONFIG_NRF53_ENFORCE_IMAGE_VERSION_EQUALITY` Kconfig option to build update images without inter-dependencies so that they can be applied independently. -* It is impossible to enable :kconfig:option:`SB_CONFIG_MCUBOOT_MODE_SWAP_WITHOUT_SCRATCH` Kconfig option. +* It is impossible to enable ``SB_CONFIG_MCUBOOT_MODE_SWAP_WITHOUT_SCRATCH`` Kconfig option. As a result, the fallback recovery is not available and any valid upgrade will overwrite the previous image. The call to the :c:func:`boot_write_img_confirmed()` will have no effect. * The current DFU limitations and dependencies are enforced by the :kconfig:option:`CONFIG_NRF53_MULTI_IMAGE_UPDATE` Kconfig option. diff --git a/doc/nrf/links.txt b/doc/nrf/links.txt index e67727c6c7ca..00bd498229a4 100644 --- a/doc/nrf/links.txt +++ b/doc/nrf/links.txt @@ -1598,7 +1598,9 @@ .. _`curl`: https://curl.se/ -.. _`nRF54H20 firmware bundle`: https://files.nordicsemi.com/artifactory/SDSC/external/nrf54h20_soc_binaries_v0.3.3.zip +.. _`nRF54H20 firmware bundle`: https://files.nordicsemi.com/artifactory/SDSC/external/nrf54h20_soc_binaries_v0.5.0.zip +.. _`nRF54H20 firmware bundle v0.3.3`: https://files.nordicsemi.com/artifactory/SDSC/external/nrf54h20_soc_binaries_v0.3.3.zip +.. _`nRF54H20 firmware bundle v0.5.0`: https://files.nordicsemi.com/artifactory/SDSC/external/nrf54h20_soc_binaries_v0.5.0.zip .. _`BICR binary file`: https://files.nordicsemi.com/artifactory/SDSC/external/bicr_ext_loadcap.hex diff --git a/doc/nrf/protocols/bt/bt_mesh/dfu_over_bt_mesh.rst b/doc/nrf/protocols/bt/bt_mesh/dfu_over_bt_mesh.rst index d80050e39e43..3a86939030b2 100644 --- a/doc/nrf/protocols/bt/bt_mesh/dfu_over_bt_mesh.rst +++ b/doc/nrf/protocols/bt/bt_mesh/dfu_over_bt_mesh.rst @@ -198,7 +198,7 @@ Using the DFU metadata extraction script is the most efficient way of generating Automated metadata generation ============================= -By enabling the :kconfig:option:`SB_CONFIG_DFU_ZIP_BLUETOOTH_MESH_METADATA` option in sysbuild, the metadata will be automatically parsed from the ``.elf`` and ``.config`` files. +By enabling the ``SB_CONFIG_DFU_ZIP_BLUETOOTH_MESH_METADATA`` option in sysbuild, the metadata will be automatically parsed from the ``.elf`` and ``.config`` files. The parsed data is stored in the :file:`ble_mesh_metadata.json` file. The file is placed in the :file:`dfu_application.zip` archive in the build folder of the application. Additionally, the metadata string required by the ``mesh models dfu slot add`` command will be printed in the command line window when the application is built:: diff --git a/doc/nrf/protocols/matter/end_product/bootloader.rst b/doc/nrf/protocols/matter/end_product/bootloader.rst index 7fd76139675a..870e18a60788 100644 --- a/doc/nrf/protocols/matter/end_product/bootloader.rst +++ b/doc/nrf/protocols/matter/end_product/bootloader.rst @@ -98,7 +98,7 @@ MCUboot uses asymmetric cryptography to validate the authenticity of firmware. The public key embedded in the bootloader image is used to validate the signature of a firmware image that is about to be booted. If the signature check fails, MCUboot rejects the image and either: -* rolls back to the last valid firmware image if the fallback recovery has not been disabled using the MCUboot's :kconfig:option:`SB_CONFIG_MCUBOOT_MODE_OVERWRITE_ONLY` Kconfig option. +* rolls back to the last valid firmware image if the fallback recovery has not been disabled using the MCUboot's ``SB_CONFIG_MCUBOOT_MODE_OVERWRITE_ONLY`` Kconfig option. * fails to boot. .. note:: @@ -113,4 +113,4 @@ Downgrade protection The :ref:`downgrade protection ` mechanism makes it impossible for an attacker to trick a user to install a firmware image older than the currently installed one. The attacker might want to do this to reintroduce old security vulnerabilities that have already been fixed in newer firmware revisions. -You should enable the downgrade protection mechanism if you choose to enable MCUboot's :kconfig:option:`SB_CONFIG_MCUBOOT_MODE_OVERWRITE_ONLY` Kconfig option, which disables the fallback recovery in case of a faulty upgrade. +You should enable the downgrade protection mechanism if you choose to enable MCUboot's ``SB_CONFIG_MCUBOOT_MODE_OVERWRITE_ONLY`` Kconfig option, which disables the fallback recovery in case of a faulty upgrade. diff --git a/doc/nrf/protocols/matter/end_product/test_event_triggers.rst b/doc/nrf/protocols/matter/end_product/test_event_triggers.rst index d0f4fed871d0..f53d7d2838e2 100644 --- a/doc/nrf/protocols/matter/end_product/test_event_triggers.rst +++ b/doc/nrf/protocols/matter/end_product/test_event_triggers.rst @@ -100,7 +100,7 @@ The following table lists the available triggers and their activation codes: - ``0xFFFFFFFF60000000`` - No additional value supported. * - OTA query - - :kconfig:option:`CONFIG_CHIP_OTA_REQUESTOR` = ``y``, and :kconfig:option:`SB_CONFIG_MATTER_OTA` = ``y``. + - :kconfig:option:`CONFIG_CHIP_OTA_REQUESTOR` = ``y``, and ``SB_CONFIG_MATTER_OTA`` = ``y``. - Trigger an OTA firmware update. - ``0x002a000000000100`` - ``0x01000000000001FF`` - The range of ``0x00`` - ``0xFF`` is the fabric index value. @@ -125,10 +125,10 @@ You cannot set the enable key to a specific value using factory data unless the If it is not set, the default value ``00112233445566778899AABBCCDDEEFF`` will be used. For secure operation, you need to ensure that the enable key is unique for all of your devices. -To specify the enable key through the build system, enable the :kconfig:option:`SB_CONFIG_MATTER_FACTORY_DATA_GENERATE` Kconfig option by setting it to ``y``. +To specify the enable key through the build system, enable the ``SB_CONFIG_MATTER_FACTORY_DATA_GENERATE`` Kconfig option by setting it to ``y``. Then, set the :kconfig:option:`CONFIG_CHIP_DEVICE_ENABLE_KEY` Kconfig option to a 32-byte hexadecimal string value. -If :kconfig:option:`SB_CONFIG_MATTER_FACTORY_DATA_GENERATE` is set to ``n``, you can follow the :doc:`matter:nrfconnect_factory_data_configuration` guide in the Matter documentation to generate the factory data set with the specific enable key value. +If ``SB_CONFIG_MATTER_FACTORY_DATA_GENERATE`` is set to ``n``, you can follow the :doc:`matter:nrfconnect_factory_data_configuration` guide in the Matter documentation to generate the factory data set with the specific enable key value. If you do not use the |NCS| Matter common module, you need to read the enable key value manually from the factory data set and provide it to the ``TestEventTrigger`` class. diff --git a/doc/nrf/releases_and_maturity/migration/migration_guide_2.7.rst b/doc/nrf/releases_and_maturity/migration/migration_guide_2.7.rst index 14320d36ce63..ff952d727113 100644 --- a/doc/nrf/releases_and_maturity/migration/migration_guide_2.7.rst +++ b/doc/nrf/releases_and_maturity/migration/migration_guide_2.7.rst @@ -67,12 +67,12 @@ Matter * With the inheritance of Zephyr's :ref:`zephyr:sysbuild` in the |NCS|, 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 :kconfig:option:`SB_CONFIG_MATTER_FACTORY_DATA_GENERATE` Kconfig option instead to enable or disable creating the factory data set during building a Matter sample. + * :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 ``/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 :kconfig:option:`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. - * :kconfig:option:`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 :kconfig:option:`SB_CONFIG_MATTER_OTA_IMAGE_FILE_NAME` Kconfig option instead to define Matter OTA output filename. + * :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:: diff --git a/doc/nrf/releases_and_maturity/migration/migration_guide_nRF54H20_cs_to_2_7.rst b/doc/nrf/releases_and_maturity/migration/migration_guide_nRF54H20_cs_to_2_7.rst new file mode 100644 index 000000000000..809abef89fe6 --- /dev/null +++ b/doc/nrf/releases_and_maturity/migration/migration_guide_nRF54H20_cs_to_2_7.rst @@ -0,0 +1,21 @@ +.. _migration_nrf4h20_to_2.7: + +Migration notes for |NCS| v2.7.0 for nRF54H20 DK users +###################################################### + +This document describes the new features and changes implemented in |NCS| to take into consideration when migrating your application for the nRF54H20 DK to |NCS| v2.7.0. + +To ensure the nRF54H20 DK runs its components correctly, verify its compatibility with the |NCS| v2.7.0 release by checking the version number on your DK's sticker. +The only versions of the nRF54H20 DK compatible with the |NCS| v2.7.0 are the following: + +* Version PCA10175 v0.7.x (ES3) +* Version PCA10175 v0.8.0 (ES3.x) +* Version ES4 + +.. toctree:: + :maxdepth: 1 + :glob: + :reversed: + :caption: Subpages: + + nRF54H20_migration_2.7/* diff --git a/doc/nrf/releases_and_maturity/migration/migration_sysbuild.rst b/doc/nrf/releases_and_maturity/migration/migration_sysbuild.rst index 4cd7a6ce8037..e7d13ae34f98 100644 --- a/doc/nrf/releases_and_maturity/migration/migration_sysbuild.rst +++ b/doc/nrf/releases_and_maturity/migration/migration_sysbuild.rst @@ -10,7 +10,7 @@ As the previous system has been deprecated, you must update your existing multi- The following are the differences in how project configuration is performed in sysbuild compared to child/parent image configuration: * Sysbuild controls which images are added to a build, instead of the main application. -* Sysbuild specifies the project configuration for all images, which was previously done in the main application or child applications. +* Sysbuild specifies the project configuration files for all images, which was previously done in the main application or child applications. * Sysbuild controls the packaging of firmware components, instead of the main application. * Sysbuild manages some software functionality of image builds, such as the configuration mode of an nRF70-series radio. * Sysbuild runs partition manager code (if enabled) and distributes the output information to images. @@ -21,7 +21,7 @@ This results in the CMake configuration step running more than once, as this inf * Sysbuild introduces support for file suffixes, replacing the deprecated build type used by child/parent images. The changes needed to convert a child/parent image project to a Sysbuild project depend on the features used. -Review how :ref:`sysbuild` works to understand the basic usage and configuration methods, and how these differ from a single image build, before proceeding with project migration according to the guidelines listed in the following sections. +Review how :ref:`sysbuild` works to understand the basic usage and configuration methods, and how these differ from a child image build, before proceeding with project migration according to the guidelines listed in the following sections. .. _child_parent_to_sysbuild_migration_sysbuild_configuration_file: @@ -88,21 +88,21 @@ The following Kconfig options are available to include the desired image in the +---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ | Kconfig option | Description | +=========================================================+===========================================================================================================+ -| :kconfig:option:`SB_CONFIG_NETCORE_EMPTY` | Empty network core image :zephyr_file:`samples/nrf5340/empty_net_core` | +| ``SB_CONFIG_NETCORE_EMPTY`` | Empty network core image: :ref:`nrf5340_empty_net_core` | +---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_NETCORE_HCI_IPC` | Zephyr hci_ipc Bluetooth image :zephyr_file:`samples/bluetooth/hci_ipc` | +| ``SB_CONFIG_NETCORE_HCI_IPC`` | Zephyr hci_ipc Bluetooth image: :ref:`zephyr:bluetooth-hci-ipc-sample` | +---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_NETCORE_RPC_HOST` | |NCS| rpc_host Bluetooth image :zephyr_file:`samples/bluetooth/rpc_host` | +| ``SB_CONFIG_NETCORE_RPC_HOST`` | |NCS| rpc_host Bluetooth image: :ref:`ble_rpc_host` | +---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_NETCORE_802154_RPMSG` | Zephyr 802.15.4 image :zephyr_file:`samples/boards/nrf/ieee802154/802154_rpmsg` | +| ``SB_CONFIG_NETCORE_802154_RPMSG`` | Zephyr 802.15.4 image: :ref:`zephyr:nrf-ieee802154-rpmsg-sample` | +---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_NETCORE_MULTIPROTOCOL_RPMSG` | |NCS| multiprotocol_rpmsg Bluetooth and 802.15.4 image :zephyr_file:`samples/nrf5340/multiprotocol_rpmsg` | +| ``SB_CONFIG_NETCORE_MULTIPROTOCOL_RPMSG`` | |NCS| multiprotocol_rpmsg Bluetooth and 802.15.4 image: :ref:`multiprotocol-rpmsg-sample` | +---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_NETCORE_IPC_RADIO` | |NCS| ipc_radio image :zephyr_file:`applications/ipc_radio` | +| ``SB_CONFIG_NETCORE_IPC_RADIO`` | |NCS| ipc_radio image: :ref:`ipc_radio` | +---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_NETCORE_NONE` | No network core image | +| ``SB_CONFIG_NETCORE_NONE`` | No network core image | +---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_NETCORE_APP_UPDATE` | Will enable network core image update support in MCUboot (PCD) | +| ``SB_CONFIG_NETCORE_APP_UPDATE`` | Will enable network core image update support in MCUboot (PCD) | +---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ If a project uses network-core functionality (for example, Bluetooth) in the main application but does not enable a network-core image in sysbuild, then no network-core image will be built, resulting in a non-working application. @@ -119,47 +119,47 @@ The following Kconfig options are available: +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ | Kconfig option | Description | +===========================================================================+==========================================================================================================================+ -| :kconfig:option:`SB_CONFIG_BOOTLOADER_MCUBOOT` | Build MCUboot image | +| ``SB_CONFIG_BOOTLOADER_MCUBOOT`` | Build MCUboot image | +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_BOOT_SIGNATURE_TYPE_NONE` | Set MCUboot signature type to none (SHA256 hash check only) | +| ``SB_CONFIG_BOOT_SIGNATURE_TYPE_NONE`` | Set MCUboot signature type to none (SHA256 hash check only) | +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_BOOT_SIGNATURE_TYPE_RSA` | Set MCUboot signature type to RSA | +| ``SB_CONFIG_BOOT_SIGNATURE_TYPE_RSA`` | Set MCUboot signature type to RSA | +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_BOOT_SIGNATURE_TYPE_ECDSA_P256` | Set MCUboot signature type to ECDSA-P256 | +| ``SB_CONFIG_BOOT_SIGNATURE_TYPE_ECDSA_P256`` | Set MCUboot signature type to ECDSA-P256 | +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_BOOT_SIGNATURE_TYPE_ED25519` | Set MCUboot signature type to ED25519 | +| ``SB_CONFIG_BOOT_SIGNATURE_TYPE_ED25519`` | Set MCUboot signature type to ED25519 | +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_BOOT_SIGNATURE_KEY_FILE` | Absolute path to MCUboot private signing key file | +| ``SB_CONFIG_BOOT_SIGNATURE_KEY_FILE`` | Absolute path to MCUboot private signing key file | +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_BOOT_ENCRYPTION` | Enable MCUboot image encryption | +| ``SB_CONFIG_BOOT_ENCRYPTION`` | Enable MCUboot image encryption | +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_BOOT_ENCRYPTION_KEY_FILE` | Absolute path to MCUboot private encryption key file | +| ``SB_CONFIG_BOOT_ENCRYPTION_KEY_FILE`` | Absolute path to MCUboot private encryption key file | +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_MCUBOOT_MODE_SINGLE_APP` | Build MCUboot in single slot mode (application can only be updated by MCUboot's serial recovery mode) | +| ``SB_CONFIG_MCUBOOT_MODE_SINGLE_APP`` | Build MCUboot in single slot mode (application can only be updated by MCUboot's serial recovery mode) | +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_MCUBOOT_MODE_SWAP_WITHOUT_SCRATCH` | Build MCUboot and application in swap using move mode (default) | +| ``SB_CONFIG_MCUBOOT_MODE_SWAP_WITHOUT_SCRATCH`` | Build MCUboot and application in swap using move mode (default) | +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_MCUBOOT_MODE_SWAP_SCRATCH` | Build MCUboot and application in swap using scratch mode | +| ``SB_CONFIG_MCUBOOT_MODE_SWAP_SCRATCH`` | Build MCUboot and application in swap using scratch mode | +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_MCUBOOT_MODE_OVERWRITE_ONLY` | Build MCUboot and application in overwrite only mode | +| ``SB_CONFIG_MCUBOOT_MODE_OVERWRITE_ONLY`` | Build MCUboot and application in overwrite only mode | +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_MCUBOOT_MODE_DIRECT_XIP` | Build MCUboot and application in direct-XIP mode | +| ``SB_CONFIG_MCUBOOT_MODE_DIRECT_XIP`` | Build MCUboot and application in direct-XIP mode | +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_MCUBOOT_MODE_DIRECT_XIP_WITH_REVERT` | Build MCUboot and application in direct-XIP mode, with revert support | +| ``SB_CONFIG_MCUBOOT_MODE_DIRECT_XIP_WITH_REVERT`` | Build MCUboot and application in direct-XIP mode, with revert support | +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_MCUBOOT_BUILD_DIRECT_XIP_VARIANT` | Build secondary image for direct-XIP mode for the alternative execution slot | +| ``SB_CONFIG_MCUBOOT_BUILD_DIRECT_XIP_VARIANT`` | Build secondary image for direct-XIP mode for the alternative execution slot | +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_MCUBOOT_HARDWARE_DOWNGRADE_PREVENTION` | Enable hardware downgrade protection in MCUboot and application | +| ``SB_CONFIG_MCUBOOT_HARDWARE_DOWNGRADE_PREVENTION`` | Enable hardware downgrade protection in MCUboot and application | +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_MCUBOOT_HW_DOWNGRADE_PREVENTION_COUNTER_SLOTS` | Number of available hardware counter slots for downgrade prevention | +| ``SB_CONFIG_MCUBOOT_HW_DOWNGRADE_PREVENTION_COUNTER_SLOTS`` | Number of available hardware counter slots for downgrade prevention | +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_MCUBOOT_HW_DOWNGRADE_PREVENTION_COUNTER_VALUE` | Security counter value of the image for downgrade prevention | +| ``SB_CONFIG_MCUBOOT_HW_DOWNGRADE_PREVENTION_COUNTER_VALUE`` | Security counter value of the image for downgrade prevention | +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_MCUBOOT_UPDATEABLE_IMAGES` | Number of updateable images for MCUboot to support | +| ``SB_CONFIG_MCUBOOT_UPDATEABLE_IMAGES`` | Number of updateable images for MCUboot to support | +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_MCUBOOT_APP_SYNC_UPDATEABLE_IMAGES` | Will set the main application number of updateable images as well as MCUboot if enabled, otherwise will only set MCUboot | +| ``SB_CONFIG_MCUBOOT_APP_SYNC_UPDATEABLE_IMAGES`` | Will set the main application number of updateable images as well as MCUboot if enabled, otherwise will only set MCUboot | +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_SECURE_BOOT_MCUBOOT_VERSION` | MCUboot version string to use when creating MCUboot update package for application secure boot mode | +| ``SB_CONFIG_SECURE_BOOT_MCUBOOT_VERSION`` | MCUboot version string to use when creating MCUboot update package for application secure boot mode | +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ Support for unsigned images and image encryption has been added. @@ -178,23 +178,23 @@ The following Kconfig options are available: +------------------------------------------------------------+-----------------------------------------------------------------------------------------+ | Kconfig option | Description | +============================================================+=========================================================================================+ -| :kconfig:option:`SB_CONFIG_SECURE_BOOT_APPCORE` | Enable secure boot for application core (or main core if device only has a single core) | +| ``SB_CONFIG_SECURE_BOOT_APPCORE`` | Enable secure boot for application core (or main core if device only has a single core) | +------------------------------------------------------------+-----------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_SECURE_BOOT_NETCORE` | Enable secure boot for network core | +| ``SB_CONFIG_SECURE_BOOT_NETCORE`` | Enable secure boot for network core | +------------------------------------------------------------+-----------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_SECURE_BOOT_SIGNING_PYTHON` | Sign b0 images using python (default) | +| ``SB_CONFIG_SECURE_BOOT_SIGNING_PYTHON`` | Sign b0 images using python (default) | +------------------------------------------------------------+-----------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_SECURE_BOOT_SIGNING_OPENSSL` | Sign b0 images using OpenSSL | +| ``SB_CONFIG_SECURE_BOOT_SIGNING_OPENSSL`` | Sign b0 images using OpenSSL | +------------------------------------------------------------+-----------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_SECURE_BOOT_SIGNING_CUSTOM` | Sign b0 images with a custom command | +| ``SB_CONFIG_SECURE_BOOT_SIGNING_CUSTOM`` | Sign b0 images with a custom command | +------------------------------------------------------------+-----------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_SECURE_BOOT_SIGNING_KEY_FILE` | Absolute path to signing private key file | +| ``SB_CONFIG_SECURE_BOOT_SIGNING_KEY_FILE`` | Absolute path to signing private key file | +------------------------------------------------------------+-----------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_SECURE_BOOT_SIGNING_COMMAND` | Command called for custom signing, will have file to sign provided as an argument | +| ``SB_CONFIG_SECURE_BOOT_SIGNING_COMMAND`` | Command called for custom signing, will have file to sign provided as an argument | +------------------------------------------------------------+-----------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_SECURE_BOOT_SIGNING_PUBLIC_KEY` | Absolute path to signing key public file | +| ``SB_CONFIG_SECURE_BOOT_SIGNING_PUBLIC_KEY`` | Absolute path to signing key public file | +------------------------------------------------------------+-----------------------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_SECURE_BOOT_PUBLIC_KEY_FILES` | Comma-separated value list of absolute paths to signing public key files | +| ``SB_CONFIG_SECURE_BOOT_PUBLIC_KEY_FILES`` | Comma-separated value list of absolute paths to signing public key files | +------------------------------------------------------------+-----------------------------------------------------------------------------------------+ Secure boot can now be enabled centrally from sysbuild for both the application and network cores for nRF53-based boards. @@ -213,14 +213,14 @@ The following Kconfig options are available: +------------------------------------------+----------------------------------------+ | Kconfig option | Description | +==========================================+========================================+ -| :kconfig:option:`SB_CONFIG_BT_FAST_PAIR` | Enables Google Fast Pair functionality | +| ``SB_CONFIG_BT_FAST_PAIR`` | Enables Google Fast Pair functionality | +------------------------------------------+----------------------------------------+ To generate the Google Fast Pair provisioning data, you must set this Kconfig option at the sysbuild level. The method of supplying the Fast Pair Model ID and Anti-Spoofing Private Key via the command line arguments remains unchanged from previous |NCS| versions. .. note:: - When building with sysbuild, the value of the :kconfig:option:`CONFIG_BT_FAST_PAIR` Kconfig option is overwritten by :kconfig:option:`SB_CONFIG_BT_FAST_PAIR`. + When building with sysbuild, the value of the :kconfig:option:`CONFIG_BT_FAST_PAIR` Kconfig option is overwritten by ``SB_CONFIG_BT_FAST_PAIR``. For more details about enabling Fast Pair for your application, see the :ref:`ug_bt_fast_pair_prerequisite_ops_kconfig` section in the Fast Pair integration guide. .. _child_parent_to_sysbuild_migration_matter: @@ -234,15 +234,15 @@ The following Kconfig options are available: +---------------------------------------------------------------------+---------------------------------------------------+ | Kconfig option | Description | +=====================================================================+===================================================+ -| :kconfig:option:`SB_CONFIG_MATTER` | Enable matter support | +| ``SB_CONFIG_MATTER`` | Enable matter support | +---------------------------------------------------------------------+---------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_MATTER_FACTORY_DATA_GENERATE` | Generate factory data | +| ``SB_CONFIG_MATTER_FACTORY_DATA_GENERATE`` | Generate factory data | +---------------------------------------------------------------------+---------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_MATTER_FACTORY_DATA_MERGE_WITH_FIRMWARE` | Merge factory data with main application firmware | +| ``SB_CONFIG_MATTER_FACTORY_DATA_MERGE_WITH_FIRMWARE`` | Merge factory data with main application firmware | +---------------------------------------------------------------------+---------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_MATTER_OTA` | Generate over-the-air firmware update image | +| ``SB_CONFIG_MATTER_OTA`` | Generate over-the-air firmware update image | +---------------------------------------------------------------------+---------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_MATTER_OTA_IMAGE_FILE_NAME` | Filename for over-the-air firmware update image | +| ``SB_CONFIG_MATTER_OTA_IMAGE_FILE_NAME`` | Filename for over-the-air firmware update image | +---------------------------------------------------------------------+---------------------------------------------------+ Applications must enable these options if they generate factory data or need an over-the-air firmware update. @@ -254,7 +254,7 @@ Applications must enable these options if they generate factory data or need an .. _child_parent_to_sysbuild_migration_nrf700x: nRF700x -####### +======= Support for nRF700x operating mode and firmware storage has moved to sysbuild. The following Kconfig options are available: @@ -262,21 +262,21 @@ The following Kconfig options are available: +----------------------------------------------------------------+-----------------------------------------------------------------------------+ | Kconfig option | Description | +================================================================+=============================================================================+ -| :kconfig:option:`SB_CONFIG_WIFI_NRF700X` | Enable Wifi support for nRF700x | +| ``SB_CONFIG_WIFI_NRF700X`` | Enable Wifi support for nRF700x | +----------------------------------------------------------------+-----------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_WIFI_NRF700X_SYSTEM_MODE` | Use system mode firmware patches and set application to this mode | +| ``SB_CONFIG_WIFI_NRF700X_SYSTEM_MODE`` | Use system mode firmware patches and set application to this mode | +----------------------------------------------------------------+-----------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_WIFI_NRF700X_SCAN_ONLY` | Use scan-only mode firmware patches and set application to this mode | +| ``SB_CONFIG_WIFI_NRF700X_SCAN_ONLY`` | Use scan-only mode firmware patches and set application to this mode | +----------------------------------------------------------------+-----------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_WIFI_NRF700X_RADIO_TEST` | Use radio test mode firmware patches and set application to this mode | +| ``SB_CONFIG_WIFI_NRF700X_RADIO_TEST`` | Use radio test mode firmware patches and set application to this mode | +----------------------------------------------------------------+-----------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_WIFI_NRF700X_SYSTEM_WITH_RAW_MODES` | Use system with raw modes firmware patches and set application to this mode | +| ``SB_CONFIG_WIFI_NRF700X_SYSTEM_WITH_RAW_MODES`` | Use system with raw modes firmware patches and set application to this mode | +----------------------------------------------------------------+-----------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_WIFI_PATCHES_EXT_FLASH_DISABLED` | Load firmware patches directly from ram (default) | +| ``SB_CONFIG_WIFI_PATCHES_EXT_FLASH_DISABLED`` | Load firmware patches directly from ram (default) | +----------------------------------------------------------------+-----------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_WIFI_PATCHES_EXT_FLASH_XIP` | Load firmware patches from external flash using XIP | +| ``SB_CONFIG_WIFI_PATCHES_EXT_FLASH_XIP`` | Load firmware patches from external flash using XIP | +----------------------------------------------------------------+-----------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_WIFI_PATCHES_EXT_FLASH_STORE` | Load firmware patches from external flash into RAM and load to radio | +| ``SB_CONFIG_WIFI_PATCHES_EXT_FLASH_STORE`` | Load firmware patches from external flash into RAM and load to radio | +----------------------------------------------------------------+-----------------------------------------------------------------------------+ You must update your applications to select the required Kconfig options at the sysbuild level for applications to work. @@ -294,15 +294,15 @@ The following Kconfig options are available: +-------------------------------------------------------------------+---------------------------------------------------+ | Kconfig option | Description | +===================================================================+===================================================+ -| :kconfig:option:`SB_CONFIG_DFU_MULTI_IMAGE_PACKAGE_BUILD` | Enables building a DFU multi-image package | +| ``SB_CONFIG_DFU_MULTI_IMAGE_PACKAGE_BUILD`` | Enables building a DFU multi-image package | +-------------------------------------------------------------------+---------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_DFU_MULTI_IMAGE_PACKAGE_APP` | Include application update in package | +| ``SB_CONFIG_DFU_MULTI_IMAGE_PACKAGE_APP`` | Include application update in package | +-------------------------------------------------------------------+---------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_DFU_MULTI_IMAGE_PACKAGE_NET` | Include network core image update in package | +| ``SB_CONFIG_DFU_MULTI_IMAGE_PACKAGE_NET`` | Include network core image update in package | +-------------------------------------------------------------------+---------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_DFU_MULTI_IMAGE_PACKAGE_MCUBOOT` | Include MCUboot update in package | +| ``SB_CONFIG_DFU_MULTI_IMAGE_PACKAGE_MCUBOOT`` | Include MCUboot update in package | +-------------------------------------------------------------------+---------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_DFU_MULTI_IMAGE_PACKAGE_WIFI_FW_PATCH` | Include nRF7000x firmware patch update in package | +| ``SB_CONFIG_DFU_MULTI_IMAGE_PACKAGE_WIFI_FW_PATCH`` | Include nRF7000x firmware patch update in package | +-------------------------------------------------------------------+---------------------------------------------------+ You must update your application to select the required Kconfig options at the sysbuild level to have this file generated. @@ -318,15 +318,15 @@ The following Kconfig options are available: +-------------------------------------------------------------+----------------------------------------------------------------------------+ | Kconfig option | Description | +=============================================================+============================================================================+ -| :kconfig:option:`SB_CONFIG_DFU_ZIP` | Will generate a dfu_application.zip archive with manifest file and updates | +| ``SB_CONFIG_DFU_ZIP`` | Will generate a dfu_application.zip archive with manifest file and updates | +-------------------------------------------------------------+----------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_DFU_ZIP_APP` | Include application update in zip archive | +| ``SB_CONFIG_DFU_ZIP_APP`` | Include application update in zip archive | +-------------------------------------------------------------+----------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_DFU_ZIP_NET` | Include network-core image update in zip archive | +| ``SB_CONFIG_DFU_ZIP_NET`` | Include network-core image update in zip archive | +-------------------------------------------------------------+----------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_DFU_ZIP_WIFI_FW_PATCH` | Include nRF700x firmware patch update in zip archive | +| ``SB_CONFIG_DFU_ZIP_WIFI_FW_PATCH`` | Include nRF700x firmware patch update in zip archive | +-------------------------------------------------------------+----------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_DFU_ZIP_BLUETOOTH_MESH_METADATA` | Include Bluetooth mesh metadata in zip archive | +| ``SB_CONFIG_DFU_ZIP_BLUETOOTH_MESH_METADATA`` | Include Bluetooth mesh metadata in zip archive | +-------------------------------------------------------------+----------------------------------------------------------------------------+ You must update your application to select the required Kconfig options at the sysbuild level to have the correct firmware update images in the zip generated, the firmware zip is generated by default. @@ -342,13 +342,13 @@ The following Kconfig options are available: +-----------------------------------------------------------------+----------------------------------------------------------------------------+ | Kconfig option | Description | +=================================================================+============================================================================+ -| :kconfig:option:`SB_CONFIG_PARTITION_MANAGER` | Enables partition manager support | +| ``SB_CONFIG_PARTITION_MANAGER`` | Enables partition manager support | +-----------------------------------------------------------------+----------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_PM_MCUBOOT_PAD` | MCUboot image header padding | +| ``SB_CONFIG_PM_MCUBOOT_PAD`` | MCUboot image header padding | +-----------------------------------------------------------------+----------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_PM_EXTERNAL_FLASH_MCUBOOT_SECONDARY` | Places the secondary MCUboot update partition in external flash | +| ``SB_CONFIG_PM_EXTERNAL_FLASH_MCUBOOT_SECONDARY`` | Places the secondary MCUboot update partition in external flash | +-----------------------------------------------------------------+----------------------------------------------------------------------------+ -| :kconfig:option:`SB_CONFIG_PM_OVERRIDE_EXTERNAL_DRIVER_CHECK` | Will force override the external flash driver check | +| ``SB_CONFIG_PM_OVERRIDE_EXTERNAL_DRIVER_CHECK`` | Will force override the external flash driver check | +-----------------------------------------------------------------+----------------------------------------------------------------------------+ You must update your applications to select the required Kconfig options at the sysbuild level for applications to work. @@ -357,7 +357,7 @@ If these options are not set, firmware updates may not work or images may fail t .. _child_parent_to_sysbuild_migration_filename_changes: Filename changes -################ +================ Some output file names have changed from child/parent image configurations or have changed the directory where they are created. This is because sysbuild properly namespaces images in a project. @@ -386,7 +386,7 @@ The changes to final output files (ignoring artifacts and intermediary files) ar +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``zephyr/mcuboot_secondary_app_signed.hex`` | ``mcuboot_secondary_app/zephyr/.signed.hex`` where ```` is the applications Kconfig :kconfig:option:`CONFIG_KERNEL_BIN_NAME` value | +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``zephyr/matter.ota`` | ``.ota`` where ```` is the value of Kconfig :kconfig:option:`SB_CONFIG_MATTER_OTA_IMAGE_FILE_NAME` | +| ``zephyr/matter.ota`` | ``.ota`` where ```` is the value of Kconfig ``SB_CONFIG_MATTER_OTA_IMAGE_FILE_NAME`` | +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``zephyr/signed_by_b0_s0_image.hex`` | ``signed_by_b0_.hex`` where ```` is the name of the application | +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -439,27 +439,27 @@ The expected output files are the following: +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------+ | File | Description | +=====================================================+=======================================================================================================+ -| ``matter_weather_station/zephyr/zephyr.hex`` | Unsigned main application hex file | +| ``matter_weather_station/zephyr/zephyr.hex`` | Unsigned main application HEX file | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------+ | ``matter_weather_station/zephyr/zephyr.bin`` | Unsigned main application binary file | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------+ -| ``matter_weather_station/zephyr/zephyr.signed.hex`` | Signed (with MCUboot signing key) main application hex file | +| ``matter_weather_station/zephyr/zephyr.signed.hex`` | Signed (with MCUboot signing key) main application HEX file | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------+ -| ``mcuboot/zephyr/zephyr.hex`` | MCUboot hex file | +| ``mcuboot/zephyr/zephyr.hex`` | MCUboot HEX file | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------+ -| ``ipc_radio/zephyr/zephyr.hex`` | Network core IPC radio hex file | +| ``ipc_radio/zephyr/zephyr.hex`` | Network core IPC radio HEX file | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------+ | ``ipc_radio/zephyr/zephyr.bin`` | Network core IPC radio binary file | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------+ -| ``b0n/zephyr/zephyr.bin`` | Network core secure bootloader hex file | +| ``b0n/zephyr/zephyr.bin`` | Network core secure bootloader binary file | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------+ -| ``b0n/zephyr/zephyr.hex`` | Network core secure bootloader binary file | +| ``b0n/zephyr/zephyr.hex`` | Network core secure bootloader HEX file | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------+ -| ``signed_by_b0_ipc_radio.hex`` | Signed (with b0 signing key) network core IPC radio hex file | +| ``signed_by_b0_ipc_radio.hex`` | Signed (with b0 signing key) network core IPC radio HEX file | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------+ | ``signed_by_b0_ipc_radio.bin`` | Signed (with b0 signing key) network core IPC radio binary file | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------+ -| ``signed_by_mcuboot_and_b0_ipc_radio.hex`` | Signed (with b0 and MCUboot signing key) network core IPC radio update from application core hex file | +| ``signed_by_mcuboot_and_b0_ipc_radio.hex`` | Signed (with b0 and MCUboot signing key) network core IPC radio update from application core HEX file | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------+ Combined files @@ -470,9 +470,9 @@ The expected output files are the following: +-----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | File | Description | +=======================+=======================================================================================================================================================================+ -| ``merged.hex`` | Merged application core hex file (contains merged contents of ``mcuboot/zephyr/zephyr.hex`` and ``matter_weather_station/zephyr/zephyr.signed.hex``) | +| ``merged.hex`` | Merged application core HEX file (contains merged contents of ``mcuboot/zephyr/zephyr.hex`` and ``matter_weather_station/zephyr/zephyr.signed.hex``) | +-----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``merged_CPUNET.hex`` | Merged network core hex file (contains merged contents of ``net_provision.hex``, ``b0n_container.hex``, ``b0n/zephyr/zephyr.hex`` and ``signed_by_b0_ipc_radio.hex``) | +| ``merged_CPUNET.hex`` | Merged network core HEX file (contains merged contents of ``net_provision.hex``, ``b0n_container.hex``, ``b0n/zephyr/zephyr.hex`` and ``signed_by_b0_ipc_radio.hex``) | +-----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ Update files @@ -545,18 +545,18 @@ Without doing this, projects with multiple images (for example, those with MCUbo +-------------------------------+----------------------------------+-----------------------+ | Configuration parameter | Child/parent | Sysbuild | +===============================+==================================+=======================+ -| ``-DFILE_SUFFIX=...`` | Applies to main application only | Applies to all images | +| ``-DFILE_SUFFIX=...`` | Applies only to main application | Applies to all images | ++-------------------------------+----------------------------------+-----------------------+ +| ``-D_FILE_SUFFIX=...`` | Applies only to |Applies only to | +-------------------------------+----------------------------------+-----------------------+ -| ``-D_FILE_SUFFIX=...`` | Applies to only | +| ``-DSNIPPET=...`` | Applies only to main application | Applies to all images | +-------------------------------+----------------------------------+-----------------------+ -| ``-DSNIPPET=...`` | Applies to main application only | Applies to all images | +| ``-D_SNIPPET=...`` | Applies only to |Applies only to | +-------------------------------+----------------------------------+-----------------------+ -| ``-D_SNIPPET=...`` | Applies to only | +| ``-DSHIELD=...`` | Applies only to main application | Applies to all images | +-------------------------------+----------------------------------+-----------------------+ -| ``-DSHIELD=...`` | Applies to main application only | Applies to all images | +| ``-D_SHIELD=...`` | Applies only to |Applies only to | +-------------------------------+----------------------------------+-----------------------+ -| ``-D_SHIELD=...`` | Applies to only | -+-------------------------------+----------------------------------------------------------+ Configuration values that specify Kconfig fragment or overlay files (for example, ``EXTRA_CONF_FILE`` and ``EXTRA_DTC_OVERLAY_FILE``) cannot be applied globally using either child/parent image or sysbuild. They function the same in both systems: @@ -590,37 +590,41 @@ Similarly, CMake will not configure projects using sysbuild unless the invocatio West can build a specific project using sysbuild with the following command: - .. code-block:: console + .. parsed-literal:: + :class: highlight - west build -b --sysbuild + west build -b *board_target* --sysbuild *app_path* .. group-tab:: west (child/parent image) West can build a specific project using child/parent image with the following command: - .. code-block:: console + .. parsed-literal:: + :class: highlight - west build -b --no-sysbuild + west build -b *board_target* --no-sysbuild *app_path* .. note:: This is deprecated in |NCS| 2.7 and support will be removed in |NCS| 2.9 - .. group-tab:: cmake (sysbuild) + .. group-tab:: CMake (sysbuild) CMake can be used to configure a specific project using sysbuild image with the following command: - .. code-block:: console + .. parsed-literal:: + :class: highlight - cmake -GNinja -DBOARD= -DAPP_DIR= /share/sysbuild + cmake -GNinja -DBOARD=*board_target* -DAPP_DIR=*app_path* *path_to_zephyr*/share/sysbuild - .. group-tab:: cmake (child/parent image) + .. group-tab:: CMake (child/parent image) CMake can be used to configure a specific project using child/parent image with the following command: - .. code-block:: console + .. parsed-literal:: + :class: highlight - cmake -GNinja -DBOARD= + cmake -GNinja -DBOARD=*board_target* *app_path* .. note:: @@ -658,7 +662,7 @@ As sysbuild deals with configuration of features for some features and propagati Incompatibities =============== -In the sysbuild release included in the |NCS| 2.7, the following features of the multi-image builds using child an parent images are not supported: +In the sysbuild release included in the |NCS| 2.7, the following features of the multi-image builds using child and parent images are not supported: * Using pre-built HEX files for images (like MCUboot). All images in a project will be built from source diff --git a/doc/nrf/releases_and_maturity/migration/nRF54H20_migration_2.7/images/jlink788j_install.png b/doc/nrf/releases_and_maturity/migration/nRF54H20_migration_2.7/images/jlink788j_install.png new file mode 100644 index 000000000000..c1c6aa0d5a41 Binary files /dev/null and b/doc/nrf/releases_and_maturity/migration/nRF54H20_migration_2.7/images/jlink788j_install.png differ diff --git a/doc/nrf/releases_and_maturity/migration/nRF54H20_migration_2.7/images/jlink794e_install.png b/doc/nrf/releases_and_maturity/migration/nRF54H20_migration_2.7/images/jlink794e_install.png new file mode 100644 index 000000000000..63fb110568aa Binary files /dev/null and b/doc/nrf/releases_and_maturity/migration/nRF54H20_migration_2.7/images/jlink794e_install.png differ diff --git a/doc/nrf/releases_and_maturity/migration/nRF54H20_migration_2.7/migration_guide_2.4.99-cs3_to_2.7_application.rst b/doc/nrf/releases_and_maturity/migration/nRF54H20_migration_2.7/migration_guide_2.4.99-cs3_to_2.7_application.rst new file mode 100644 index 000000000000..12a32384bb32 --- /dev/null +++ b/doc/nrf/releases_and_maturity/migration/nRF54H20_migration_2.7/migration_guide_2.4.99-cs3_to_2.7_application.rst @@ -0,0 +1,752 @@ +.. _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 |NCS| v2.4.99-cs3 to |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 ` 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 ` 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| `, 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 ``/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_.conf` Kconfig configurations should be transitioned to using :file:`boards/.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 `. + 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| `, 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 ` 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_` 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/` directory (for example, :file:`sysbuild/mcuboot`) to the :file:`prj.conf` file located in the :file:`child_image/` directory. + #. Copy the content of the board configuration file located in the :file:`sysbuild//boards` directory (for example, :file:`sysbuild/mcuboot/boards/nrf52840dk_nrf52840.conf`) to the board file located in the :file:`child_image//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 :ref:`zephyr:bluetooth-hci-ipc-sample` 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 `. + 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 ` Kconfig option is no longer available and MRAMC requires writes of the size of the whole MRAM word to the MRAM. diff --git a/doc/nrf/releases_and_maturity/migration/nRF54H20_migration_2.7/migration_guide_2.6.99-cs2_to_2.7_application.rst b/doc/nrf/releases_and_maturity/migration/nRF54H20_migration_2.7/migration_guide_2.6.99-cs2_to_2.7_application.rst new file mode 100644 index 000000000000..c2f662e69a77 --- /dev/null +++ b/doc/nrf/releases_and_maturity/migration/nRF54H20_migration_2.7/migration_guide_2.6.99-cs2_to_2.7_application.rst @@ -0,0 +1,673 @@ +.. _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 |NCS| v2.6.99-cs2 to |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 ` 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 ` 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| `, 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 ``/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 `. + 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| `, 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 ` 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_` 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/` directory (for example, :file:`sysbuild/mcuboot`) to the :file:`prj.conf` file located in the :file:`child_image/` directory. + #. Copy the content of the board configuration file located in the :file:`sysbuild//boards` directory (for example, :file:`sysbuild/mcuboot/boards/nrf52840dk_nrf52840.conf`) to the board file located in the :file:`child_image//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 :ref:`zephyr:bluetooth-hci-ipc-sample` 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 `. + 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 ` Kconfig option is no longer available and MRAMC requires writes of the size of the whole MRAM word to the MRAM. diff --git a/doc/nrf/releases_and_maturity/migration/nRF54H20_migration_2.7/migration_guide_2.6.99-cs2_to_2_7_environment.rst b/doc/nrf/releases_and_maturity/migration/nRF54H20_migration_2.7/migration_guide_2.6.99-cs2_to_2_7_environment.rst new file mode 100644 index 000000000000..bc2a20014192 --- /dev/null +++ b/doc/nrf/releases_and_maturity/migration/nRF54H20_migration_2.7/migration_guide_2.6.99-cs2_to_2_7_environment.rst @@ -0,0 +1,319 @@ +.. _migration_cs2_to_2_7_env: + +Update your development environment for |NCS| v2.7.0 (for v2.6.99-cs2 users) +############################################################################ + +.. contents:: + :local: + :depth: 2 + +This document describes how to update your development environment for the nRF54H20 DK from |NCS| v2.6.99-cs2 to |NCS| v2.7.0. + +Overview +******** + +|NCS| v2.7.0 introduced a series of changes that might affect your existing development environment. +The following is a summary of the most important ones: + +Updated |NCS| toolchain + The |NCS| toolchain has been updated. + +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. + +Minimum requirements +******************** + +Make sure you have all the required hardware, software, and that your computer has one of the supported operating systems. + +Hardware +======== + +* nRF54H20 DK version PCA10175 v0.7.2 (ES3) or PCA10175 v0.8.0 (ES3.3, ES4). + These are the only versions of the nRF54H20 DK compatible with |NCS| v2.7.0. + Check the version number on your DK's sticker to verify its compatibility with |NCS| version v2.7.0. +* USB-C cable. + +Software +======== + +On your computer, one of the following operating systems: + +.. include:: ../../../../nrf/installation/recommended_versions.rst + :start-after: os_table_start + :end-before: os_table_end + +See :ref:`supported_OS` for more information about the tier definitions. + +|supported OS| + +You also need the following: + +* `Git`_ or `Git for Windows`_ (on Linux and Mac, or Windows, respectively) +* `curl`_ +* The latest version of the `nRF Command Line Tools`_ package. + After downloading and installing the tools, add the nrfjprog executable to the system path, on Linux and MacOS, or to the environment variables, on Windows, to run it from anywhere on the system. + + The CLI tools installation will also trigger the installation of J-Link. + During that installation, in the :guilabel:`Choose optional components` window, select :guilabel:`update existing installation`. +* On Windows, SEGGER USB Driver for J-Link from SEGGER `J-Link version 7.94e`_. + + .. note:: + To install the SEGGER USB Driver for J-Link on Windows, you must manually reinstall J-Link v7.94e from the command line using the ``-InstUSBDriver=1`` parameter, updating the installation previously run by the `nRF Command Line Tools`_: + + 1. Navigate to the download location of the J-Link executable and run one of the following commands: + + * From the Command Prompt:: + + JLink_Windows_V794e_x86_64.exe -InstUSBDriver=1 + + * From PowerShell:: + + .\JLink_Windows_V794e_x86_64.exe -InstUSBDriver=1 + + #. In the :guilabel:`Choose optional components` window, select again :guilabel:`update existing installation`. + #. Add the J-Link executable to the system path, on Linux and MacOS, or to the environment variables, on Windows, to run it from anywhere on the system. + +* The latest version of |VSC| for your operating system from the `Visual Studio Code download page`_. +* In |VSC|, the latest version of the `nRF Connect for VS Code Extension Pack`_. +* On Linux, the `nrf-udev`_ module with udev rules required to access USB ports on Nordic Semiconductor devices and program the firmware. + +Updating the |NCS| and its toolchain +************************************ + +You can update to the |NCS| v2.7.0 and its toolchain by using Toolchain Manager. + +Toolchain Manager is a tool available from `nRF Connect for Desktop`_, a cross-platform tool that provides different applications that simplify installing the |NCS|. +Both the tool and the application are available for Windows, Linux, and MacOS. + +To proceed with the update, complete the following steps: + +1. Install Toolchain Manager: + + a. `Download nRF Connect for Desktop`_ for your operating system. + #. Install and run the tool on your machine. + #. In the **APPS** section, click :guilabel:`Install` next to Toolchain Manager. + + The app is installed on your machine, and the :guilabel:`Install` button changes to :guilabel:`Open`. + +#. Open the Toolchain Manager application in nRF Connect for Desktop. +#. Click the button with the arrow pointing down next to the installed |NCS| version to expand the drop-down menu with options. + + .. figure:: ../../../../nrf/installation/images/gs-assistant_tm_dropdown.png + :alt: The Toolchain Manager dropdown menu for the installed nRF Connect SDK version, cropped + + The Toolchain Manager dropdown menu options + +#. In the drop-down menu, click :guilabel:`Update toolchain`. +#. In the same drop-down menu, click :guilabel:`Update SDK`. + +Updating the Terminal application +********************************* + +To update `Serial Terminal from nRF Connect for Desktop`, follow these steps: + +1. On your computer, open `nRF Connect for Desktop`_ + If there is an update available, a pop up will notify you of its availability. +#. If available, install the update from the pop up screen. +#. Update `Serial Terminal from nRF Connect for Desktop`. + +If you are using the nRF Terminal application part of the `nRF Connect for Visual Studio Code`_ extension, open Visual Studio Code instead and ensure you are running the newest version of both the editor and the extension. + +Updating nRF Util and its commands +********************************** + +|NCS| v2.7.0 requires nRF Util version 7.11.1 or above. + +1. Verify the version of the nRF Util installation on your machine by running the following command:: + + nrfutil --version + +#. If your version is below 7.11.1, run the following command to update nRF Util:: + + nrfutil self-upgrade + +#. Add nRF Util to the system path (on Linux and MacOS) or environment variables (on Windows) to run it from anywhere on the system. + On Linux and MacOS, use one of the following options: + + * Add nRF Util's directory to the system path. + * Move the file to a directory in the system path. + +#. On MacOS and Linux, give ``nrfutil`` execute permissions by typing ``chmod +x nrfutil`` in a terminal or using a file browser. + This is typically a checkbox found under file properties. +#. Update the nRF Util ``device`` command to version 2.4.0 as follows:: + + nrfutil install device=2.4.0 --force + +For more information, consult the `nRF Util`_ documentation. + +.. _migration_cs2_to_2_7_env_bringup: + +Verify the LCS of the device +**************************** + +The current nRF54H20 DK is delivered with its lifecycle state (LCS) set to ``EMPTY``. +To correctly operate, its lifecycle state must be transitioned to Root of Trust (``RoT``) through the bring-up steps. +To be compatible with |NCS| v2.7.0, the SDFW and SCFW firmware bundle programmed on the nRF54H20 DK during through the bring-up steps must be v0.5.0. + +.. note:: + The forward transition to LCS ``RoT`` is permanent. + After the transition, it is not possible to transition backward to LCS ``EMPTY``. + +You can verify the current lifecycle state of the nRF54H20 as follows:: + + nrfutil device x-adac-discovery --serial-number + +The output will look similar to the following:: + + *serial_number* + adac_auth_version 1.0 + vendor_id Nordic VLSI ASA + soc_class 0x00005420 + soc_id [e6, 6f, 21, b6, dc, be, 11, ee, e5, 03, 6f, fe, 4d, 7b, 2e, 07] + hw_permissions_fixed [00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00] + hw_permissions_mask [01, 00, 00, 00, 87, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00] + psa_lifecycle LIFECYCLE_EMPTY (0x1000) + sda_id 0x01 + secrom_revision 0xad3b3cd0 + sysrom_revision 0xebc8f190 + token_formats [TokenAdac] + cert_formats [CertAdac] + cryptosystems [Ed25519Sha512] + Additional TLVs: + TargetIdentity: [ff, ff, ff, ff, ff, ff, ff, ff] + +If the lifecycle state (``psa_lifecycle``) shown is not ``RoT`` (``LIFECYCLE_EMPTY (0x1000)`` means the LCS is set to ``EMPTY``) you can follow the bring-up steps in the next chapter. +If the lifecycle state (``psa_lifecycle``) shown is ``RoT`` (``LIFECYCLE_ROT (0x2000)``), the device is in Root of Trust: + +* If your nRF54H20 DK was already programmed with the SDFW and SCFW firmware bundle version 0.5.0, you can jump to the :ref:`migration_cs2_to_2_7_env_nextsteps` chapter. +* If your current nRF54H20 DK was programmed with a firmware bundle version 0.3.x: + + * Use a different nRF54H20 DK with LCS ``EMPTY`` and continue to the nRF54H20 bring-up. + * Use a different nRF54H20 DK with LCS ``RoT`` and already programmed with the firmware bundle version 0.5.0. + +nRF54H20 DK bring-up +******************** + +.. caution:: + Follow these steps only if your device is in lifecycle state ``EMPTY``. + For more information, see `Verify the LCS of the device`_. + +The following sections describe the steps required for the nRF54H20 bring-up. + +.. rst-class:: numbered-step + +Programming the BICR +==================== + +The Board Information Configuration Registers (BICR) are non-volatile memory (NVM) registers that contain information on how the nRF54H20 SoC must interact with other board elements, including the information about the power and clock delivery to the SoC. +To prepare the nRF54H20 DK for first use, you must manually program the values of the BICR using a precompiled BICR binary file (:file:`bicr_ext_loadcap.hex`). + +1. Download the `BICR binary file`_ . +#. Connect the nRF54H20 DK to your computer using the **DEBUGGER** port on the DK. + +.. note:: + On MacOS, connecting the DK might cause a popup containing the message ``“Disk Not Ejected Properly`` to repeatedly appear on screen. + To disable this, run ``JLinkExe``, then run ``MSDDisable`` in the J-Link Commander interface. + +#. List all the connected development kits to see their serial number (matching the one on the DK's sticker):: + + nrfutil device list + +#. Move the BICR HEX file to a folder of your choice, then program the BICR by running nRF Util from that folder using the following command:: + + nrfutil device program --options chip_erase_mode=ERASE_NONE --firmware bicr_ext_loadcap.hex --core Secure --serial-number + +.. rst-class:: numbered-step + +Provisioning the SDFW and SCFW +============================== + +After programming the BICR, the nRF54H20 SoC requires the provisioning of a bundle ( :file:`nrf54h20_soc_binaries_v0.5.0.zip`) containing the precompiled firmware for the Secure Domain and System Controller. +To program the Secure Domain Firmware (SDFW, also known as ``urot``) and the System Controller Firmware (SCFW) from the firmware bundle to the nRF54H20 DK, do the following: + +1. Download the `nRF54H20 firmware bundle v0.5.0`_. + + .. note:: + On MacOS, ensure that the ZIP file is not unpacked automatically upon download. + +#. Move the :file:`.zip` bundle to a folder of your choice, then run nRF Util to program the binaries using the following command:: + + nrfutil device x-provision-nrf54h --firmware --serial-number + +.. rst-class:: numbered-step + +Updating the FICR +================= + +.. caution:: + This step is required only if your nRF54H20 DK is version PCA10175 v0.7.2 or v0.8.0 ES3.3. + Jump to the next step if your DK is version ES4, meaning v0.8.0 with no ES markings. + +After programming the SDFW and SCFW from the firmware bundle, you must update the Factory Information Configuration Registers (FICR) to correctly configure some trims of the nRF54H20 SoC. +To update the FICR, you must run a J-Link script: + +1. Get the Jlink script that updates the FICR:: + + curl -LO https://files.nordicsemi.com/artifactory/swtools/external/scripts/nrf54h20es_trim_adjust.jlink + +#. Run the script: + + * Linux and Mac OS:: + + JLinkExe -CommanderScript nrf54h20es_trim_adjust.jlink + + * Windows:: + + jlink.exe -CommanderScript nrf54h20es_trim_adjust.jlink + +.. _migration_cs2_to_2_7_env_lcsrot: + +.. rst-class:: numbered-step + +Transitioning the nRF54H20 SoC to RoT +===================================== + +Set the device to Root of Trust using the following command:: + + nrfutil device x-adac-lcs-change --life-cycle rot --serial-number + +#. Verify again the current lifecycle state of the nRF54H20:: + + nrfutil device x-adac-discovery --serial-number + + The output will look similar to the following:: + + *serial_number* + adac_auth_version 1.0 + vendor_id Nordic VLSI ASA + soc_class 0x00005420 + soc_id [e6, 6f, 21, b6, dc, be, 11, ee, e5, 03, 6f, fe, 4d, 7b, 2e, 07] + hw_permissions_fixed [00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00] + hw_permissions_mask [01, 00, 00, 00, 87, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00] + psa_lifecycle LIFECYCLE_ROT (0x2000) + sda_id 0x01 + secrom_revision 0xad3b3cd0 + sysrom_revision 0xebc8f190 + token_formats [TokenAdac] + cert_formats [CertAdac] + cryptosystems [Ed25519Sha512] + Additional TLVs: + TargetIdentity: [ff, ff, ff, ff, ff, ff, ff, ff] + + The lifecycle state (``psa_lifecycle``) is now correctly set to *Root of Trust* (``LIFECYCLE_ROT (0x2000)``) + +#. After the LCS transition, reset the device:: + + nrfutil device reset --reset-kind RESET_PIN --serial-number + +.. _migration_cs2_to_2_7_env_nextsteps: + +Next steps +********** + +Your environment is now set to use the |NCS| v2.7.0 with the nRF54H20 DK: + +* If you want to modify your existing custom applications previously developed for |NCS| v2.6.99-cs2 to be compatible with v2.7.0, consult the :ref:`migration_2_6_99_cs2_to_2_7_app` page. +* If you want to build and program a sample application on your nRF54H20 DK, consult the building and programming section in the :ref:`ug_nrf54h20_gs` page. diff --git a/doc/nrf/releases_and_maturity/migration/nRF54H20_migration_2.7/transition_guide_2.4.99-cs3_to_2.7_environment.rst b/doc/nrf/releases_and_maturity/migration/nRF54H20_migration_2.7/transition_guide_2.4.99-cs3_to_2.7_environment.rst new file mode 100644 index 000000000000..97a01e8bc54b --- /dev/null +++ b/doc/nrf/releases_and_maturity/migration/nRF54H20_migration_2.7/transition_guide_2.4.99-cs3_to_2.7_environment.rst @@ -0,0 +1,354 @@ +.. _transition_cs3_to_2_7_env: + +Transition your development environment to |NCS| v2.7.0 (for v2.4.99-cs3 users) +############################################################################### + +.. contents:: + :local: + :depth: 2 + +This document describes how to transition your development environment for the nRF54H20 DK from |NCS| v2.4.99-cs3 to |NCS| v2.7.0. + +The main development environment changes introduced by v2.7.0 for the nRF54H20 DK are the following: + +* The |NCS| toolchain has been updated. +* nRF Util is now used by the build system. +* 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`. + See the details in the `nRF54H20 DK bring-up`_ section below. +* 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``. + +Minimum requirements +******************** + +Make sure you have all the required hardware, software, and that your computer has one of the supported operating systems. + +Hardware +======== + +* nRF54H20 DK version PCA10175 v0.7.2 (ES3) or PCA10175 v0.8.0 (ES3.3, ES4). + These are the only versions of the nRF54H20 DK compatible with |NCS| v2.7.0. + Check the version number on your DK's sticker to verify its compatibility with |NCS| version v2.7.0. +* USB-C cable. + +Software +======== + +On your computer, one of the following operating systems: + +.. include:: ../../../../nrf/installation/recommended_versions.rst + :start-after: os_table_start + :end-before: os_table_end + +See :ref:`supported_OS` for more information about the tier definitions. + +|supported OS| + +You also need the following: + +* `Git`_ or `Git for Windows`_ (on Linux and Mac, or Windows, respectively) +* `curl`_ +* The latest version of the `nRF Command Line Tools`_ package. + After downloading and installing the tools, add the nrfjprog executable to the system path, on Linux and MacOS, or to the environment variables, on Windows, to run it from anywhere on the system. + + The CLI tools installation will also trigger the installation of J-Link. + During that installation, in the :guilabel:`Choose optional components` window, select :guilabel:`update existing installation`. +* On Windows, SEGGER USB Driver for J-Link from SEGGER `J-Link version 7.94e`_. + + .. note:: + To install the SEGGER USB Driver for J-Link on Windows, you must manually reinstall J-Link v7.94e from the command line using the ``-InstUSBDriver=1`` parameter, updating the installation previously run by the `nRF Command Line Tools`_: + + 1. Navigate to the download location of the J-Link executable and run one of the following commands: + + * From the Command Prompt:: + + JLink_Windows_V794e_x86_64.exe -InstUSBDriver=1 + + * From PowerShell:: + + .\JLink_Windows_V794e_x86_64.exe -InstUSBDriver=1 + + #. In the :guilabel:`Choose optional components` window, select again :guilabel:`update existing installation`. + #. Add the J-Link executable to the system path, on Linux and MacOS, or to the environment variables, on Windows, to run it from anywhere on the system. + +* The latest version of |VSC| for your operating system from the `Visual Studio Code download page`_. +* In |VSC|, the latest version of the `nRF Connect for VS Code Extension Pack`_. +* On Linux, the `nrf-udev`_ module with udev rules required to access USB ports on Nordic Semiconductor devices and program the firmware. + +Preliminary step +**************** + +Before transitioning to the new toolchain, rename your existing ``ncs-lcs`` and ``.west`` folders (for example as ``ncs-lcs_old`` and ``.west_old``) to back up their files. + +.. note:: + If you have multiple folders initialized with ``west``, it is suggested to back up all the relevant ``.west`` folders. + +Transitioning to the |NCS| v2.7.0 +********************************* + +You can transition to the |NCS| v2.7.0 by using Toolchain Manager. + +Toolchain Manager is a tool available from `nRF Connect for Desktop`_, a cross-platform tool that provides different applications that simplify installing the |NCS|. +Both the tool and the application are available for Windows, Linux, and MacOS. + +To install the toolchain and the SDK using the Toolchain Manager app, complete the following steps: + +1. Install Toolchain Manager: + + a. `Download nRF Connect for Desktop`_ for your operating system. + #. Install and run the tool on your machine. + #. In the **APPS** section, click :guilabel:`Install` next to Toolchain Manager. + + The app is installed on your machine, and the :guilabel:`Install` button changes to :guilabel:`Open`. + +#. Install the |NCS| source code: + + a. Open Toolchain Manager in nRF Connect for Desktop. + + .. figure:: ../../../../nrf/installation/images/gs-assistant_tm.png + :alt: The Toolchain Manager window + + The Toolchain Manager window + + #. Click :guilabel:`SETTINGS` in the navigation bar to specify where you want to install the |NCS|. + #. In :guilabel:`SDK ENVIRONMENTS`, click the :guilabel:`Install` button next to the |NCS| version 2.7.0. + + The |NCS| version 2.7.0 is installed on your machine. + The :guilabel:`Install` button changes to :guilabel:`Open VS Code`. + +#. Set up the preferred building method: + + .. tabs:: + + .. tab:: nRF Connect for Visual Studio Code + + To build on the |nRFVSC|, complete the following steps: + + a. In Toolchain Manager, click the :guilabel:`Open VS Code` button. + + A notification appears with a list of missing extensions that you need to install, including those from the `nRF Connect for Visual Studio Code`_ extension pack. + #. Click **Install missing extensions**, then close VS Code. + #. Once the extensions are installed, click **Open VS Code** button again. + + You can then follow the instructions in :ref:`creating_vsc`. + + .. tab:: Command line + + To build on the command line, complete the following steps: + + 1. With admin permissions enabled, download and install the `nRF Command Line Tools`_. + #. Restart the Toolchain Manager application. + #. Click the dropdown menu for the installed nRF Connect SDK version. + + .. figure:: ../../../../nrf/installation/images/gs-assistant_tm_dropdown.png + :alt: The Toolchain Manager dropdown menu for the installed nRF Connect SDK version, cropped + + The Toolchain Manager dropdown menu options + + #. Select :guilabel:`Open command prompt`. + + You can then follow the instructions in :ref:`creating_cmd`. + +#. If you have any existing custom applications created for 2.4.99-cs3 that you would like to migrate, move its files from the previous ``ncs-lcs_old`` folder to the newly created |NCS| installation folder. + +Updating the Terminal application +********************************* + +To update `Serial Terminal from nRF Connect for Desktop`, follow these steps: + +1. On your computer, open `nRF Connect for Desktop`_ + If there is an update available, a pop up will notify you of its availability. +#. If available, install the update from the pop up screen. +#. Update `Serial Terminal from nRF Connect for Desktop`. + +If you are using the nRF Terminal application part of the `nRF Connect for Visual Studio Code`_ extension, open Visual Studio Code instead and ensure you are running the newest version of both the editor and the extension. + +Installing nRF Util and its commands +************************************ + +Using the nRF54H20 DK with the |NCS| v2.7.0 requires the following: + +* nRF Util version 7.11.1 or above +* nRF Util ``device`` version 2.4.0 + +1. Download the nrfutil executable file from the `nRF Util development tool`_ product page. +#. Add nRF Util to the system path (on Linux and MacOS) or environment variables (on Windows) to run it from anywhere on the system. + On Linux and MacOS, use one of the following options: + + * Add nRF Util's directory to the system path. + * Move the file to a directory in the system path. + +#. On MacOS and Linux, give ``nrfutil`` execute permissions by typing ``chmod +x nrfutil`` in a terminal or using a file browser. + This is typically a checkbox found under file properties. +#. Verify the version of the nRF Util installation on your machine by running the following command:: + + nrfutil --version + +#. If your version is below 7.11.1, run the following command to update nRF Util:: + + nrfutil self-upgrade + +#. Install the nRF Util ``device`` command to version 2.4.0 as follows:: + + nrfutil install device=2.4.0 --force + +For more information, consult the `nRF Util`_ documentation. + +.. _transition_cs3_to_2_7_env_bringup: + +nRF54H20 DK bring-up +******************** + +The following sections describe the steps required for the nRF54H20 bring-up. + +.. rst-class:: numbered-step + +Programming the BICR +==================== + +The Board Information Configuration Registers (BICR) are non-volatile memory (NVM) registers that contain information on how the nRF54H20 SoC must interact with other board elements, including the information about the power and clock delivery to the SoC. +To prepare the nRF54H20 DK for first use, you must manually program the values of the BICR using a precompiled BICR binary file (:file:`bicr_ext_loadcap.hex`). + +1. Download the `BICR binary file`_ . +#. Connect the nRF54H20 DK to your computer using the **DEBUGGER** port on the DK. + +.. note:: + On MacOS, connecting the DK might cause a popup containing the message ``“Disk Not Ejected Properly`` to repeatedly appear on screen. + To disable this, run ``JLinkExe``, then run ``MSDDisable`` in the J-Link Commander interface. + +#. List all the connected development kits to see their serial number (matching the one on the DK's sticker):: + + nrfutil device list + +#. Move the BICR HEX file to a folder of your choice, then program the BICR by running nRF Util from that folder using the following command:: + + nrfutil device program --options chip_erase_mode=ERASE_NONE --firmware bicr_ext_loadcap.hex --core Secure --serial-number + +.. rst-class:: numbered-step + +Programming the SDFW and SCFW +============================= + +After programming the BICR, the nRF54H20 SoC requires the provisioning of a bundle ( :file:`nrf54h20_soc_binaries_v0.5.0.zip`) containing the precompiled firmware for the Secure Domain and System Controller. +To program the Secure Domain Firmware (SDFW, also known as ``urot``) and the System Controller Firmware (SCFW) from the firmware bundle to the nRF54H20 DK, do the following: + +1. Download the `nRF54H20 firmware bundle v0.5.0`_. + + .. note:: + On MacOS, ensure that the ZIP file is not unpacked automatically upon download. + +#. Move the :file:`.zip` bundle to a folder of your choice, then run nRF Util to program the binaries using the following command:: + + nrfutil device x-provision-nrf54h --firmware --serial-number + +.. rst-class:: numbered-step + +Updating the FICR +================= + +.. caution:: + This step is required only if your nRF54H20 DK is version PCA10175 v0.7.2 or v0.8.0 ES3.3. + Jump to the next step if your DK is version ES4, meaning v0.8.0 with no ES markings. + +After programming the SDFW and SCFW from the firmware bundle, you must update the Factory Information Configuration Registers (FICR) to correctly configure some trims of the nRF54H20 SoC. +To update the FICR, you must run a J-Link script: + +1. Get the Jlink script that updates the FICR:: + + curl -LO https://files.nordicsemi.com/artifactory/swtools/external/scripts/nrf54h20es_trim_adjust.jlink + +#. Run the script: + + * Linux and Mac OS:: + + JLinkExe -CommanderScript nrf54h20es_trim_adjust.jlink + + * Windows:: + + jlink.exe -CommanderScript nrf54h20es_trim_adjust.jlink + +.. _transition_cs3_to_2_7_env_lcsrot: + +.. rst-class:: numbered-step + +Transitioning the nRF54H20 SoC to RoT +===================================== + +The current nRF54H20 DK is delivered with its lifecycle state (LCS) set to ``EMPTY``. +To correctly operate, its lifecycle state must be transitioned to Root of Trust (``RoT``). + +.. note:: + The forward transition to LCS ``RoT`` is permanent. + After the transition, it is not possible to transition backward to LCS ``EMPTY``. + +To transition the LCS to ``RoT``, do the following: + +1. Verify the current lifecycle state of the nRF54H20:: + + nrfutil device x-adac-discovery --serial-number + + The output will look similar to the following:: + + *serial_number* + adac_auth_version 1.0 + vendor_id Nordic VLSI ASA + soc_class 0x00005420 + soc_id [e6, 6f, 21, b6, dc, be, 11, ee, e5, 03, 6f, fe, 4d, 7b, 2e, 07] + hw_permissions_fixed [00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00] + hw_permissions_mask [01, 00, 00, 00, 87, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00] + psa_lifecycle LIFECYCLE_EMPTY (0x1000) + sda_id 0x01 + secrom_revision 0xad3b3cd0 + sysrom_revision 0xebc8f190 + token_formats [TokenAdac] + cert_formats [CertAdac] + cryptosystems [Ed25519Sha512] + Additional TLVs: + TargetIdentity: [ff, ff, ff, ff, ff, ff, ff, ff] + +#. If the lifecycle state (``psa_lifecycle``) shown is ``RoT`` (``LIFECYCLE_ROT (0x2000)``), no LCS transition is required. + If the lifecycle state (``psa_lifecycle``) shown is not ``RoT`` (``LIFECYCLE_EMPTY (0x1000)`` means the LCS is set to ``EMPTY``), set it to Root of Trust using the following command:: + + nrfutil device x-adac-lcs-change --life-cycle rot --serial-number + +#. Verify again the current lifecycle state of the nRF54H20:: + + nrfutil device x-adac-discovery --serial-number + + The output will look similar to the following:: + + *serial_number* + adac_auth_version 1.0 + vendor_id Nordic VLSI ASA + soc_class 0x00005420 + soc_id [e6, 6f, 21, b6, dc, be, 11, ee, e5, 03, 6f, fe, 4d, 7b, 2e, 07] + hw_permissions_fixed [00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00] + hw_permissions_mask [01, 00, 00, 00, 87, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00] + psa_lifecycle LIFECYCLE_ROT (0x2000) + sda_id 0x01 + secrom_revision 0xad3b3cd0 + sysrom_revision 0xebc8f190 + token_formats [TokenAdac] + cert_formats [CertAdac] + cryptosystems [Ed25519Sha512] + Additional TLVs: + TargetIdentity: [ff, ff, ff, ff, ff, ff, ff, ff] + + The lifecycle state (``psa_lifecycle``) is now correctly set to *Root of Trust* (``LIFECYCLE_ROT (0x2000)``) + +#. After the LCS transition, reset the device:: + + nrfutil device reset --reset-kind RESET_PIN --serial-number + +Next steps +********** + +Your environment is now set to use the |NCS| v2.7.0 with the nRF54H20 DK: + +* If you want to modify your existing custom applications previously developed for |NCS| v2.4.99-cs3 to be compatible with v2.7.0, consult the :ref:`migration_cs3_to_to_2_7_app` page. +* If you want to build and program a sample application on your nRF54H20 DK, consult the building and programming section in the :ref:`ug_nrf54h20_gs` page. diff --git a/doc/nrf/shortcuts.txt b/doc/nrf/shortcuts.txt index 8fb62c2bec33..f6f731d9b1ea 100644 --- a/doc/nrf/shortcuts.txt +++ b/doc/nrf/shortcuts.txt @@ -212,8 +212,10 @@ .. |sysbuild_related_deprecation_note| replace:: This feature is deprecated and is being replaced by Zephyr's :ref:`zephyr:sysbuild`. You can continue to use it until the transition is complete in the |NCS| and the feature is removed in one of the upcoming |NCS| releases. + For more information, see :ref:`zephyr:sysbuild`, :ref:`sysbuild_images`, :ref:`zephyr_samples_sysbuild`, and :ref:`sysbuild_forced_options`. -.. |sysbuild_autoenabled_ncs| replace:: In the :ref:`nRF repositories `, building with sysbuild is :ref:`enabled by default `. +.. |sysbuild_autoenabled_ncs| replace:: When building :ref:`workspace applications ` copied from :ref:`nRF repositories `, building with sysbuild is :ref:`enabled by default `. + If you work with out-of-tree :ref:`freestanding applications `, you need to manually pass ``--sysbuild`` to build commands. .. |file_suffix_related_deprecation_note| replace:: This feature is deprecated and is being replaced by :ref:`suffix-based configurations `. You can continue to use it until the transition is complete in the |NCS| and the feature is removed in one of the upcoming |NCS| releases. diff --git a/samples/benchmarks/coremark/README.rst b/samples/benchmarks/coremark/README.rst index f5200015f2a8..96559aa39b4e 100644 --- a/samples/benchmarks/coremark/README.rst +++ b/samples/benchmarks/coremark/README.rst @@ -165,6 +165,8 @@ When running the benchmark, an extra build flag (:kconfig:option:`CONFIG_COMPILE After flashing, messages describing the benchmark state will appear in the console. +.. include:: /includes/nRF54H20_erase_UICR.txt + Testing ======= diff --git a/samples/bluetooth/central_and_peripheral_hr/README.rst b/samples/bluetooth/central_and_peripheral_hr/README.rst index d73e458dfe65..e0983b319f86 100644 --- a/samples/bluetooth/central_and_peripheral_hr/README.rst +++ b/samples/bluetooth/central_and_peripheral_hr/README.rst @@ -84,6 +84,7 @@ Building and running .. include:: /includes/build_and_run_ns.txt +.. include:: /includes/nRF54H20_erase_UICR.txt .. _central_and_peripheral_hrs_testing: diff --git a/samples/bluetooth/central_hids/README.rst b/samples/bluetooth/central_hids/README.rst index 73d92b164bda..1cd062f753fd 100644 --- a/samples/bluetooth/central_hids/README.rst +++ b/samples/bluetooth/central_hids/README.rst @@ -91,6 +91,7 @@ Building and Running .. include:: /includes/build_and_run_ns.txt +.. include:: /includes/nRF54H20_erase_UICR.txt Testing ======= diff --git a/samples/bluetooth/central_uart/README.rst b/samples/bluetooth/central_uart/README.rst index 54eaabd5f4b9..7650c4c703ff 100644 --- a/samples/bluetooth/central_uart/README.rst +++ b/samples/bluetooth/central_uart/README.rst @@ -52,6 +52,7 @@ Building and running .. include:: /includes/build_and_run_ns.txt +.. include:: /includes/nRF54H20_erase_UICR.txt .. _central_uart_testing: diff --git a/samples/bluetooth/peripheral_hids_keyboard/README.rst b/samples/bluetooth/peripheral_hids_keyboard/README.rst index 729c0c007b04..4281035d64f9 100644 --- a/samples/bluetooth/peripheral_hids_keyboard/README.rst +++ b/samples/bluetooth/peripheral_hids_keyboard/README.rst @@ -140,6 +140,8 @@ Building and running .. include:: /includes/build_and_run_ns.txt +.. include:: /includes/nRF54H20_erase_UICR.txt + Testing ======= diff --git a/samples/bluetooth/peripheral_hids_mouse/README.rst b/samples/bluetooth/peripheral_hids_mouse/README.rst index b5a623f8cdda..bddb4b44e1b7 100644 --- a/samples/bluetooth/peripheral_hids_mouse/README.rst +++ b/samples/bluetooth/peripheral_hids_mouse/README.rst @@ -104,6 +104,8 @@ To build this sample with the :ref:`nrf_rpc_ipc_readme` library on the nRF5340 D .. include:: /includes/build_and_run_ns.txt +.. include:: /includes/nRF54H20_erase_UICR.txt + Testing ======= diff --git a/samples/bluetooth/peripheral_lbs/README.rst b/samples/bluetooth/peripheral_lbs/README.rst index 5e706e651658..a85f3bf70631 100644 --- a/samples/bluetooth/peripheral_lbs/README.rst +++ b/samples/bluetooth/peripheral_lbs/README.rst @@ -119,6 +119,8 @@ Building and running .. include:: /includes/build_and_run_ns.txt +.. include:: /includes/nRF54H20_erase_UICR.txt + Minimal build ============= diff --git a/samples/bluetooth/peripheral_rscs/README.rst b/samples/bluetooth/peripheral_rscs/README.rst index d62f49a8b843..3b9f02f95356 100644 --- a/samples/bluetooth/peripheral_rscs/README.rst +++ b/samples/bluetooth/peripheral_rscs/README.rst @@ -55,6 +55,8 @@ Building and running .. include:: /includes/build_and_run_ns.txt +.. include:: /includes/nRF54H20_erase_UICR.txt + .. _peripheral_rscs_testing: Testing diff --git a/samples/bluetooth/peripheral_uart/README.rst b/samples/bluetooth/peripheral_uart/README.rst index 975a8c670234..12b80dc75526 100644 --- a/samples/bluetooth/peripheral_uart/README.rst +++ b/samples/bluetooth/peripheral_uart/README.rst @@ -176,6 +176,8 @@ Building and running .. include:: /includes/build_and_run_ns.txt +.. include:: /includes/nRF54H20_erase_UICR.txt + .. _peripheral_uart_sample_activating_variants: Experimental Bluetooth Low Energy Remote Procedure Call interface diff --git a/samples/bluetooth/rpc_host/README.rst b/samples/bluetooth/rpc_host/README.rst index 58235ba7a605..a445744af7bf 100644 --- a/samples/bluetooth/rpc_host/README.rst +++ b/samples/bluetooth/rpc_host/README.rst @@ -38,6 +38,8 @@ You must program this sample to the nRF5340 network core. .. include:: /includes/build_and_run.txt +.. include:: /includes/nRF54H20_erase_UICR.txt + .. _rpc_host_debug: Debug build diff --git a/samples/bluetooth/throughput/README.rst b/samples/bluetooth/throughput/README.rst index c87b876a6a3a..2df0b5c7503a 100644 --- a/samples/bluetooth/throughput/README.rst +++ b/samples/bluetooth/throughput/README.rst @@ -117,6 +117,8 @@ Building and running .. include:: /includes/build_and_run_ns.txt +.. include:: /includes/nRF54H20_erase_UICR.txt + Testing ======= diff --git a/samples/caf_sensor_manager/README.rst b/samples/caf_sensor_manager/README.rst index 9f8089ec617a..a4f270cc7de5 100644 --- a/samples/caf_sensor_manager/README.rst +++ b/samples/caf_sensor_manager/README.rst @@ -76,6 +76,8 @@ Complete the following steps to program the sample: west flash +.. include:: /includes/nRF54H20_erase_UICR.txt + Testing ======= diff --git a/samples/event_manager_proxy/README.rst b/samples/event_manager_proxy/README.rst index d4e114fab7e7..8980f8a02a64 100644 --- a/samples/event_manager_proxy/README.rst +++ b/samples/event_manager_proxy/README.rst @@ -101,6 +101,7 @@ Complete the following steps to program the sample: west flash +.. include:: /includes/nRF54H20_erase_UICR.txt Testing ======= diff --git a/samples/ipc/ipc_service/README.rst b/samples/ipc/ipc_service/README.rst index fac7209075cd..33736ec75d8a 100644 --- a/samples/ipc/ipc_service/README.rst +++ b/samples/ipc/ipc_service/README.rst @@ -109,6 +109,8 @@ To build the sample to test IPC between the application and PPR core using the : west build -p -b nrf54h20dk/nrf54h20/cpuapp -T sample.ipc.ipc_service.nrf54h20dk_cpuapp_cpuppr_icmsg . +.. include:: /includes/nRF54H20_erase_UICR.txt + Testing ======= diff --git a/samples/matter/lock/README.rst b/samples/matter/lock/README.rst index d08f2f50698d..f31507eba8e3 100644 --- a/samples/matter/lock/README.rst +++ b/samples/matter/lock/README.rst @@ -126,7 +126,7 @@ You can program a portion of the application code related to the nRF70 Series' W This option is available only when building for the nRF5340 DK with the nRF7002 EK shield attached. To prepare an application to use this feature, you need to create additional MCUboot partitions. To learn how to configure MCUboot partitions, see the :ref:`nrf70_fw_patch_update_adding_partitions` guide. -To enable this feature for Matter, set the :kconfig:option:`SB_CONFIG_WIFI_PATCHES_EXT_FLASH_STORE`, :kconfig:option:`SB_CONFIG_DFU_MULTI_IMAGE_PACKAGE_WIFI_FW_PATCH` Kconfig options to ``y``, and set the :kconfig:option:`SB_CONFIG_MCUBOOT_UPDATEABLE_IMAGES` Kconfig option to ``3``. +To enable this feature for Matter, set the ``SB_CONFIG_WIFI_PATCHES_EXT_FLASH_STORE``, ``SB_CONFIG_DFU_MULTI_IMAGE_PACKAGE_WIFI_FW_PATCH`` Kconfig options to ``y``, and set the ``SB_CONFIG_MCUBOOT_UPDATEABLE_IMAGES`` Kconfig option to ``3``. .. matter_door_lock_sample_nrf70_firmware_patch_end @@ -329,7 +329,7 @@ This means that a new factory data set will be automatically generated when buil To disable factory data support, set the following Kconfig options to ``n``: * :kconfig:option:`CONFIG_CHIP_FACTORY_DATA` - * :kconfig:option:`SB_CONFIG_MATTER_FACTORY_DATA_GENERATE` + * ``SB_CONFIG_MATTER_FACTORY_DATA_GENERATE`` To learn more about factory data, read the :doc:`matter:nrfconnect_factory_data_configuration` page in the Matter documentation. diff --git a/samples/nfc/record_launch_app/README.rst b/samples/nfc/record_launch_app/README.rst index d21adfac3f7a..2bb635852a24 100644 --- a/samples/nfc/record_launch_app/README.rst +++ b/samples/nfc/record_launch_app/README.rst @@ -52,6 +52,8 @@ Building and running .. include:: /includes/build_and_run_ns.txt +.. include:: /includes/nRF54H20_erase_UICR.txt + .. note:: |nfc_nfct_driver_note| diff --git a/samples/nfc/record_text/README.rst b/samples/nfc/record_text/README.rst index a2b44b1908c2..fe996e40aa5c 100644 --- a/samples/nfc/record_text/README.rst +++ b/samples/nfc/record_text/README.rst @@ -52,6 +52,8 @@ Building and running .. include:: /includes/build_and_run_ns.txt +.. include:: /includes/nRF54H20_erase_UICR.txt + .. note:: |nfc_nfct_driver_note| diff --git a/samples/nfc/shell/README.rst b/samples/nfc/shell/README.rst index b06ccb7a4012..1ab65d4c6d34 100644 --- a/samples/nfc/shell/README.rst +++ b/samples/nfc/shell/README.rst @@ -73,6 +73,8 @@ Building and running .. include:: /includes/build_and_run.txt +.. include:: /includes/nRF54H20_erase_UICR.txt + .. note:: |nfc_nfct_driver_note| diff --git a/samples/nfc/system_off/README.rst b/samples/nfc/system_off/README.rst index a15a9d92e989..fab4534d6a58 100644 --- a/samples/nfc/system_off/README.rst +++ b/samples/nfc/system_off/README.rst @@ -83,6 +83,8 @@ Building and running .. include:: /includes/build_and_run_ns.txt +.. include:: /includes/nRF54H20_erase_UICR.txt + .. note:: |nfc_nfct_driver_note| diff --git a/samples/nfc/writable_ndef_msg/README.rst b/samples/nfc/writable_ndef_msg/README.rst index 46cb6102730f..264b54e87cf5 100644 --- a/samples/nfc/writable_ndef_msg/README.rst +++ b/samples/nfc/writable_ndef_msg/README.rst @@ -68,6 +68,8 @@ Building and running .. include:: /includes/build_and_run_ns.txt +.. include:: /includes/nRF54H20_erase_UICR.txt + .. note:: |nfc_nfct_driver_note| diff --git a/samples/peripheral/radio_test/README.rst b/samples/peripheral/radio_test/README.rst index 71629e7a36f8..f0bf53db6791 100644 --- a/samples/peripheral/radio_test/README.rst +++ b/samples/peripheral/radio_test/README.rst @@ -215,6 +215,8 @@ You can use the following command: west build samples/peripheral/radio_test -b nrf5340dk/nrf5340/cpunet -- -DSHIELD=nrf21540ek -DFILE_SUFFIX=usb +.. include:: /includes/nRF54H20_erase_UICR.txt + .. note:: You can also build the sample with the remote IPC Service Shell for the |nRF7002DKnoref| using the ``nrf7002dk/nrf5340/cpunet`` board target in the commands. diff --git a/samples/suit/flash_companion/README.rst b/samples/suit/flash_companion/README.rst index 9ee4ac6040bc..3cdbb1e8d46d 100644 --- a/samples/suit/flash_companion/README.rst +++ b/samples/suit/flash_companion/README.rst @@ -42,7 +42,7 @@ Configuration Setup ===== -You can build the sample using :ref:`sysbuild ` by enabling the :kconfig:option:`SB_CONFIG_SUIT_BUILD_FLASH_COMPANION` Kconfig option. +You can build the sample using :ref:`sysbuild ` by enabling the ``SB_CONFIG_SUIT_BUILD_FLASH_COMPANION`` Kconfig option. The memory partition from which the firmware will run can be configured by providing a devicetree overlay through sysbuild. You should create a dedicated partition in non-volatile memory and override the ``zephyr,code-partition``. The memory partition must not be used by any other firmware image. @@ -71,7 +71,7 @@ Make sure that both the main application and the flash companion support your ta Perform the following steps in the main application directory: -1. Enable the :kconfig:option:`SB_CONFIG_SUIT_BUILD_FLASH_COMPANION` sysbuild option. +1. Enable the ``SB_CONFIG_SUIT_BUILD_FLASH_COMPANION`` sysbuild option. #. Create :file:`sysbuild/flash_companion.overlay` devicetree overlay file and add the following content: