diff --git a/doc/nrf/config_and_build/bootloaders/bootloader_adding.rst b/doc/nrf/config_and_build/bootloaders/bootloader_adding.rst index 0c04bcbc9a44..33dbfd93afa0 100644 --- a/doc/nrf/config_and_build/bootloaders/bootloader_adding.rst +++ b/doc/nrf/config_and_build/bootloaders/bootloader_adding.rst @@ -1,7 +1,11 @@ .. _ug_bootloader_adding: -Adding a bootloader chain -######################### +Adding a bootloader chain using child and parent images +####################################################### + +.. note:: + This feature is now deprecated. + See :ref:`ug_bootloader_adding_sysbuild`. .. contents:: :local: diff --git a/doc/nrf/config_and_build/bootloaders/bootloader_adding_sysbuild.rst b/doc/nrf/config_and_build/bootloaders/bootloader_adding_sysbuild.rst new file mode 100644 index 000000000000..89023b530d09 --- /dev/null +++ b/doc/nrf/config_and_build/bootloaders/bootloader_adding_sysbuild.rst @@ -0,0 +1,449 @@ +.. _ug_bootloader_adding_sysbuild: + +Adding a bootloader chain using sysbuild +######################################## + +.. contents:: + :local: + :depth: 2 + +You can add a bootloader chain to an application in the following ways: + +* Permanently: + + * Using :file:`sysbuild.conf` sysbuild Kconfig project configuration files. + +* Temporarily (for a single build): + + * Using :ref:`one-time CMake arguments `. + * Using ``sysbuild_menuconfig``. + + +While you can use temporary configurations for quickly experimenting with different configurations from build to build, the recommended method is to implement your bootloader chain with permanent configurations. + +You can add bootloader chains to nearly any sample in |NCS| or Zephyr for rapid testing and experimentation. + +Choose the bootloader type depending on your application needs. +For detailed information about the bootloader support in the |NCS| and the general architecture, see :ref:`ug_bootloader`. + +.. _ug_bootloader_adding_sysbuild_immutable: + +Adding an immutable bootloader +****************************** + +The following sections describe how to add either |NSIB| or MCUboot as an immutable bootloader. + +.. _ug_bootloader_adding_sysbuild_immutable_b0: + +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: + +.. code-block:: console + + west build -b nrf52840dk/nrf52840 zephyr/samples/hello_world -- -DSB_CONFIG_SECURE_BOOT_APPCORE=y + +|how_to_configure| + +Like other images, :ref:`image-specific configurations ` can be assigned at build time to further customize the bootloader's functionality. + +To ensure that the immutable bootloader occupies as little flash memory as possible, you can also apply the :file:`prj_minimal.conf` configuration: + +.. code-block:: console + + west build -b nrf52840dk/nrf52840 zephyr/samples/hello_world -- \ + -DSB_CONFIG_SECURE_BOOT_APPCORE=y \ + -Db0_FILE_SUFFIX=minimal + +See :ref:`ug_bootloader_config` for more information about using Kconfig fragments. + +Configuring |NSIB| as an immutable bootloader +--------------------------------------------- + +The following sections describe different configuration options available for |NSIB| as an immutable bootloader. + +.. _ug_bootloader_adding_sysbuild_immutable_keys: + +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: + +.. tabs:: + + .. group-tab:: Kconfig / sysbuild.conf + + .. code-block:: console + + SB_CONFIG_SECURE_BOOT_SIGNING_KEY_FILE="/priv.pem" + + .. group-tab:: Command line + + .. code-block:: console + + -DSB_CONFIG_SECURE_BOOT_SIGNING_KEY_FILE=\"/priv.pem\" + + Escaped quotations avoid malformed-string warnings from Kconfig. + +This option only accepts the private key of an ECDSA key pair, as the build system scripts automatically extract the public key at build time. + +The file argument must be a string and is specified in one of the following ways: + +* The relative path to the 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 the file. + +For example, if a directory named :file:`_keys` located in :file:`/home/user/ncs` contains signing keys, you can provide the path in the following ways: + +.. tabs:: + + .. group-tab:: Kconfig / sysbuild.conf + + .. code-block:: console + + SB_CONFIG_SECURE_BOOT_SIGNING_KEY_FILE="../../_keys/priv.pem" + + Or + + .. code-block:: console + + SB_CONFIG_SECURE_BOOT_SIGNING_KEY_FILE="/home/user/ncs/_keys/priv.pem" + + .. group-tab:: Command line + + .. code-block:: console + + -DSB_CONFIG_SECURE_BOOT_SIGNING_KEY_FILE=\"../../_keys/priv.pem\" + + Or + + .. code-block:: console + + -DSB_CONFIG_SECURE_BOOT_SIGNING_KEY_FILE=\"/home/user/ncs/_keys/priv.pem\" + + Or, if you set an environment variable named :envvar:`NCS` to :file:`/home/user/ncs`: + + .. code-block:: console + + -DSB_CONFIG_SECURE_BOOT_SIGNING_KEY_FILE=\"$NCS/_keys/priv.pem\" + +.. note:: + + The public key string must be a list of files in the following ways: + + * 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. + + 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. + +You can find specific configuration options for keys with this bootloader in :file:`nrf/sysbuild/Kconfig.secureboot`. + +See :ref:`ug_fw_update_keys` for information on how to generate custom keys for a project. + +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. + +The OpenSSL method is handled internally by the build system, whereas using custom commands requires more configuration steps. + +Checking the public key +^^^^^^^^^^^^^^^^^^^^^^^ + +You can check that the bootloader image is correctly compiled with the custom signing key by comparing its auto-generated public key against a manual public key dump using OpenSSL. +You can do this with ``diff``, running the following command from a terminal: + +.. code-block:: console + + diff build/zephyr/nrf/subsys/bootloader/generated/public.pem <(openssl ec -in priv.pem -pubout) + +If there is no file diff output, then the private key has been successfully included in the bootloader image. + +.. _ug_bootloader_adding_sysbuild_immutable_b0_custom_signing: + +Custom signing commands +~~~~~~~~~~~~~~~~~~~~~~~ + +If you want complete control over the key handling of a project, you can use a custom signing command with |NSIB|. +Using a custom signing command removes the need to use of a private key from the build system. +This is useful when the private keys are stored, managed, or otherwise processed through a *hardware security module* (`HSM`_) or an in-house tool. + +To use a custom signing command with this bootloader, set the following options in the application's :file:`sysbuild.conf` file or using the command line: + +.. tabs:: + + .. group-tab:: Kconfig / sysbuild.conf + + .. code-block:: console + + SB_CONFIG_SECURE_BOOT_APPCORE=y + SB_CONFIG_SECURE_BOOT_SIGNING_CUSTOM=y + SB_CONFIG_SECURE_BOOT_SIGNING_PUBLIC_KEY="/path/to/pub.pem" + SB_CONFIG_SECURE_BOOT_SIGNING_COMMAND="my_command" + + .. group-tab:: Command line + + .. code-block:: console + + west build -b nrf52840dk/nrf52840 zephyr/samples/hello_world -- \ + -DSB_CONFIG_SECURE_BOOT_APPCORE=y \ + -DSB_CONFIG_SECURE_BOOT_SIGNING_CUSTOM=y \ + -DSB_CONFIG_SECURE_BOOT_SIGNING_PUBLIC_KEY=\"/path/to/pub.pem\" \ + -DSB_CONFIG_SECURE_BOOT_SIGNING_COMMAND=\"my_command\" + + Escaped quotations avoid malformed-string warnings from Kconfig. + +.. note:: + + 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. + +See :kconfig:option:`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:: + :class: highlight + + 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. + +.. 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. + +.. _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: + +.. code-block:: console + + west build -b nrf52840dk/nrf52840 zephyr/samples/hello_world -- -DSB_CONFIG_BOOTLOADER_MCUBOOT=y + +|how_to_configure| +Like other images, you can assign :ref:`image-specific configurations ` at build time to further customize the bootloader's functionality. + +Configuring MCUboot as an immutable bootloader +---------------------------------------------- + +The following sections describe different configuration options available for MCUboot as an immutable bootloader. + +.. _ug_bootloader_adding_sysbuild_immutable_mcuboot_keys: + +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 set the option in :file:`sysbuild.conf` or using the command line: + +.. tabs:: + + .. group-tab:: Kconfig / sysbuild.conf + + .. code-block:: console + + SB_CONFIG_BOOT_SIGNATURE_KEY_FILE="priv.pem" + + .. group-tab:: Command line + + .. code-block:: console + + -DSB_CONFIG_BOOT_SIGNATURE_KEY_FILE=\"priv.pem\" + + Escaped quotations avoid malformed-string warnings from Kconfig. + +The path of the key must be an absolute path, though ``${APPLICATION_CONFIG_DIR}`` can be used to get the path of the application configuration directory to use keys relative to this directory. + +See :ref:`ug_fw_update_keys` for information on how to generate custom keys for a project. + +The key type must also be set correctly: + +.. code-block:: console + + west build -b nrf52840dk/nrf52840 zephyr/samples/hello_world -- \ + -DSB_CONFIG_BOOTLOADER_MCUBOOT=y \ + -DSB_CONFIG_BOOT_SIGNATURE_KEY_FILE=\"${APPLICATION_CONFIG_DIR}/../../priv-ecdsa256.pem\" \ + -DSB_CONFIG_BOOT_SIGNATURE_TYPE_ECDSA_P256=y + +You can find specific configuration options for keys with this bootloader in :file:`zephyr/share/sysbuild/images/bootloader/Kconfig`. + +Checking the public key +^^^^^^^^^^^^^^^^^^^^^^^ + +You can extract the public key locally and compare it against MCUboot's auto-generated file to verify that it is using the custom key: + +.. code-block:: console + + diff build/mcuboot/zephyr/autogen-pubkey.c <(python3 bootloader/mcuboot/scripts/imgtool.py getpub -k priv.pem) + +If there is no file diff output, then the private key was successfully included with the bootloader image. + +.. _ug_bootloader_adding_sysbuild_upgradable: + +Adding an upgradable bootloader +******************************* + +MCUboot is the only upgradable bootloader currently available for the |NCS|. +The following section describes how to add it to your secure bootloader chain. + +.. _ug_bootloader_adding_sysbuild_upgradable_mcuboot: + +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: + + .. code-block:: + + west build -b nrf52840dk/nrf52840 zephyr/samples/hello_world -- \ + -DSB_CONFIG_SECURE_BOOT_APPCORE=y \ + -DSB_CONFIG_BOOTLOADER_MCUBOOT=y + + |how_to_configure| + +#. Optionally, you can configure MCUboot to use the cryptographic functionality exposed by the immutable bootloader and reduce the flash memory usage for MCUboot to less than 16 kB. + To enable this configuration, apply both the :file:`prj_minimal.conf` Kconfig project file and the :file:`external_crypto.conf` Kconfig fragment for the MCUboot image: + + .. code-block:: + + west build -b nrf52840dk/nrf52840 zephyr/samples/hello_world -- \ + -DSB_CONFIG_SECURE_BOOT_APPCORE=y \ + -DSB_CONFIG_BOOTLOADER_MCUBOOT=y \ + -Dmcuboot_FILE_SUFFIX=minimal \ + -Dmcuboot_EXTRA_CONF_FILE=external_crypto.conf + + See :ref:`ug_bootloader_config` for more information about using Kconfig fragments with bootloaders. + +The build process generates several :ref:`app_build_output_files`, including :ref:`app_build_mcuboot_output`. + +Configuring MCUboot as an upgradable bootloader +----------------------------------------------- + +The following sections describe different configuration options available for MCUboot as an upgradable bootloader. + +Adding a custom signature key file +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The process to use specific signature keys with MCUboot used as the upgradable bootloader is the same as when it is used :ref:`as the immutable one `. + +.. note:: + + Since each bootloader is built with its own signature key, using a different private key with an upgradable bootloader will not cause problems with the secure boot chain. + You can also use the same private key for both the immutable and upgradable bootloaders, as long as the key type is supported by both of them. + +.. _ug_bootloader_adding_sysbuild_presigned_variants: + +Generating pre-signed variants +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The S1 variant is built as a separate image called ``s1_image`` automatically. +This variant image will use the same application configuration as the base image, with the exception of its placement in memory. +You only have to modify the version set in the :kconfig:option:`CONFIG_FW_INFO_FIRMWARE_VERSION` Kconfig option. +To make ``s1_image`` bootable with |NSIB|, the value of :kconfig:option:`CONFIG_FW_INFO_FIRMWARE_VERSION` for the default image (or MCUboot if using MCUboot as a second-stage bootloader) must be bigger than the one for original image. + +Using MCUboot in firmware loader mode +************************************** + +MCUboot supports a firmware loader mode which is supported in sysbuild. This mode allows for a project to consist of an MCUboot image (optionally with serial recovery), a main application which does not support firmware updates, and a secondary application which is dedicated to loading firmware updates. The benefit of this is for having a dedicated application purely for loading firmware updates e.g. over Bluetooth and allowing the size of tha main application to be smaller, helping on devices with limited flash or RAM. +In order to use this mode, a static partition file must be created for the application to designate the addresses and sizes of the main image and firmware loader applications, the firmware loader partition **must** be named ``firmware_loader``. The following is an example static partition manager file for the nRF53: + +.. code-block:: yaml + + app: + address: 0x10200 + region: flash_primary + size: 0xdfe00 + mcuboot: + address: 0x0 + region: flash_primary + size: 0x10000 + mcuboot_pad: + address: 0x10000 + region: flash_primary + size: 0x200 + mcuboot_primary: + address: 0x10000 + orig_span: &id001 + - mcuboot_pad + - app + region: flash_primary + size: 0xc0000 + span: *id001 + mcuboot_primary_app: + address: 0x10200 + orig_span: &id002 + - app + region: flash_primary + size: 0xbfe00 + span: *id002 + firmware_loader: + address: 0xd0200 + region: flash_primary + size: 0x1fe00 + mcuboot_secondary: + address: 0xd0000 + orig_span: &id003 + - mcuboot_pad + - firmware_loader + region: flash_primary + size: 0x20000 + span: *id003 + mcuboot_secondary_app: + address: 0xd0200 + orig_span: &id004 + - firmware_loader + region: flash_primary + size: 0x1fe00 + span: *id004 + settings_storage: + address: 0xf0000 + region: flash_primary + size: 0x10000 + pcd_sram: + address: 0x20000000 + size: 0x2000 + region: sram_primary + +The project must also have a ``sysbuild.cmake`` file which includes the firmware loader application in the build, this **must** be named ``firmware_loader``: + +.. code-block:: cmake + + ExternalZephyrProject_Add( + APPLICATION firmware_loader + SOURCE_DIR + ) + +There must also be a ``sysbuild.conf`` file which selects the required sysbuild options for enabling MCUboot and selecting the firmware loader mode: + +.. code-block:: cfg + + SB_CONFIG_BOOTLOADER_MCUBOOT=y + SB_CONFIG_MCUBOOT_MODE_FIRMWARE_UPDATER=y + +At least one mode must be set in MCUboot for entering the firmware loader application, supported entrance methods include: + +* GPIO +* Boot mode using retention subsystem +* No valid main application +* Device reset using dedicated reset pin + +For this example, the use of a GPIO when booting will be used. Create a ``sysbuild`` folder and add a ``sysbuild/mcuboot.conf`` Kconfig fragment file to use when building MCUboot with the following: + +.. code-block:: cfg + + CONFIG_BOOT_FIRMWARE_LOADER_ENTRANCE_GPIO=y + +The project can now be built and flashed and will boot the firmware loader application when the button is held upon device reboot, or the main application will be booted when the device is reset and the button is not held down. 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 9c2fd9eb8f14..702e6bf40769 100644 --- a/doc/nrf/config_and_build/bootloaders/bootloader_downgrade_protection.rst +++ b/doc/nrf/config_and_build/bootloaders/bootloader_downgrade_protection.rst @@ -29,10 +29,10 @@ 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 MCUboot-specific configuration options ``CONFIG_MCUBOOT_DOWNGRADE_PREVENTION`` and ``CONFIG_BOOT_UPGRADE_ONLY`` for the MCUboot image. +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. .. caution:: - Enabling ``CONFIG_BOOT_UPGRADE_ONLY`` prevents the fallback recovery of application images. + Enabling :kconfig:option:`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. You can compile your application with this feature as follows: @@ -41,10 +41,10 @@ You can compile your application with this feature as follows: :class: highlight west build -b *board_target* *application* -- \\ - -DCONFIG_BOOTLOADER_MCUBOOT=y \\ + -DSB_CONFIG_BOOTLOADER_MCUBOOT=y \\ + -DSB_CONFIG_MCUBOOT_MODE_OVERWRITE_ONLY=y \\ -DCONFIG_MCUBOOT_IMGTOOL_SIGN_VERSION=\\"0.1.2\\+3\\" \\ - -Dmcuboot_CONFIG_MCUBOOT_DOWNGRADE_PREVENTION=y \\ - -Dmcuboot_CONFIG_BOOT_UPGRADE_ONLY=y + -Dmcuboot_CONFIG_MCUBOOT_DOWNGRADE_PREVENTION=y |how_to_configure| @@ -52,8 +52,9 @@ After you upload a new image and reset the development kit, MCUboot attempts to If this image has, in order of precedence, a *major*, *minor*, or *revision* value that is lower than the primary application image, it is considered invalid and the existing primary application boots instead. .. note:: - The optional label or build number specified after the ``+`` character is ignored when evaluating the version. + By default, the optional label or build number specified after the ``+`` character is ignored when evaluating the version. For example, an existing application image with version ``0.1.2+3`` can be overwritten by an uploaded image with ``0.1.2+2``, but not by one with ``0.1.1+2``. + Checking against this field can be performed by enabling :kconfig:option:`CONFIG_BOOT_VERSION_CMP_USE_BUILD_NUMBER` in the MCUboot image .. _ug_fw_update_downgrade_protection_hw: .. _bootloader_monotonic_counter: @@ -82,27 +83,22 @@ Downgrade protection using |NSIB| .. bootloader_monotonic_counter_nsib_start -To enable anti-rollback protection with monotonic counter for |NSIB|, set the following configurations in the application (parent image): - -* :kconfig:option:`CONFIG_SB_MONOTONIC_COUNTER` -* :kconfig:option:`CONFIG_SB_NUM_VER_COUNTER_SLOTS` +To enable anti-rollback protection with monotonic counter for |NSIB|, set the following configurations in the ``b0`` image: :kconfig:option:`CONFIG_SB_MONOTONIC_COUNTER` and :kconfig:option:`CONFIG_SB_NUM_VER_COUNTER_SLOTS` 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. .. bootloader_monotonic_counter_nsib_end -To set options for child images, see the :ref:`ug_multi_image_variables` section. +To set options for other images, see :ref:`zephyr:sysbuild_kconfig_namespacing`. .. _ug_fw_update_hw_downgrade_mcuboot: Downgrade protection using MCUboot ================================== -To enable anti-rollback protection with monotonic counter for MCUboot, set the following configurations in the application (parent image): - -* :kconfig:option:`CONFIG_MCUBOOT_HARDWARE_DOWNGRADE_PREVENTION` -* :kconfig:option:`CONFIG_MCUBOOT_HW_DOWNGRADE_PREVENTION_COUNTER_SLOTS` -* :kconfig:option:`CONFIG_MCUBOOT_HW_DOWNGRADE_PREVENTION_COUNTER_VALUE` +To enable anti-rollback protection with monotonic counter for MCUboot, set the following configurations using sysbuild: -To set options for child images, see the :ref:`ug_multi_image_variables` section. +* :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` diff --git a/doc/nrf/config_and_build/bootloaders/index.rst b/doc/nrf/config_and_build/bootloaders/index.rst index 6698df0e53eb..504682bbd7ed 100644 --- a/doc/nrf/config_and_build/bootloaders/index.rst +++ b/doc/nrf/config_and_build/bootloaders/index.rst @@ -65,6 +65,7 @@ See the following user guides to learn more: bootloader bootloader_adding + bootloader_adding_sysbuild bootloader_testing bootloader_external_flash bootloader_config diff --git a/doc/nrf/config_and_build/configuring_app/index.rst b/doc/nrf/config_and_build/configuring_app/index.rst index 288512d51d32..c518a6680e4e 100644 --- a/doc/nrf/config_and_build/configuring_app/index.rst +++ b/doc/nrf/config_and_build/configuring_app/index.rst @@ -76,5 +76,8 @@ Just as for creating the application, you can build the application using either kconfig/index advanced_building output_build_files + sysbuild_images + zephyr_samples_sysbuild + sysbuild_forced_options .. |output_files_note| replace:: For more information about files generated as output of the build process, see :ref:`app_build_output_files`. 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 b4fa584afc39..12763fd3ce5c 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 @@ -18,7 +18,7 @@ When an ELF file is converted to another format, such as HEX or binary, the symb Depending on the application and the SoC, you can use one or several images. -The |NCS| build system places output images in the :file:`/zephyr` folder. +The |NCS| build system places output images in the :file:`` folder when using sysbuild. .. _app_build_output_files_common: @@ -28,66 +28,57 @@ Common output build files The following table lists build files that can be generated as output when building firmware for supported :ref:`board targets `. The table includes files for single-core and multi-core programming scenarios for both |VSC| and command-line building methods. Which files you are going to use depends on the application configuration and not directly on the type of SoC you are using. -The following scenarios are possible: - -* Single-image - Only one firmware image file is generated for a single core. -* Multi-image - Two or more firmware image files are generated for a single core. - For more details about this scenario, see :ref:`ug_multi_image`. -* Multi-core - Two or more firmware image files are generated for two or more cores. - -+------------------------------------------+-------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ -| File | Description | Programming scenario | -+==========================================+=======================================================================================================+===========================================================================================================+ -| :file:`zephyr.hex` | Default full image. | * Programming board targets with :ref:`NSPE ` or single-image. | -| | In a multi-image build, several :file:`zephyr.hex` files are generated, one for each image. | * Testing DFU procedure with nrfjprog (programming directly to device). | -+------------------------------------------+-------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ -| :file:`merged.hex` | The result of merging all :file:`zephyr.hex` files for all images for a core | * Programming multi-core application. | -| | in a multi-image build. Used by Nordic Semiconductor's board targets in single-core | * Testing DFU procedure with nrfjprog (programming directly to device). | -| | multi-image builds. In multi-core builds, several :file:`merged_.hex` fields | | -| | are generated, where ** indicates the core. | | -+------------------------------------------+-------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ -| :file:`merged_domains.hex` | The result of merging all :file:`merged.hex` files for all cores or processing environments | * Programming :ref:`SPE-only ` and multi-core board targets. | -| | (:file:`merged.hex` for the application core and :file:`merged.hex` or :file:`zephyr.hex` | * Testing DFU procedure with nrfjprog (programming directly to device). | -| | for the network core). | | -+------------------------------------------+-------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ -| :file:`tfm_s.hex` | Secure firmware image created by the TF-M build system in the background of the Zephyr build. | Programming :ref:`SPE-only ` and multi-core board targets. | -| | It is used together with the :file:`zephyr.hex` file, which is intended for the Non-Secure | | -| | Processing Environment (NSPE). Located in :file:`build/tfm/bin`. | | -+------------------------------------------+-------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ -| :file:`app_update.bin` | Application core update file used to create :file:`dfu_application.zip` for multi-core DFU. | DFU process for single-image board targets and the application core | -| | Can also be used standalone for a single-image DFU. | of the multi-core board targets. | -| | Contains the signed version of the application. | | -| | This file is transferred in the real-life update procedure, as opposed to HEX files | | -| | that are transferred with nrfjprog when emulating an update procedure. | | -| | :ref:`Compatible with MCUboot `. | | -+------------------------------------------+-------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ -| :file:`app_signed.hex` | HEX file variant of the :file:`app_update.bin` file. | Programming single-image board targets and the application core | -| | Can also be used standalone for a single-image DFU. | of the multi-core board targets. | -| | Contains the signed version of the application. | | -| | :ref:`Compatible with MCUboot `. | | -+------------------------------------------+-------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ -| :file:`mcuboot_secondary_app_update.bin` | Secondary slot variant of the :file:`app_update.bin` file. | DFU process for single-core board targets. | -| | :ref:`Compatible with MCUboot ` in the :doc:`direct-xip mode `. | | -+------------------------------------------+-------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ -| :file:`mcuboot_secondary_app_signed.hex` | Secondary slot variant of the :file:`app_signed.hex` file. | Programming single-core board targets. | -| | :ref:`Compatible with MCUboot ` in the :doc:`direct-xip mode `. | | -+------------------------------------------+-------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ -| :file:`net_core_app_update.bin` | Network core update file used to create :file:`dfu_application.zip`. | DFU process for the network core of multi-core board targets. | -| | This file is transferred in the real-life update procedure, as opposed to HEX files | | -| | that are transferred with nrfjprog when emulating an update procedure. | | -+------------------------------------------+-------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ -| :file:`dfu_application.zip` | Zip file containing both the MCUboot-compatible update image for one or more cores | DFU process for both single-core and multi-core applications. | -| | and a manifest describing its contents. | | -+------------------------------------------+-------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ -| :file:`matter.ota` | :ref:`ug_matter`-specific OTA image that contains a Matter-compliant header | DFU over Matter for both single-core and multi-core applications. | -| | and a DFU multi-image package that bundles user-selected firmware images. | | -+------------------------------------------+-------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ -| :file:`.zigbee` | :ref:`ug_zigbee`-specific OTA image that contains the Zigbee application | DFU over Zigbee for both single-core and multi-core applications | -| | with the Zigbee OTA header used for providing information about the image to the OTA server. | in the |NCS| v2.0.0 and later. | -| | The ** includes manufacturer's code, image type, file version, and comment | | -| | (customizable by user, sample name by default). | | -| | For example: :file:`127F-0141-01020003-light_switch.zigbee`. | | -+------------------------------------------+-------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ + ++--------------------------------------+--------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+ +| File | Description | Programming scenario | ++======================================+========================================================================================================+=====================================================================================+ +| :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`. | | ++--------------------------------------+--------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+ +| :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). | +| | are generated, where ** indicates the CPU core. | | ++--------------------------------------+--------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+ +| :file:`tfm_s.hex` | Secure firmware image created by the TF-M build system in the background of the Zephyr build. | Programming :ref:`SPE-only ` and multi-core board targets. | +| | It is used together with the :file:`zephyr.hex` file, which is intended for the Non-Secure | | +| | Processing Environment (NSPE). Located in :file:`build/tfm/bin`. | | ++--------------------------------------+--------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+ +| :file:`zephyr.signed.bin` | Image update file used to create :file:`dfu_application.zip` for multi-core DFU. | DFU process for single or multi-core board targets | +| | Can also be used standalone for a single-image DFU. | | +| | Contains the signed version of the application. | | +| | This file is transferred in the real-life update procedure, as opposed to HEX files | | +| | 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`. | | ++--------------------------------------+--------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+ +| :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`. | | ++--------------------------------------+--------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+ +| :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 `. | | +| | ``zephyr`` is the value of :kconfig:option:`CONFIG_KERNEL_BIN_NAME`. | | ++--------------------------------------+--------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+ +| :file:`zephyr.signed.hex` in | Secondary slot variant of the :file:`zephyr.signed.hex` file. | Programming single-core board targets. | +| :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. | +| | 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`. | | ++--------------------------------------+--------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+ +| :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. | +| | The ** includes manufacturer's code, image type, file version, and comment | | +| | (customizable by user, sample name by default). | | +| | For example: :file:`127F-0141-01020003-light_switch.zigbee`. | | ++--------------------------------------+--------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+ .. _app_build_mcuboot_output: @@ -95,62 +86,46 @@ MCUboot output build files ************************** .. note:: - MCUboot's :doc:`direct-xip mode ` and the related :kconfig:option:`CONFIG_BOOT_BUILD_DIRECT_XIP_VARIANT` Kconfig option are currently supported only on the single-core devices such as the nRF52 Series. + 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. For more details, see the :ref:`more information ` section of the :ref:`ug_nrf52_developing` page. -+------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| File | Description | -+==================================================================+==========================================================================================================================================================================================================================================================================================+ -| :file:`dfu_application.zip` | Contains the following: | -| | | -| | * 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 (``MCUBOOT_IMGTOOL_SIGN_VERSION``), :ref:`bootloader` (NSIB) version number (``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:`CONFIG_SECURE_BOOT` and :kconfig:option:`CONFIG_BUILD_S1_VARIANT` are set. | -+------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :file:`app_update.bin` | Signed variant of the firmware in binary format (as opposed to HEX). | -| | It can be uploaded to a server as a FOTA image. | -+------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :file:`signed_by_mcuboot_and_b0_s0_image_update.bin` | MCUboot update image for s0 signed by both MCUboot and NSIB. | -| | The MCUboot signature is used by MCUboot to verify the integrity of the image before swapping and the NSIB signature is used by NSIB before booting the image. | -+------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :file:`signed_by_mcuboot_and_b0_s1_image_update.bin` | MCUboot update image for s1 signed by both MCUboot and NSIB. | -| | The MCUboot signature is used by MCUboot to verify the integrity of the image before swapping and the NSIB signature is used by NSIB before booting the image. | -+------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :file:`app_to_sign.bin` | Unsigned variant of the firmware in binary format. | -+------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :file:`app_signed.hex` | Signed variant of the firmware in the HEX format. | -| | This HEX file is linked to the same address as the application. | -| | Programming this file to the device will overwrite the existing application. | -| | It will not trigger a DFU procedure. | -+------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :file:`app_test_update.hex` | Same as :file:`app_signed.hex` except that it contains metadata that instructs MCUboot to test this firmware upon boot. | -| | As :file:`app_signed.hex`, this HEX file is linked against the same address as the application. | -| | Programming this file to the device will overwrite the existing application. | -| | It will not trigger a DFU procedure. | -+------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :file:`app_moved_test_update.hex` | Same as :file:`app_test_update.hex` except that it is linked to the address used to store the upgrade candidates. | -| | When this file is programmed to the device, MCUboot will trigger the DFU procedure upon reboot. | -+------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :file:`signed_by_mcuboot_and_b0_s0_image_moved_test_update.hex` | Moved to MCUboot secondary slot address space. | -+------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :file:`signed_by_mcuboot_and_b0_s0_image_test_update.hex` | Directly overwrites s0. | -+------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :file:`mcuboot_secondary_app_update.bin` | Secondary slot variant of the :file:`app_update.bin` file intended for use when MCUboot is in the :doc:`direct-xip mode `. | -| | Created when the :kconfig:option:`CONFIG_BOOT_BUILD_DIRECT_XIP_VARIANT` Kconfig option is enabled. | -+------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :file:`mcuboot_secondary_app_signed.hex` | Secondary slot variant of the :file:`app_signed.hex` file intended for use when MCUboot is in the :doc:`direct-xip mode `. | -| | Created when the :kconfig:option:`CONFIG_BOOT_BUILD_DIRECT_XIP_VARIANT` Kconfig option is enabled. | -+------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :file:`mcuboot_secondary_app_test_update.hex` | Secondary slot variant of the :file:`app_test_update.hex` file intended for use when MCUboot is in the :doc:`direct-xip mode `. | -| | Created when the :kconfig:option:`CONFIG_BOOT_BUILD_DIRECT_XIP_VARIANT` Kconfig option is enabled. | -+------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :file:`mcuboot_secondary_app_to_sign.bin` | Secondary slot variant of the :file:`app_to_sign.bin` file intended for use when MCUboot is in the :doc:`direct-xip mode `. | -| | Created when the :kconfig:option:`CONFIG_BOOT_BUILD_DIRECT_XIP_VARIANT` Kconfig option is enabled. | -+------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ ++-----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| File | Description | ++===============================================+===================================================================================================================================================================================================================================================+ +| :file:`dfu_application.zip` | Contains the following: | +| | | +| | * 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`), | +| | :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. | ++-----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :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. | +| | ``zephyr`` is the value of :kconfig:option:`CONFIG_KERNEL_BIN_NAME`. | ++-----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :file:`signed_by_mcuboot_and_b0_mcuboot.bin` | MCUboot update image for s0 signed by both MCUboot and NSIB. | +| | The MCUboot signature is used by MCUboot to verify the integrity of the image before swapping and the NSIB signature is used by NSIB before booting the image. | ++-----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :file:`signed_by_mcuboot_and_b0_s1_image.bin` | MCUboot update image for s1 signed by both MCUboot and NSIB. | +| | The MCUboot signature is used by MCUboot to verify the integrity of the image before swapping and the NSIB signature is used by NSIB before booting the image. | ++-----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :file:`zephyr.signed.hex` | Signed variant of the firmware in the HEX format. | +| | This HEX file is linked to the same address as the application. | +| | Programming this file to the device will overwrite the existing application. | +| | It will not trigger a DFU procedure. | +| | ``zephyr`` is the value of :kconfig:option:`CONFIG_KERNEL_BIN_NAME`. | ++-----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :file:`zephyr.signed.bin` in | Secondary slot variant of the :file:`app_update.bin` file intended for use when MCUboot is in the :doc:`direct-xip mode `. | +| :file:`mcuboot_secondary_app` folder | Created when the :kconfig:option:`CONFIG_BOOT_BUILD_DIRECT_XIP_VARIANT` Kconfig option is enabled. | +| | ``zephyr`` is the value of :kconfig:option:`CONFIG_KERNEL_BIN_NAME`. | ++-----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :file:`zephyr.signed.hex` | Secondary slot variant of the :file:`app_signed.hex` file intended for use when MCUboot is in the :doc:`direct-xip mode `. | +| :file:`mcuboot_secondary_app` folder | Created when the :kconfig:option:`CONFIG_BOOT_BUILD_DIRECT_XIP_VARIANT` Kconfig option is enabled. | +| | ``zephyr`` is the value of :kconfig:option:`CONFIG_KERNEL_BIN_NAME`. | ++-----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. _app_build_output_files_suit_dfu: @@ -199,7 +174,7 @@ The following table lists secondary build files that can be generated when build | | such as firmware images for different cores. | | | Used for DFU purposes by :ref:`ug_matter` and :ref:`ug_zigbee` protocols. | +-----------------------------------+------------------------------------------------------------------------------------------------------+ -| :file:`signed_by_b0_s0_image.bin` | Intermediate file only signed by NSIB. | +| :file:`signed_by_b0_mcuboot.bin` | Intermediate file only signed by NSIB. | +-----------------------------------+------------------------------------------------------------------------------------------------------+ | :file:`signed_by_b0_s1_image.bin` | Intermediate file only signed by NSIB. | +-----------------------------------+------------------------------------------------------------------------------------------------------+ 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 new file mode 100644 index 000000000000..fc0442fb1a4f --- /dev/null +++ b/doc/nrf/config_and_build/configuring_app/sysbuild_forced_options.rst @@ -0,0 +1,106 @@ +.. _sysbuild_forced_options: + +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 | ++-------------------------------------------------------------------------+---------------------------------------------------------------------------+----------------------+ diff --git a/doc/nrf/config_and_build/configuring_app/sysbuild_images.rst b/doc/nrf/config_and_build/configuring_app/sysbuild_images.rst new file mode 100644 index 000000000000..fcb90605a180 --- /dev/null +++ b/doc/nrf/config_and_build/configuring_app/sysbuild_images.rst @@ -0,0 +1,229 @@ +.. _sysbuild_images: + +Sysbuild images +############### + +Enabling images +=============== + +Sysbuild allows you to add additional images to a build by modifying 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. +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) | ++-------------------------------------------------+-----------------------------------------------------------------------------------------+ +| :kconfig:option:`SB_CONFIG_BOOTLOADER_MCUBOOT` | Build MCUboot image | ++-------------------------------------------------+-----------------------------------------------------------------------------------------+ + +The following sysbuild Kconfig options are also available for nRF53-based devices. +These options determine whether the secure boot image is included on the network core and specify the image for the network core: + ++---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| Sysbuild Kconfig option | Description | ++=========================================================+===========================================================================================================+ +| :kconfig:option:`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` | ++---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| :kconfig:option:`SB_CONFIG_NETCORE_HCI_IPC` | Zephyr hci_ipc Bluetooth image :zephyr_file:`samples/bluetooth/hci_ipc` | ++---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| :kconfig:option:`SB_CONFIG_NETCORE_RPC_HOST` | |NCS| rpc_host Bluetooth image :zephyr_file:`samples/bluetooth/rpc_host` | ++---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| :kconfig:option:`SB_CONFIG_NETCORE_802154_RPMSG` | Zephyr 802.15.4 image :zephyr_file:`samples/boards/nrf/ieee802154/802154_rpmsg` | ++---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| :kconfig:option:`SB_CONFIG_NETCORE_MULTIPROTOCOL_RPMSG` | |NCS| multiprotocol_rpmsg Bluetooth and 802.15.4 image :zephyr_file:`samples/nrf5340/multiprotocol_rpmsg` | ++---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| :kconfig:option:`SB_CONFIG_NETCORE_IPC_RADIO` | |NCS| ipc_radio image :zephyr_file:`applications/ipc_radio` | ++---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| :kconfig:option:`SB_CONFIG_NETCORE_NONE` | No network core image | ++---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ + +.. _sysbuild_images_adding_custom_images: + +Adding custom images +==================== + +Custom images can be added directly to a project (or board) or to a Zephyr module, making them accessible to multiple projects. + +.. _sysbuild_images_adding_to_single_project: + +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. + +Kconfig.sysbuild: + +.. code-block:: kconfig + + config MY_APP_IMAGE_ABC + bool "Include ABC image" + depends on SOC_SERIES_NRF53X + default y if BOARD_NRF5340DK_NRF5340_CPUAPP + help + Will include the ABC image in the build, which will... + + source "${ZEPHYR_BASE}/share/sysbuild/Kconfig" + +sysbuild.cmake: + +.. code-block:: cmake + + if(SB_CONFIG_MY_APP_IMAGE_ABC) + ExternalZephyrProject_Add( + APPLICATION ABC + SOURCE_DIR "" + BUILD_ONLY true # This will build the application and not flash it, this **must** be used when building additional images to a core (not the primary image) when using Partition Manager, as the main application for each core will flash a merged hex file instead + ) + endif() + +This method can be used to add a new image to the existing board target. + +.. _sysbuild_images_adding_custom_network_core_images: + +Adding custom network core images +--------------------------------- + +To add an image for a different board target (like for the network core of the nRF5340 SoC), you must use a different syntax. +This can be handled using the following approach: + +Kconfig.sysbuild: + +.. code-block:: kconfig + + menu "Network core configuration" + depends on SUPPORT_NETCORE + + config SUPPORT_NETCORE_ABC + bool + default y + + choice NETCORE + prompt "Netcore image" + depends on SUPPORT_NETCORE && !EXTERNAL_CONFIGURED_NETCORE + + config NETCORE_ABC + bool "ABC" + help + Use ABC image as the network core image. + + endchoice + + if !NETCORE_NONE + + config NETCORE_IMAGE_NAME + default "abc" if NETCORE_ABC + + config NETCORE_IMAGE_PATH + default "${ZEPHYR_MY_MODULE_MODULE_DIR}/" if NETCORE_ABC + + endif # !NETCORE_NONE + + endmenu + + source "${ZEPHYR_BASE}/share/sysbuild/Kconfig" + +sysbuild.cmake: + +This file is optional and is only needed if custom configuration needs to be set on the application + +.. code-block:: cmake + + if(SB_CONFIG_MY_APP_IMAGE_ABC) + # Project can optionally be configured here if needed + + # This will add a Kconfig fragment file, named `my_extra.conf` from the application directory + add_overlay_config(${SB_CONFIG_NETCORE_IMAGE_NAME} ${SB_CONFIG_NETCORE_IMAGE_PATH}/my_extra.conf) + # This will add a devicetree overlay file, named `my_extra.dts` from the application directory + add_overlay_dts(${SB_CONFIG_NETCORE_IMAGE_NAME} ${SB_CONFIG_NETCORE_IMAGE_PATH}/my_extra.dts) + # This will set a bool Kconfig option in the image (note: sysbuild forces this setting, it cannot be overwritten by changing the application configuration) + set_config_bool(${SB_CONFIG_NETCORE_IMAGE_NAME} CONFIG_MY_CUSTOM_CONFIG y) + # This will set a string (or numeric) Kconfig option in the image (note: sysbuild forces this setting, it cannot be overwritten by changing the application configuration) + set_property(TARGET ${SB_CONFIG_NETCORE_IMAGE_NAME} APPEND_STRING PROPERTY CONFIG "CONFIG_CUSTOM_STRING=my_custom_value\n") + endif() + +.. _sysbuild_images_adding_to_a_single_board: + +Adding to a single board +------------------------ + +You can place the same code as in the :ref:`sysbuild_images_adding_to_single_project` section, without the Zephyr sourcing, in a board directory. +This enables the use of those images for any sysbuild-based project being built for that board: + +Kconfig.sysbuild: + +.. code-block:: kconfig + + config MY_APP_IMAGE_ABC + bool "Include ABC image" + depends on SOC_SERIES_NRF53X + default y if BOARD_NRF5340DK_NRF5340_CPUAPP + help + Will include the ABC image in the build, which will... + +sysbuild.cmake: + +.. code-block:: cmake + + if(SB_CONFIG_MY_APP_IMAGE_ABC) + ExternalZephyrProject_Add( + APPLICATION ABC + SOURCE_DIR "" + BUILD_ONLY true # This will build the application and not flash it, this **must** be used when building additional images to a core (not the primary image) when using Partition Manager, as the main application for each core will flash a merged hex file instead + ) + endif() + +.. _sysbuild_images_adding_via_a_zephyr_module: + +Adding via a zephyr module +-------------------------- + +To add images in a Zephyr module, create a folder within the module to hold the `Kconfig.sysbuild` and (optionally, if needed) `CMakeLists.txt` files. +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-kconfig: sysbuild/Kconfig.sysbuild + +The ``CMakeLists.txt`` file is the same as the ``sysbuild.cmake`` file from the previous examples. +The ``Kconfig.sysbuild`` file is the same as the file from the previous examples but without the Zephyr sourcing. +When images are configured, these additional images will be available from sysbuild and can be used in any project within the tree. + +Kconfig.sysbuild: + +.. code-block:: kconfig + + menu "Network core configuration" + depends on SUPPORT_NETCORE + + config SUPPORT_NETCORE_ABC + bool + default y + + choice NETCORE + prompt "Netcore image" + depends on SUPPORT_NETCORE && !EXTERNAL_CONFIGURED_NETCORE + + config NETCORE_ABC + bool "ABC" + help + Use ABC image as the network core image. + + endchoice + + if !NETCORE_NONE + + config NETCORE_IMAGE_NAME + default "abc" if NETCORE_ABC + + config NETCORE_IMAGE_PATH + default "${ZEPHYR_MY_MODULE_MODULE_DIR}/" if NETCORE_ABC + + endif # !NETCORE_NONE + + endmenu 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 new file mode 100644 index 000000000000..0d5953a0f7f4 --- /dev/null +++ b/doc/nrf/config_and_build/configuring_app/zephyr_samples_sysbuild.rst @@ -0,0 +1,47 @@ +.. _zephyr_samples_sysbuild: + +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. +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: + +.. tabs:: + + .. group-tab:: west + + west build -b -- -DSB_CONFIG_NETCORE_HCI_IPC=y + + .. group-tab:: cmake + + cmake -GNinja -DBOARD= -DSB_CONFIG_NETCORE_HCI_IPC=y -DAPP_DIR= + +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 4a73ae1391d5..6cb1f052f5fb 100644 --- a/doc/nrf/config_and_build/multi_image.rst +++ b/doc/nrf/config_and_build/multi_image.rst @@ -1,7 +1,7 @@ .. _ug_multi_image: -Multi-image builds -################## +Multi-image builds using child and parent images +################################################ .. contents:: :local: diff --git a/doc/nrf/device_guides/nrf52/fota_update.rst b/doc/nrf/device_guides/nrf52/fota_update.rst index 34492948c5df..4ad4243a07f9 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:`CONFIG_BOOTLOADER_MCUBOOT` must be enabled). +* Use MCUboot as the upgradable bootloader (:kconfig:option:`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,27 +85,25 @@ 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 ``CONFIG_BOOT_DIRECT_XIP`` Kconfig option in the MCUboot bootloader configuration. -* Enable the :kconfig:option:`CONFIG_MCUBOOT_BOOTLOADER_MODE_DIRECT_XIP` Kconfig option to inform the application about the chosen MCUboot mode of operation. +* Enable the :kconfig:option:`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* -- -Dmcuboot_CONFIG_BOOT_DIRECT_XIP=y -DCONFIG_BOOTLOADER_MCUBOOT=y -DCONFIG_NCS_SAMPLE_MCUMGR_BT_OTA_DFU=y -DCONFIG_MCUBOOT_BOOTLOADER_MODE_DIRECT_XIP=y + west build -b *board_target* -- -DSB_CONFIG_BOOTLOADER_MCUBOOT=y -DSB_CONFIG_BOOT_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 ``CONFIG_BOOT_DIRECT_XIP_REVERT`` Kconfig option in the MCUboot bootloader configuration. -* Enable the :kconfig:option:`CONFIG_MCUBOOT_BOOTLOADER_MODE_DIRECT_XIP_WITH_REVERT` Kconfig option in place of :kconfig:option:`CONFIG_MCUBOOT_BOOTLOADER_MODE_DIRECT_XIP` to inform the application about the chosen MCUboot mode of operation. +* 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`. See how to build the :ref:`peripheral_lbs` sample with MCUboot in direct-xip mode when the revert mechanism support is enabled: .. parsed-literal:: :class: highlight - west build -b *board_target* -- -Dmcuboot_CONFIG_BOOT_DIRECT_XIP=y -Dmcuboot_CONFIG_BOOT_DIRECT_XIP_REVERT=y -DCONFIG_BOOTLOADER_MCUBOOT=y -DCONFIG_NCS_SAMPLE_MCUMGR_BT_OTA_DFU=y -DCONFIG_MCUBOOT_BOOTLOADER_MODE_DIRECT_XIP_WITH_REVERT=y + west build -b *board_target* -- -DSB_CONFIG_BOOTLOADER_MCUBOOT=y -DSB_CONFIG_MCUBOOT_MODE_DIRECT_XIP_WITH_REVERT=y -DCONFIG_NCS_SAMPLE_MCUMGR_BT_OTA_DFU=y .. note:: When building the application for the first time with MCUboot in direct-xip mode and the revert mechanism support, use an additional option ``-DCONFIG_MCUBOOT_EXTRA_IMGTOOL_ARGS=\"--confirm\"``. @@ -113,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:`CONFIG_MCUBOOT_BOOTLOADER_MODE_DIRECT_XIP` and :kconfig:option:`CONFIG_MCUBOOT_BOOTLOADER_MODE_DIRECT_XIP_WITH_REVERT` Kconfig options automatically enable :kconfig:option:`CONFIG_BOOT_BUILD_DIRECT_XIP_VARIANT`, which allows to build application update images for both slots. +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. 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 @@ -138,7 +136,7 @@ To perform a FOTA update, complete the following steps: .. fota_upgrades_over_ble_nrfcdm_common_dfu_steps_start 1. Generate the DFU package by building your application with the FOTA support over Bluetooth Low Energy. - You can find the generated :file:`dfu_application.zip` archive in the following directory :file:`/zephyr`. + You can find the generated :file:`dfu_application.zip` archive in the build directory. .. note:: For each image included in the DFU-generated package, use a higher version number than your currently active firmware. @@ -187,11 +185,23 @@ The sample documentation is from the Zephyr project and is incompatible with the When working in the |NCS| environment, ignore the part of the sample documentation that describes the building and programming steps. In |NCS|, you can build and program the :zephyr:code-sample:`smp-svr` as any other sample using the following commands: -.. parsed-literal:: - :class: highlight +.. tabs:: + + .. group-tab:: nRF5340 SoCs + + .. parsed-literal:: + :class: highlight + + west build -b *board_target* -- -DEXTRA_CONF_FILE=overlay-bt.conf -DSB_CONFG_NETCORE_HCI_IPC=y + west flash + + .. group-tab:: nRF52 SoCs + + .. parsed-literal:: + :class: highlight - west build -b *board_target* -- -DEXTRA_CONF_FILE=overlay-bt.conf - west flash + west build -b *board_target* -- -DEXTRA_CONF_FILE=overlay-bt.conf + west flash Make sure to indicate the :file:`overlay-bt.conf` overlay configuration for the Bluetooth transport like in the command example. This configuration was carefully selected to achieve the maximum possible throughput of the FOTA update transport over Bluetooth with the help of the following features: diff --git a/doc/nrf/device_guides/nrf53/building_nrf53.rst b/doc/nrf/device_guides/nrf53/building_nrf53.rst index 684e9860cfb9..ae94735853e7 100644 --- a/doc/nrf/device_guides/nrf53/building_nrf53.rst +++ b/doc/nrf/device_guides/nrf53/building_nrf53.rst @@ -80,7 +80,7 @@ To program the nRF5340 DK from the command line, use either west (which uses nrf 1. Open a command prompt in the build folder of the network sample and enter the following command to erase the flash memory of the network core and program the network sample:: - nrfutil device program --firmware zephyr.hex --options chip_erase_mode=ERASE_ALL --core Network + nrfutil device program --firmware zephyr.hex --options chip_erase_mode=ERASE_ALL --core Network .. note:: If you cannot locate the build folder of the network sample, look for a folder with one of these names inside the build folder of the application sample: @@ -92,7 +92,10 @@ To program the nRF5340 DK from the command line, use either west (which uses nrf 2. Navigate to the build folder of the application sample and enter the following command to erase the flash memory of the application core and program the application sample:: - nrfutil device program --firmware zephyr/zephyr.hex --options chip_erase_mode=ERASE_ALL + nrfutil device program --firmware zephyr.hex --options chip_erase_mode=ERASE_ALL + + .. note:: + The application build folder will be in a sub-directory which is the name of the folder of the application 3. Reset the development kit:: @@ -100,9 +103,9 @@ To program the nRF5340 DK from the command line, use either west (which uses nrf See :ref:`readback_protection_error` if you encounter an error. - .. group-tab:: Multi-image build + .. group-tab:: Sysbuild - To build and program a multi-image HEX file, follow the instructions in :ref:`programming_cmd` for the application core sample. + To build and program a sysbuild HEX file, follow the instructions in :ref:`programming_cmd` for the application core sample. To program the multi-image HEX file, you can use west or nRF Util. @@ -119,9 +122,10 @@ To program the nRF5340 DK from the command line, use either west (which uses nrf .. group-tab:: nRF Util - Enter the following commands to program multi-image builds for different cores:: + Enter the following commands to program multiple image builds for different cores:: - nrfutil device program --firmware zephyr/merged_domains.hex --options verify=VERIFY_READ,chip_erase_mode=ERASE_CTRL_AP + nrfutil device program --firmware merged_CPUNET.hex --options verify=VERIFY_READ,chip_erase_mode=ERASE_CTRL_AP + nrfutil device program --firmware merged.hex --options verify=VERIFY_READ,chip_erase_mode=ERASE_CTRL_AP .. note:: The ``--verify`` command confirms that the writing operation has succeeded. @@ -198,9 +202,9 @@ When you choose ``thingy53/nrf5340/cpuapp`` or ``thingy53/nrf5340/cpuapp/ns`` as The build process generates firmware in two formats: -* Intel Hex file (:file:`merged_domains.hex`) - Used with an external debug probe. - The file contains bootloaders and applications for both cores. -* Binary files (:file:`app_update.bin`, :file:`net_core_app_update.bin`), containing signed application firmwares for the application and network core, respectively. +* Intel Hex file (:file:`merged.hex` and :file:`merged_CPUNET.hex`) - Used with an external debug probe. + These file contains bootloaders and applications for each core. +* Binary files (:file:`zephyr.signed.bin`), containing signed application firmwares for the application and network core, respectively. For convenience, the binary files are bundled in :file:`dfu_application.zip`, together with a manifest that describes them. You can use the binary files or the combined zip archive to update application firmware for both cores, with either MCUboot serial recovery or OTA DFU using Bluetooth LE. diff --git a/doc/nrf/device_guides/nrf53/multi_image_nrf5340.rst b/doc/nrf/device_guides/nrf53/multi_image_nrf5340.rst index 18018a6152a1..6819dbcf3299 100644 --- a/doc/nrf/device_guides/nrf53/multi_image_nrf5340.rst +++ b/doc/nrf/device_guides/nrf53/multi_image_nrf5340.rst @@ -1,12 +1,15 @@ .. _ug_nrf5340_multi_image: -Multi-image builds on the nRF5340 DK -#################################### +Multi-image builds on the nRF5340 DK using child and parent images +################################################################## .. contents:: :local: :depth: 2 +.. note:: + |sysbuild_related_deprecation_note| + If a sample consists of several images (in this case, different images for the application core and for the network core), you can build these images separately or combined as a :ref:`multi-image build `, depending on the sample configuration. In a multi-image build, the image for the application core is usually the parent image, and the image for the network core is treated as a child image in a separate domain. 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 c71981ee129c..8873b8a32aef 100644 --- a/doc/nrf/device_guides/nrf70/fw_patches_ext_flash.rst +++ b/doc/nrf/device_guides/nrf70/fw_patches_ext_flash.rst @@ -15,7 +15,7 @@ This guide explains the available options for having the nRF70 Series firmware p Overview ******** -By default, the nRF70 Series firmware patches are built as part of the nRF Wi-Fi driver code, residing in on-chip memory. +By default, the nRF70 Series firmware patches are built as part of sysbuild, residing in on-chip memory. The firmware patches include code that is executed on the nRF70 Series device. The size of the firmware patches might be considerably large, which limits the amount of on-chip code memory available for the user application. In order to increase the amount of on-chip memory available for user applications, the nRF Wi-Fi driver supports the option of using external memory, if that is available. @@ -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:`CONFIG_NRF_WIFI_PATCHES_EXT_FLASH_XIP` Kconfig option to ``y``. +To enable this feature, set the :kconfig:option:`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:`CONFIG_NRF_WIFI_PATCHES_EXT_FLASH_STORE` - Enables the option to store the firmware patch in external non-XIP memory. +* :kconfig:option:`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,7 @@ Building See :ref:`nrf7002dk_nrf5340` for general instructions on building. -Additionally, you must enable either the ``nrf70-fw-patch-ext-flash`` snippet or the :kconfig:option:`CONFIG_PARTITION_MANAGER_ENABLED` option. +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`. 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. @@ -135,31 +135,31 @@ With west .. code-block:: console - west build -p -b nrf5340dk/nrf5340/cpuapp samples/wifi/shell -- -Dnrf_wifi_shell_SHIELD=nrf7002ek -Dnrf_wifi_shell_SNIPPET="nrf70-fw-patch-ext-flash" + west build -p -b nrf5340dk/nrf5340/cpuapp samples/wifi/shell -- -Dnrf_wifi_shell_SHIELD=nrf7002ek -Dnrf_wifi_shell_SNIPPET="nrf70-fw-patch-ext-flash" -DSB_CONFIG_WIFI_PATCHES_EXT_FLASH_STORE=y -DSB_CONFIG_PARTITION_MANAGER=n With CMake ^^^^^^^^^^ .. code-block:: console - cmake -GNinja -Bbuild -DBOARD=nrf5340dk/nrf5340/cpuapp -Dnrf_wifi_shell_SHIELD=nrf7002ek -Dnrf_wifi_shell_SNIPPET="nrf70-fw-patch-ext-flash" samples/wifi/shell + cmake -GNinja -Bbuild -DBOARD=nrf5340dk/nrf5340/cpuapp -Dnrf_wifi_shell_SHIELD=nrf7002ek -Dnrf_wifi_shell_SNIPPET="nrf70-fw-patch-ext-flash" -DSB_CONFIG_WIFI_PATCHES_EXT_FLASH_STORE=y -DSB_CONFIG_PARTITION_MANAGER=n samples/wifi/shell ninja -C build -For example, to build the :ref:`wifi_shell_sample` sample for the nRF5340 DK with the :kconfig:option:`CONFIG_PARTITION_MANAGER_ENABLED` option enabled, run the following commands: +For example, to build the :ref:`wifi_shell_sample` sample for the nRF5340 DK with partition manager enabled, run the following commands: With west ^^^^^^^^^ .. code-block:: console - west build -p -b nrf5340dk/nrf5340/cpuapp samples/wifi/shell -- -Dnrf_wifi_shell_SHIELD=nrf7002ek -DCONFIG_PARTITION_MANAGER_ENABLED=y -DCONFIG_NRF_WIFI_PATCHES_EXT_FLASH_STORE=y + west build -p -b nrf5340dk/nrf5340/cpuapp samples/wifi/shell -- -Dnrf_wifi_shell_SHIELD=nrf7002ek -DSB_CONFIG_WIFI_PATCHES_EXT_FLASH_STORE=y With CMake ^^^^^^^^^^ .. code-block:: console - cmake -GNinja -Bbuild -DBOARD=nrf5340dk/nrf5340/cpuapp -Dnrf_wifi_shell_SHIELD=nrf7002ek -DCONFIG_PARTITION_MANAGER_ENABLED=y -DCONFIG_NRF_WIFI_PATCHES_EXT_FLASH_STORE=y samples/wifi/shell + cmake -GNinja -Bbuild -DBOARD=nrf5340dk/nrf5340/cpuapp -Dnrf_wifi_shell_SHIELD=nrf7002ek -DSB_CONFIG_WIFI_PATCHES_EXT_FLASH_STORE=y samples/wifi/shell ninja -C build Programming @@ -185,7 +185,7 @@ For example, for nrfjprog: .. code-block:: console - nrfjprog -f nrf53 -s 0 --program build/zephyr/merged.hex ---sectorerase --qspisectorerase --verify --reset + nrfjprog -f nrf53 -s 0 --program build/merged.hex ---sectorerase --qspisectorerase --verify --reset Updating firmware patches ========================= 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 8637522ec562..75fea2293777 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:`CONFIG_NRF_WIFI_PATCHES_EXT_FLASH_STORE` and :kconfig:option:`CONFIG_XIP_SPLIT_IMAGE` Kconfig options enabled. - To enable XIP support use the :kconfig:option:`CONFIG_NRF_WIFI_PATCHES_EXT_FLASH_XIP` Kconfig option instead of the :kconfig:option:`CONFIG_NRF_WIFI_PATCHES_EXT_FLASH_STORE` Kconfig option. + 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. 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:`CONFIG_BOOTLOADER_MCUBOOT` Kconfig option is set to ``y``. +* MCUboot is enabled, and the :kconfig:option:`SB_CONFIG_BOOTLOADER_MCUBOOT` Kconfig option is set to ``y``. Supported platforms =================== @@ -163,15 +163,13 @@ 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:`CONFIG_UPDATEABLE_IMAGE_NUMBER`` Kconfig option to ``2``. - #. For the MCUBoot child image, set the :kconfig:option:`CONFIG_UPDATEABLE_IMAGE_NUMBER`` Kconfig option to ``2``. + 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``. * 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:`CONFIG_UPDATEABLE_IMAGE_NUMBER`` Kconfig option to ``3``. - #. For the MCUBoot child image, set the :kconfig:option:`CONFIG_UPDATEABLE_IMAGE_NUMBER`` Kconfig option to ``3``. + #. Set the :kconfig:option:`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: @@ -181,13 +179,13 @@ For example, to build the sample with the DFU procedure for the nRF70 Series fir .. code-block:: console - west build -d nrf5340dk/nrf5340/cpuapp -d -- -DSHIELD=nrf7002ek -DCONFIG_PARTITION_MANAGER_ENABLED=y -DCONFIG_NRF_WIFI_PATCHES_EXT_FLASH_STORE=y -DCONFIG_NRF_WIFI_FW_PATCH_DFU=y -DCONFIG_UPDATEABLE_IMAGE_NUMBER=3 -Dmcuboot_CONFIG_UPDATEABLE_IMAGE_NUMBER=3 + west build -d nrf5340dk/nrf5340/cpuapp -d -- -DSHIELD=nrf7002ek -DSB_CONFIG_WIFI_PATCHES_EXT_FLASH_STORE=y -DCONFIG_NRF_WIFI_FW_PATCH_DFU=y -DSB_CONFIG_MCUBOOT_UPDATEABLE_IMAGES=3 .. group-tab:: CMake .. code-block:: console - cmake -GNinja -Bbuild -DBOARD=nrf5340dk/nrf5340/cpuapp -DSHIELD=nrf7002ek -DCONFIG_PARTITION_MANAGER_ENABLED=y -DCONFIG_NRF_WIFI_PATCHES_EXT_FLASH_STORE=y -DCONFIG_NRF_WIFI_FW_PATCH_DFU=y -DCONFIG_UPDATEABLE_IMAGE_NUMBER=3 -Dmcuboot_CONFIG_UPDATEABLE_IMAGE_NUMBER=3 sample + cmake -GNinja -Bbuild -DBOARD=nrf5340dk/nrf5340/cpuapp -DSHIELD=nrf7002ek -DSB_CONFIG_WIFI_PATCHES_EXT_FLASH_STORE=y -DCONFIG_NRF_WIFI_FW_PATCH_DFU=y -DSB_CONFIG_MCUBOOT_UPDATEABLE_IMAGES=3 sample ninja -C build .. group-tab:: nRF Connect for VS Code @@ -198,9 +196,9 @@ For example, to build the sample with the DFU procedure for the nRF70 Series fir .. code-block:: console - -- -DSHIELD=nrf7002ek -DCONFIG_PARTITION_MANAGER_ENABLED=y -DCONFIG_NRF_WIFI_PATCHES_EXT_FLASH_STORE=y -DCONFIG_NRF_WIFI_FW_PATCH_DFU=y -DCONFIG_UPDATEABLE_IMAGE_NUMBER=3 -Dmcuboot_CONFIG_UPDATEABLE_IMAGE_NUMBER=3 + -- -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:`CONFIG_DFU_MULTI_IMAGE_MAX_IMAGE_COUNT` Kconfig option to one of the following values: +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: * For the nRF5340 DK without the network core: ``2`` * For the nRF5340 DK with the network core: ``3`` diff --git a/doc/nrf/libraries/bluetooth_services/services/fast_pair.rst b/doc/nrf/libraries/bluetooth_services/services/fast_pair.rst index c091d67e9ad5..0b2d99392062 100644 --- a/doc/nrf/libraries/bluetooth_services/services/fast_pair.rst +++ b/doc/nrf/libraries/bluetooth_services/services/fast_pair.rst @@ -135,7 +135,7 @@ 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:`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:`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 d53d1454d18a..1992bc70bb73 100644 --- a/doc/nrf/libraries/dfu/dfu_multi_image.rst +++ b/doc/nrf/libraries/dfu/dfu_multi_image.rst @@ -23,7 +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:`CONFIG_DFU_MULTI_IMAGE_PACKAGE_BUILD` 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: + ++-------------------------------------------------------------------+---------------------------------------+ +| Kconfig | Description | ++===================================================================+=======================================+ +| :kconfig:option:`SB_CONFIG_DFU_MULTI_IMAGE_PACKAGE_APP` | Include application update | ++-------------------------------------------------------------------+---------------------------------------+ +| :kconfig:option:`SB_CONFIG_DFU_MULTI_IMAGE_PACKAGE_NET` | Include network core image update | ++-------------------------------------------------------------------+---------------------------------------+ +| :kconfig:option:`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 | ++-------------------------------------------------------------------+---------------------------------------+ Dependencies ************ diff --git a/doc/nrf/libraries/zigbee/zigbee_fota.rst b/doc/nrf/libraries/zigbee/zigbee_fota.rst index 53f57cdfe103..17f5dbc469e4 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:`CONFIG_BOOT_SWAP_USING_MOVE` Kconfig option. +* It is impossible to enable :kconfig:option:`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/protocols/bt/bt_mesh/dfu_over_bt_mesh.rst b/doc/nrf/protocols/bt/bt_mesh/dfu_over_bt_mesh.rst index dd154812f09c..d80050e39e43 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:`CONFIG_BT_MESH_DFU_METADATA_ON_BUILD` option in the application, the metadata will be automatically parsed from the ``.elf`` and ``.config`` files. +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. 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/releases_and_maturity/migration/migration_sysbuild.rst b/doc/nrf/releases_and_maturity/migration/migration_sysbuild.rst new file mode 100644 index 000000000000..4cd7a6ce8037 --- /dev/null +++ b/doc/nrf/releases_and_maturity/migration/migration_sysbuild.rst @@ -0,0 +1,691 @@ +.. _child_parent_to_sysbuild_migration: + +Migrating from multi-image builds to sysbuild +############################################# + +:ref:`sysbuild` is a build system used in zephyr to configure, build, and flash multiple images as part of a single project. +It replaces the :ref:`child/parent system for multi-image builds ` in |NCS|. +As the previous system has been deprecated, you must update your existing multi-image build projects to support being built using sysbuild. + +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 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. + +This results in the CMake configuration step running more than once, as this information is only available after all images have been processed. + +* Sysbuild output files have different names and locations (they are namespaced). +* 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. + +.. _child_parent_to_sysbuild_migration_sysbuild_configuration_file: + +Sysbuild configuration files +============================ + +You can set sysbuild configuration for projects in the ``sysbuild.conf`` file in the project folder. +You can also add custom Kconfig values in the ``Kconfig.sysbuild`` file in the project folder, or use this file to set Kconfig defaults that depend on a board or other parameters when building a project. +Sysbuild Kconfig values in Kconfig fragment files have the ``SB_CONFIG_`` prefix. +The following example demonstrates how to use these files to set project configuration: + +.. tabs:: + + .. group-tab:: sysbuild.conf + + This example enables MCUboot, sets the key type to RSA, and specifies the overwrite-only mode for all boards: + + .. code-block:: cfg + + SB_CONFIG_BOOTLOADER_MCUBOOT=y + SB_CONFIG_MCUBOOT_MODE_OVERWRITE_ONLY=y + SB_CONFIG_BOOT_SIGNATURE_TYPE_RSA=y + + .. group-tab:: Kconfig.sysbuild + + This example enables MCUboot, sets the key type to RSA, and specifies the overwrite-only mode for the application core of the nRF5340 DK: + + .. code-block:: kconfig + + if BOARD_NRF5340DK_NRF5340_CPUAPP + + choice BOOTLOADER + default BOOTLOADER_MCUBOOT + endchoice + + if BOOTLOADER_MCUBOOT + + choice MCUBOOT_MODE + default MCUBOOT_MODE_OVERWRITE_ONLY + endchoice + + choice BOOT_SIGNATURE_TYPE + default BOOT_SIGNATURE_TYPE_RSA + endchoice + + endif # BOOTLOADER_MCUBOOT + + endif # BOARD_NRF5340DK_NRF5340_CPUAPP + +Both approaches are used in |NCS| applications and samples depending on the required configuration. + +.. note:: + + Sysbuild has :ref:`file suffix support `, which means different files can be created and used depending on whether a file suffix is used for a build. + +.. _child_parent_to_sysbuild_migration_network_core: + +Network core +============ + +Sysbuild handles the selection of the network core image. +The following Kconfig options are available to include the desired image in the build or to set network core options: + ++---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| Kconfig option | Description | ++=========================================================+===========================================================================================================+ +| :kconfig:option:`SB_CONFIG_NETCORE_EMPTY` | Empty network core image :zephyr_file:`samples/nrf5340/empty_net_core` | ++---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| :kconfig:option:`SB_CONFIG_NETCORE_HCI_IPC` | Zephyr hci_ipc Bluetooth image :zephyr_file:`samples/bluetooth/hci_ipc` | ++---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| :kconfig:option:`SB_CONFIG_NETCORE_RPC_HOST` | |NCS| rpc_host Bluetooth image :zephyr_file:`samples/bluetooth/rpc_host` | ++---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| :kconfig:option:`SB_CONFIG_NETCORE_802154_RPMSG` | Zephyr 802.15.4 image :zephyr_file:`samples/boards/nrf/ieee802154/802154_rpmsg` | ++---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| :kconfig:option:`SB_CONFIG_NETCORE_MULTIPROTOCOL_RPMSG` | |NCS| multiprotocol_rpmsg Bluetooth and 802.15.4 image :zephyr_file:`samples/nrf5340/multiprotocol_rpmsg` | ++---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| :kconfig:option:`SB_CONFIG_NETCORE_IPC_RADIO` | |NCS| ipc_radio image :zephyr_file:`applications/ipc_radio` | ++---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ +| :kconfig:option:`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) | ++---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ + +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. +Projects must be updated to select the correct network core image. + +.. _child_parent_to_sysbuild_migration_mcuboot: + +MCUboot +======= + +Sysbuild handles MCUboot mode selection and key file configuration. +The following Kconfig options are available: + ++---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ +| Kconfig option | Description | ++===========================================================================+==========================================================================================================================+ +| :kconfig:option:`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) | ++---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ +| :kconfig:option:`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 | ++---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ +| :kconfig:option:`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 | ++---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ +| :kconfig:option:`SB_CONFIG_BOOT_ENCRYPTION` | Enable MCUboot image encryption | ++---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ +| :kconfig:option:`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) | ++---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ +| :kconfig:option:`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 | ++---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ +| :kconfig:option:`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 | ++---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ +| :kconfig:option:`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 | ++---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ +| :kconfig:option:`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 | ++---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ +| :kconfig:option:`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 | ++---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ +| :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 | ++---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ +| :kconfig:option:`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. +These options generate the respective output files for the main application build. +Any MCUboot configuration that was previously done in the main application or MCUboot needs to be updated to apply at the sysbuild level. +If this is not done, the settings of these builds will be forcefully replaced with the default generated by sysbuild, making firmware updates incompatible with firmware images built in previous versions of the |NCS|. + +.. _child_parent_to_sysbuild_migration_secure_boot: + +Secure boot +=========== + +Sysbuild handles the mode selection of secure boot and the configuration of the key file. +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) | ++------------------------------------------------------------+-----------------------------------------------------------------------------------------+ +| :kconfig:option:`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) | ++------------------------------------------------------------+-----------------------------------------------------------------------------------------+ +| :kconfig:option:`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 | ++------------------------------------------------------------+-----------------------------------------------------------------------------------------+ +| :kconfig:option:`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 | ++------------------------------------------------------------+-----------------------------------------------------------------------------------------+ +| :kconfig:option:`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 | ++------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + +Secure boot can now be enabled centrally from sysbuild for both the application and network cores for nRF53-based boards. +Configuration that was previously done in the images themselves must now be applied at the sysbuild level. +If not, the secure boot images are not built, or the settings of these builds are forcefully replaced with the default generated by sysbuild, making firmware updates incompatible with firmware images built in previous versions of the |NCS|. + +.. _child_parent_to_sysbuild_migration_bluetooth_fast_pair: + +Google Fast Pair +================ + +Sysbuild now handles the HEX generation with Google Fast Pair provisioning data. +See the :ref:`ug_bt_fast_pair_provisioning_register` section in the Fast Pair integration guide for more details regarding the provisioning process. +The following Kconfig options are available: + ++------------------------------------------+----------------------------------------+ +| Kconfig option | Description | ++==========================================+========================================+ +| :kconfig:option:`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`. + 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: + +Matter +====== + +Sysbuild now directly controls Matter configuration for generating factory data and over-the-air firmware update images. +The following Kconfig options are available: + ++---------------------------------------------------------------------+---------------------------------------------------+ +| Kconfig option | Description | ++=====================================================================+===================================================+ +| :kconfig:option:`SB_CONFIG_MATTER` | Enable matter support | ++---------------------------------------------------------------------+---------------------------------------------------+ +| :kconfig:option:`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 | ++---------------------------------------------------------------------+---------------------------------------------------+ +| :kconfig:option:`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 | ++---------------------------------------------------------------------+---------------------------------------------------+ + +Applications must enable these options if they generate factory data or need an over-the-air firmware update. + +.. note:: + + The configuration data for the factory data file is still configured from the main application. + +.. _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: + ++----------------------------------------------------------------+-----------------------------------------------------------------------------+ +| Kconfig option | Description | ++================================================================+=============================================================================+ +| :kconfig:option:`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 | ++----------------------------------------------------------------+-----------------------------------------------------------------------------+ +| :kconfig:option:`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 | ++----------------------------------------------------------------+-----------------------------------------------------------------------------+ +| :kconfig:option:`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) | ++----------------------------------------------------------------+-----------------------------------------------------------------------------+ +| :kconfig:option:`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 | ++----------------------------------------------------------------+-----------------------------------------------------------------------------+ + +You must update your applications to select the required Kconfig options at the sysbuild level for applications to work. +These sysbuild Kconfig options are no longer defaulted or gated depending on the features that the main application uses, so you must set these manually. +If these options are not set, nRF700x functionality will not work. + +.. _child_parent_to_sysbuild_migration_dfu_multi_image_build: + +Multi-image builds for DFU +========================== + +Support for creating multi-image build files for Device Firmware Update (DFU) was moved to sysbuild. +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 | ++-------------------------------------------------------------------+---------------------------------------------------+ +| :kconfig:option:`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 | ++-------------------------------------------------------------------+---------------------------------------------------+ +| :kconfig:option:`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 | ++-------------------------------------------------------------------+---------------------------------------------------+ + +You must update your application to select the required Kconfig options at the sysbuild level to have this file generated. + +.. _child_parent_to_sysbuild_migration_dfu_zip: + +DFU Zip file generation +======================= + +Support for generating a firmware update zip has moved to sysbuild. +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 | ++-------------------------------------------------------------+----------------------------------------------------------------------------+ +| :kconfig:option:`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 | ++-------------------------------------------------------------+----------------------------------------------------------------------------+ +| :kconfig:option:`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 | ++-------------------------------------------------------------+----------------------------------------------------------------------------+ + +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. + +.. _child_parent_to_sysbuild_migration_partition_manager: + +Partition manager +================= + +Support for using partition manager for an image was moved to sysbuild. +The following Kconfig options are available: + ++-----------------------------------------------------------------+----------------------------------------------------------------------------+ +| Kconfig option | Description | ++=================================================================+============================================================================+ +| :kconfig:option:`SB_CONFIG_PARTITION_MANAGER` | Enables partition manager support | ++-----------------------------------------------------------------+----------------------------------------------------------------------------+ +| :kconfig:option:`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 | ++-----------------------------------------------------------------+----------------------------------------------------------------------------+ +| :kconfig:option:`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. +If these options are not set, firmware updates may not work or images may fail to boot. + +.. _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. +The changes to final output files (ignoring artifacts and intermediary files) are as follows: + ++-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Child/parent file | Sysbuild file | ++=====================================================+==============================================================================================================================================================+ +| ``zephyr/app_update.bin`` | ``/zephyr/.signed.bin`` where ```` is the applications Kconfig :kconfig:option:`CONFIG_KERNEL_BIN_NAME` value | ++-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``zephyr/app_signed.hex`` | ``/zephyr/.signed.hex`` where ```` is the applications Kconfig :kconfig:option:`CONFIG_KERNEL_BIN_NAME` value | ++-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``zephyr/app_test_update.hex`` | No equivalent | ++-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``zephyr/app_moved_test_update.hex`` | No equivalent | ++-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``zephyr/net_core_app_update.bin`` | ``signed_by_mcuboot_and_b0_.bin`` where ```` is the name of the network core application | ++-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``zephyr/net_core_app_signed.hex`` | ``signed_by_b0_.hex`` where ```` is the name of the network core application | ++-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``zephyr/net_core_app_test_update.hex`` | No equivalent | ++-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``zephyr/net_core_app_moved_test_update.hex`` | No equivalent | ++-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``zephyr/mcuboot_secondary_app_update.bin`` | ``mcuboot_secondary_app/zephyr/.signed.bin`` where ```` is the applications Kconfig :kconfig:option:`CONFIG_KERNEL_BIN_NAME` value | ++-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``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/signed_by_b0_s0_image.hex`` | ``signed_by_b0_.hex`` where ```` is the name of the application | ++-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``zephyr/signed_by_b0_s1_image.hex`` | ``signed_by_b0_s1_image.hex`` | ++-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``zephyr/signed_by_b0_s0_image.bin`` | ``signed_by_b0_.bin`` where ```` is the name of the application | ++-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``zephyr/signed_by_b0_s1_image.bin`` | ``signed_by_b0_s1_image.bin`` | ++-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``/zephyr/signed_by_b0_app.hex`` | ``signed_by_b0_.hex`` where ```` is the name of the network core application | ++-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``/zephyr/signed_by_b0_app.bin`` | ``signed_by_b0_.bin`` where ```` is the name of the network core application | ++-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``zephyr/merged.hex`` | ``merged.hex`` | ++-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``/zephyr/merged_CPUNET.hex`` | ``merged_CPUNET.hex`` | ++-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``zephyr/merged_domains.hex`` | No equivalent, use ``merged.hex`` for application core and ``merged_CPUNET.hex`` for network core | ++-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``zephyr/dfu_multi_image.bin`` | ``dfu_multi_image.bin`` | ++-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``zephyr/dfu_application.zip`` | ``dfu_application.zip`` | ++-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``zephyr/dfu_mcuboot.zip`` | ``dfu_mcuboot.zip`` | ++-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +Example output files +==================== + +To demonstrate the expected output files when using sysbuild for an application build, the following sections show and describe the output files for the ``matter_weather_station`` application when building using the ``thingy53/nrf5340/cpaupp`` board target: + +Provision/container files +------------------------- + +The expected output files are the following: + ++-----------------------+-------------------------------------------------------+ +| File | Description | ++=======================+=======================================================+ +| ``b0n_container.hex`` | Copy of ``b0n/zephyr/zephyr.hex`` | ++-----------------------+-------------------------------------------------------+ +| ``net_provision.hex`` | Provision data for the network core secure boot image | ++-----------------------+-------------------------------------------------------+ + +Image build files +----------------- + +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.bin`` | Unsigned main application binary file | ++-----------------------------------------------------+-------------------------------------------------------------------------------------------------------+ +| ``matter_weather_station/zephyr/zephyr.signed.hex`` | Signed (with MCUboot signing key) main application hex file | ++-----------------------------------------------------+-------------------------------------------------------------------------------------------------------+ +| ``mcuboot/zephyr/zephyr.hex`` | MCUboot 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.hex`` | Network core secure bootloader binary 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 | ++-----------------------------------------------------+-------------------------------------------------------------------------------------------------------+ + +Combined files +-------------- + +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_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 +------------ + +The expected output files are the following: + ++-----------------------------------------------------+----------------------------------------------------------------------------------------------------------+ +| File | Description | ++=====================================================+==========================================================================================================+ +| ``matter_weather_station/zephyr/zephyr.signed.bin`` | Signed (with MCUboot signing key) main application binary file which can be used directly with MCUmgr | ++-----------------------------------------------------+----------------------------------------------------------------------------------------------------------+ +| ``signed_by_mcuboot_and_b0_ipc_radio.bin`` | Signed (with b0 and MCUboot signing key) network core IPC radio update from application core binary file | ++-----------------------------------------------------+----------------------------------------------------------------------------------------------------------+ +| ``dfu_multi_image.bin`` | DFU multi image file containing firmware update files and manifest | ++-----------------------------------------------------+----------------------------------------------------------------------------------------------------------+ +| ``matter.ota`` | Matter over-the-air firmware update file | ++-----------------------------------------------------+----------------------------------------------------------------------------------------------------------+ +| ``dfu_application.zip`` | Zip file containing firmware update files and manifest | ++-----------------------------------------------------+----------------------------------------------------------------------------------------------------------+ + +.. _child_parent_to_sysbuild_migration_image_overlay_changes: + +Image overlay configuration +=========================== + +In child/parent image configurations, an application could include additional configuration files in the ``child_image`` folder that would be applied to these images (see :ref:`ug_multi_image_permanent_changes`). +This feature has been adapted in sysbuild; see :ref:`sysbuild_application_configuration` for an overview. +You must update child/parent image configuration to use it with sysbuild, as the way these files can be used differs: + +* In child/parent image configurations, there can be Kconfig fragments and board overlays that are all merged into the final output files. + +* In sysbuild, there can either be a Kconfig fragment overlay, or replacement for the whole application configuration directory. + +In sysbuild, if an image application configuration directory is created then it must include all the required files for that image, as none of the original application configuration files will be used. +Sysbuild includes support for :ref:`application-file-suffixes` in applications, and it can also use :ref:`sysbuild_file_suffixes`. + +Example for MCUboot +=================== + +The following table shows how to add custom MCUboot configuration for a project. +The ``sysbuild`` folder must be created in the application's folder: + ++--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ +| File | Description | ++==============================================================+===========================================================================================================================================+ +| ``sysbuild/mcuboot/prj.conf`` | Copy of ``boot/zephyr/prj.conf`` from the MCUboot repository, this may have additional changes for this specific application | ++--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ +| ``sysbuild/mcuboot/prj_release.conf`` | Modification of prj.conf with changes for a release configuration (can be selected using ``-DFILE_SUFFIX=release``) | ++--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ +| ``sysbuild/mcuboot/app.overlay`` | Copy of ``boot/zephyr/app.overlay`` from the MCUboot repository | ++--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ +| ``sysbuild/mcuboot/boards/nrf52840dk_nrf52840.conf`` | Kconfig fragment for the ``nrf52840dk/nrf52840`` board target | ++--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ +| ``sysbuild/mcuboot/boards/nrf52840dk_nrf52840.overlay`` | DTS overlay for the ``nrf52840dk/nrf52840`` board target, note: used **instead** of app.overlay, not with as child/parent used to do | ++--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ +| ``sysbuild/mcuboot/boards/nrf9160dk_nrf9160_0_14_0.overlay`` | DTS overlay for the ``nrf9160dk@0.14.0/nrf9160`` board target, note: used **instead** of app.overlay, not with as child/parent used to do | ++--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ + +.. _child_parent_to_sysbuild_migration_scope_changes: + +Scope changes +============= + +In child/parent images, the application controlled all images, so variables without a prefix would apply to the main application only. +In Sysbuild, elements like file suffixes, shields, and snippets without an image prefix will be applied **globally** to all images. +To apply them to a single image, they must be prefixed with the image name. +Without doing this, projects with multiple images (for example, those with MCUboot) might fail to build due to invalid configuration for other images. + ++-------------------------------+----------------------------------+-----------------------+ +| Configuration parameter | Child/parent | Sysbuild | ++===============================+==================================+=======================+ +| ``-DFILE_SUFFIX=...`` | Applies to main application only | Applies to all images | ++-------------------------------+----------------------------------+-----------------------+ +| ``-D_FILE_SUFFIX=...`` | Applies to only | ++-------------------------------+----------------------------------+-----------------------+ +| ``-DSNIPPET=...`` | Applies to main application only | Applies to all images | ++-------------------------------+----------------------------------+-----------------------+ +| ``-D_SNIPPET=...`` | Applies to only | ++-------------------------------+----------------------------------+-----------------------+ +| ``-DSHIELD=...`` | Applies to main application only | Applies to all images | ++-------------------------------+----------------------------------+-----------------------+ +| ``-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: + +* Without a prefix, they will be applied to the main application only. + +* With a prefix, they will apply to that specific image only. + +.. _child_parent_to_sysbuild_migration_building: + +Building with sysbuild +====================== + +With |NCS| 2.7, building with ``west`` will use sysbuild by default in |NCS| repositories. +To maintain compatibility with child/parent images, out-of-tree applications will not use sysbuild by default. +Twister does not inherit this change and will not use sysbuild unless tests are updated. +Similarly, CMake will not configure projects using sysbuild unless the invocation command is updated. + +.. note:: + + Sysbuild can optionally be set as the default when using west. + This means that unless west is ran with ``--no-sysbuild`` then it will always use sysbuild + + .. code-block:: shell + + west config build.sysbuild True + +.. tabs:: + + .. group-tab:: west (sysbuild) + + West can build a specific project using sysbuild with the following command: + + .. code-block:: console + + west build -b --sysbuild + + .. group-tab:: west (child/parent image) + + West can build a specific project using child/parent image with the following command: + + .. code-block:: console + + west build -b --no-sysbuild + + .. note:: + + This is deprecated in |NCS| 2.7 and support will be removed in |NCS| 2.9 + + .. group-tab:: cmake (sysbuild) + + CMake can be used to configure a specific project using sysbuild image with the following command: + + .. code-block:: console + + cmake -GNinja -DBOARD= -DAPP_DIR= /share/sysbuild + + .. 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 + + cmake -GNinja -DBOARD= + + .. note:: + + This is deprecated in |NCS| 2.7 and support will be removed in |NCS| 2.9 + + .. group-tab:: twister (sysbuild) + + Twister test cases can build using sysbuild with the following: + + .. code-block:: yaml + + sysbuild: true + + .. group-tab:: twister (child/parent image) + + Twister test cases can build using child/parent image with the following: + + .. code-block:: yaml + + sysbuild: false + + .. note:: + + This is deprecated in |NCS| 2.7 and support will be removed in |NCS| 2.9 + +.. _child_parent_to_sysbuild_forced_kconfig_options: + +Forced Kconfig options +====================== + +As sysbuild deals with configuration of features for some features and propagating this information to other images, some Kconfig options in applications will be forcefully overwritten by sysbuild, for details on these options and how to set them from sysbuild, check the :ref:`sysbuild_forced_options` section. + +.. _child_parent_to_sysbuild_migration_incompatibilities: + +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: + +* Using pre-built HEX files for images (like MCUboot). + All images in a project will be built from source + + As a workaround for this, you can first build a project, then use ``mergehex`` manually to merge the project output HEX file with a previously-generated HEX file in overwrite mode to replace that firmware in the output image. + +* Building an image for the nRF5340 network core as the primary image and including an application core image + + Projects should be updated to first build for the application core and then add the network image. + +* Moved and confirmed output files when MCUboot is enabled + These files are not generated when using sysbuild so would need to be manually generated. + +* OpenSSL/custom signing for MCUboot images + This is not supported out of the box using sysbuild, but a custom signing script can be used which can be generated to use OpenSSL or a custom signing method, see :zephyr_file:`cmake/sysbuild/image_signing.cmake` for how signing is performed in |NCS|, this can be set from a module using the following code as an example: + + .. code-block:: cmake + + function(${SYSBUILD_CURRENT_MODULE_NAME}_pre_cmake) + set(_SIGNING_SCRIPT "${ZEPHYR_MY_CUSTOM_MODULE_MODULE_DIR}//image_signing.cmake" CACHE INTERNAL "MCUboot signing script" FORCE) + endfunction() + + This must run after the |NCS| sysbuild cmake code has ran with a dependency, using a :file:`zephyr/module.yml` file similar to: + + .. code-block:: yaml + + build: + sysbuild-cmake: sysbuild + depends: + - hal_nordic diff --git a/snippets/nrf70-fw-patch-ext-flash/fw-patch-ext-flash.overlay b/snippets/nrf70-fw-patch-ext-flash/fw-patch-ext-flash.overlay index a8c45cc8dc88..769a731e4a2c 100644 --- a/snippets/nrf70-fw-patch-ext-flash/fw-patch-ext-flash.overlay +++ b/snippets/nrf70-fw-patch-ext-flash/fw-patch-ext-flash.overlay @@ -5,14 +5,14 @@ &qspi { mx25r64: mx25r6435f@0 { - partitions { - compatible = "fixed-partitions"; - #address-cells = <1>; - #size-cells = <1>; - nrf70_fw_partition: partition@0 { - label = "nrf70_fw_partition"; - reg = <0x0 DT_SIZE_K(128)>; + partitions { + compatible = "fixed-partitions"; + #address-cells = <1>; + #size-cells = <1>; + nrf70_fw_partition: partition@0 { + label = "nrf70_fw_partition"; + reg = <0x0 DT_SIZE_K(128)>; + }; }; }; - }; }; diff --git a/sysbuild/Kconfig.sysbuild b/sysbuild/Kconfig.sysbuild index 983b16931723..bc0914ccfaa2 100644 --- a/sysbuild/Kconfig.sysbuild +++ b/sysbuild/Kconfig.sysbuild @@ -25,26 +25,21 @@ config PM_MCUBOOT_PAD different padding size, then this value must be updated to correspond to the value in the static partition file. -config PM_OVERRIDE_EXTERNAL_DRIVER_CHECK - bool "Override external driver check" - help - When enabled, will include all external flash stroage areas without - being gated on the NORDIC_QSPI_NOR Kconfig, can be enabled to use - non-QSPI external flash chips from partition manager. - config PM_EXTERNAL_FLASH_MCUBOOT_SECONDARY bool "Place MCUboot secondary in external flash" depends on BOOTLOADER_MCUBOOT - # Only depend on the chosen for the parent image. The value of this - # option is propagated to the MCUboot child imag#e automatically. -# depends on PM_EXTERNAL_FLASH_ENABLED || MCUBOOT -# default y if BOOTLOADER_MCUBOOT -# imply ADD_MCUBOOT_MEDIATE_SIM_FLASH_DTS help Place the secondary partition of MCUboot in the external flash instead of the internal flash. This option should only be enabled by the user in the parent image. +config PM_OVERRIDE_EXTERNAL_DRIVER_CHECK + bool "Override external driver check" + help + When enabled, will include all external flash stroage areas without + being gated on the NORDIC_QSPI_NOR Kconfig, can be enabled to use + non-QSPI external flash chips from partition manager. + endif # PARTITION_MANAGER config BUILD_OUTPUT_BIN