diff --git a/applications/nrf5340_audio/tools/buildprog/program.py b/applications/nrf5340_audio/tools/buildprog/program.py index a75b80c4053b..f913c64965e6 100644 --- a/applications/nrf5340_audio/tools/buildprog/program.py +++ b/applications/nrf5340_audio/tools/buildprog/program.py @@ -41,7 +41,7 @@ def __populate_uicr(dev): def _program_cores(dev: DeviceConf) -> int: if dev.core_net_programmed == SelectFlags.TBD: if not path.isfile(dev.hex_path_net): - print("NET core hex not found. Built as APP core child image.") + print("NET core hex not found. Built as APP core image.") return 1 print(f"Programming net core on: {dev}") diff --git a/cmake/extensions.cmake b/cmake/extensions.cmake index a0afdd351ad7..c171ed0be5a9 100644 --- a/cmake/extensions.cmake +++ b/cmake/extensions.cmake @@ -107,7 +107,7 @@ endfunction() # # NCS file function extension. # This function extends the zephyr_file(CONF_FILES ) function to support -# switching BOARD for child images. +# switching BOARD for images. # # It also supports lookup of static partition manager files for based on # the board name, revision, and the current build type. @@ -349,7 +349,7 @@ endfunction() # Usage # get_shared( IMAGE PROPERTY ) # -# Get a property value defined by the child image or domain if it exists. +# Get a property value defined by an image or domain if it exists. # The property value will be returned in the variable referenced by . # # Example usage 'get_shared(prop_value IMAGE child PROPERTY property_in_child)' diff --git a/cmake/sysbuild/partition_manager.cmake b/cmake/sysbuild/partition_manager.cmake index dac8cda72dd0..d98e4c665679 100644 --- a/cmake/sysbuild/partition_manager.cmake +++ b/cmake/sysbuild/partition_manager.cmake @@ -366,24 +366,11 @@ function(update_runner) sysbuild_cache(CREATE APPLICATION ${RUNNER_IMAGE}) endfunction() - # APP is a special domain which is handled differently. # Remove it from the list. get_property(PM_DOMAINS GLOBAL PROPERTY PM_DOMAINS) list(REMOVE_ITEM PM_DOMAINS APP) -## Check if current image is the dynamic partition in its domain. -## I.E. it is the only partition without a statically configured size in this -## domain. This is equivalent to the 'app' partition in the root domain. -## -## The dynamic partition is specified by the parent domain (i.e. the domain -## which creates the current domain through 'create_domain_image()'. -#if(DEFINED ${DOMAIN}_PM_DOMAIN_DYNAMIC_PARTITION -# AND "${IMAGE_NAME}" STREQUAL "${${DOMAIN}_PM_DOMAIN_DYNAMIC_PARTITION}" -#) -# set(is_dynamic_partition_in_domain TRUE) -#endif() - get_property(PM_IMAGES GLOBAL PROPERTY PM_IMAGES) get_property(PM_SUBSYS_PREPROCESSED GLOBAL PROPERTY PM_SUBSYS_PREPROCESSED) @@ -391,7 +378,7 @@ get_property(PM_SUBSYS_PREPROCESSED GLOBAL PROPERTY PM_SUBSYS_PREPROCESSED) # # It will be executed if one of the following criteria is true for the # current image: -# - It's a child image, and is the dynamic partition in the domain +# - It's a secondary image, and is the dynamic partition in the domain # - It's the root image, and a static configuration has been provided # - It's the root image, and PM_IMAGES is populated. # - It's the root image, and other domains exist. @@ -410,24 +397,8 @@ else() ) endif() -# Image files, those should be queried from actual image. -# Add the dynamic partition as an image partition. -#set_property(GLOBAL PROPERTY -# ${dynamic_partition}_PM_HEX_FILE -# ${PROJECT_BINARY_DIR}/${KERNEL_HEX_NAME} -# ) -# -#set_property(GLOBAL PROPERTY -# ${dynamic_partition}_PM_TARGET -# ${logical_target_for_zephyr_elf} -# ) - # Prepare the input_files, header_files, and images lists set(generated_path include/generated) -# ToDo: In child image, this happens to each domain parent. -# In parent image, it only happen to direct children, not children of children. -# This must be adjusted into: -# Explicitly add the main dynamic partition image sysbuild_get(${DEFAULT_IMAGE}_input_files IMAGE ${DEFAULT_IMAGE} VAR PM_YML_FILES CACHE) sysbuild_get(${DEFAULT_IMAGE}_binary_dir IMAGE ${DEFAULT_IMAGE} VAR ZEPHYR_BINARY_DIR CACHE) list(APPEND prefixed_images ":${dynamic_partition}") @@ -568,8 +539,6 @@ foreach(d APP ${PM_DOMAINS}) DEFAULT_DRIVER_KCONFIG ${soc_nvs_controller_driver_kc} DOMAIN ${d} ) - - endforeach() sysbuild_get(ext_flash_enabled IMAGE ${DEFAULT_IMAGE} VAR CONFIG_PM_EXTERNAL_FLASH_ENABLED KCONFIG) @@ -623,38 +592,8 @@ partition_manager(IN_FILES ${input_files} REGIONS ${regions}) foreach(d ${PM_DOMAINS}) get_property(image_name GLOBAL PROPERTY DOMAIN_APP_${d}) partition_manager(DOMAIN ${d} IN_FILES ${${d}_input_files} REGIONS ${${d}_regions}) - -# foreach(d ${PM_DOMAINS}) -# # Should list be adjust to domain image list ? -# # In files must be adjust according to image being built/ -# partition_manager(DOMAIN ${d} IN_FILES ${${d}_input_files} REGIONS ${domain_regions}) -# endforeach() endforeach() -# Start - Code related to network core update. Multi image updates are part of NCSDK-17807 -#if (CONFIG_SECURE_BOOT AND CONFIG_BOOTLOADER_MCUBOOT) -# # Create symbols for the offsets required for moving test update hex files -# # to MCUBoots secondary slot. This is needed because objcopy does not -# # support arithmetic expressions as argument (e.g. '0x100+0x200'), and all -# # of the symbols used to generate the offset is only available as a -# # generator expression when MCUBoots cmake code exectues. This because -# # partition manager is performed as the last step in the configuration stage. -# math(EXPR s0_offset "${PM_MCUBOOT_SECONDARY_ADDRESS} - ${PM_S0_ADDRESS}") -# math(EXPR s1_offset "${PM_MCUBOOT_SECONDARY_ADDRESS} - ${PM_S1_ADDRESS}") -# -# set_property( -# TARGET partition_manager -# PROPERTY s0_TO_SECONDARY -# ${s0_offset} -# ) -# set_property( -# TARGET partition_manager -# PROPERTY s1_TO_SECONDARY -# ${s1_offset} -# ) -#endif() -# End - Code related to network core update. Multi image updates are part of NCSDK-17807 - # Always add main partition file to list. list(APPEND pm_out_partition_file ${APPLICATION_BINARY_DIR}/partitions.yml) list(APPEND pm_out_region_file ${APPLICATION_BINARY_DIR}/regions.yml) @@ -719,78 +658,6 @@ else() endif() endforeach() -# Start - Code related to network core update. Multi image updates are part of NCSDK-17807 -# if (CONFIG_BOOTLOADER_MCUBOOT) -# # Create symbols for the offset required for moving the signed network -# # core application to MCUBoots secondary slot. This is needed -# # because objcopy does not support arithmetic expressions as argument -# # (e.g. '0x100+0x200'), and all of the symbols used to generate the -# # offset are only available as a generator expression when MCUBoots -# # cmake code executes. -# -# # Check if a signed version of the network core application is defined. -# # If so, this indicates that we need to support firmware updates on the -# # network core. This again means that we should generate the required -# # hex files. -# get_shared(cpunet_signed_app_hex IMAGE CPUNET PROPERTY PM_SIGNED_APP_HEX) -# -# if (CONFIG_NRF53_UPGRADE_NETWORK_CORE -# AND DEFINED cpunet_signed_app_hex) -# # The address coming from other domains are not available in this scope -# # since it is imported by a different domain. Hence, it must be fetched -# # through the 'partition_manager' target. -# get_target_property(net_app_addr partition_manager CPUNET_PM_APP_ADDRESS) -# -# get_shared( -# mcuboot_NRF53_MULTI_IMAGE_UPDATE -# IMAGE mcuboot -# PROPERTY NRF53_MULTI_IMAGE_UPDATE -# ) -# -# # Check if multi image updates are enabled, in which case we need -# # to use the "_1" variant of the secondary partition for the network core. -# if(DEFINED mcuboot_NRF53_MULTI_IMAGE_UPDATE) -# set(sec_slot_idx "_1") -# endif() -# -# # Calculate the offset from the address which the net/app core app is linked -# # against to the secondary slot. We need these values to generate hex files -# # which targets the secondary slot. -# math(EXPR net_app_to_secondary -# "${xip_addr} \ -# + ${PM_MCUBOOT_SECONDARY${sec_slot_idx}_ADDRESS} \ -# - ${net_app_addr} \ -# + ${PM_MCUBOOT_PAD_SIZE}" -# ) -# -# set_property( -# TARGET partition_manager -# PROPERTY net_app_TO_SECONDARY -# ${net_app_to_secondary} -# ) -# -# # This value is needed by `imgtool.py` which is used to sign the images. -# set_property( -# TARGET partition_manager -# PROPERTY net_app_slot_size -# ${PM_MCUBOOT_SECONDARY${sec_slot_idx}_SIZE} -# ) -# endif() -# -# math(EXPR app_to_secondary -# "${xip_addr} \ -# + ${PM_MCUBOOT_SECONDARY_ADDRESS} \ -# - ${PM_MCUBOOT_PRIMARY_ADDRESS}" -# ) -# -# set_property( -# TARGET partition_manager -# PROPERTY app_TO_SECONDARY -# ${app_to_secondary} -# ) -# endif() -# End - Code related to network core update. Multi image updates are part of NCSDK-17807 - # Explicitly add the root image domain hex file to the list list(APPEND domain_hex_files ${CMAKE_BINARY_DIR}/${merged}.hex) list(APPEND global_hex_depends ${merged}_hex) @@ -838,30 +705,6 @@ else() COMMAND_EXPAND_LISTS ) -# ToDo: do we still want to merge hex files for all the domains ? -# if (PM_DOMAINS) -# # For convenience, generate global hex file containing all domains' hex -# # files. -# set(final_merged ${PROJECT_BINARY_DIR}/merged_domains.hex) -# -# # Add command to merge files. -# add_custom_command( -# OUTPUT ${final_merged} -# COMMAND -# ${PYTHON_EXECUTABLE} -# ${ZEPHYR_BASE}/scripts/build/mergehex.py -# -o ${final_merged} -# ${domain_hex_files} -# DEPENDS -# ${domain_hex_files} -# ${global_hex_depends} -# ) -# -# # Wrapper target for the merge command. -# add_custom_target(merged_domains_hex ALL DEPENDS ${final_merged}) -# endif() - set(ZEPHYR_RUNNER_CONFIG_KERNEL_HEX "${final_merged}" CACHE STRING "Path to merged image in Intel Hex format" FORCE) - endif() diff --git a/doc/_utils/redirects.py b/doc/_utils/redirects.py index 2c6a321af43d..33de6be34207 100644 --- a/doc/_utils/redirects.py +++ b/doc/_utils/redirects.py @@ -91,9 +91,10 @@ ("config_and_build/companion_components", "app_dev/companion_components"), # Using companion components ("config_and_build/output_build_files", "app_dev/config_and_build/output_build_files"), # Output build files (image files) ("config_and_build/configuring_app/output_build_files", "app_dev/config_and_build/output_build_files"), - ("ug_multi_image", "app_dev/config_and_build/multi_image"), # Multi-image build using child and parent images - ("app_dev/multi_image/index", "app_dev/config_and_build/multi_image"), - ("config_and_build/multi_image", "app_dev/config_and_build/multi_image"), + ("ug_multi_image", "app_dev/config_and_build/sysbuild/index"), # Multi-image build using child and parent images (removed in v3.0.0) + ("app_dev/multi_image/index", "app_dev/config_and_build/sysbuild/index"), + ("config_and_build/multi_image", "app_dev/config_and_build/sysbuild/index"), + ("app_dev/config_and_build/multi_image", "app_dev/config_and_build/sysbuild/index"), ("ug_fw_update", "app_dev/bootloaders_dfu/index"), # Firmware updates (removed after 2.5.0) ("app_dev/bootloaders_and_dfu/fw_update", "app_dev/bootloaders_dfu/index"), ("config_and_build/bootloaders_and_dfu/fw_update", "app_dev/bootloaders_dfu/index"), @@ -112,13 +113,14 @@ ("config_and_build/bootloaders_dfu/mcuboot_nsib/bootloader_quick_start", "app_dev/bootloaders_dfu/mcuboot_nsib/bootloader_quick_start"), ("config_and_build/bootloaders/bootloader_adding_sysbuild", "app_dev/bootloaders_dfu/mcuboot_nsib/bootloader_adding_sysbuild"), # Enabling a bootloader chain using sysbuild ("config_and_build/bootloaders_dfu/mcuboot_nsib/bootloader_adding_sysbuild", "app_dev/bootloaders_dfu/mcuboot_nsib/bootloader_adding_sysbuild"), - ("ug_bootloader_adding", "app_dev/bootloaders_dfu/mcuboot_nsib/bootloader_adding"), # "Enabling a bootloader chain using child and parent images (deprecated)" - ("app_dev/bootloaders_and_dfu/bootloader_adding", "app_dev/bootloaders_dfu/mcuboot_nsib/bootloader_adding"), - ("config_and_build/bootloaders_and_dfu/bootloader_adding", "app_dev/bootloaders_dfu/mcuboot_nsib/bootloader_adding"), - ("config_and_build/bootloaders/bootloader_adding", "app_dev/bootloaders_dfu/mcuboot_nsib/bootloader_adding"), - ("config_and_build/bootloaders_dfu/mcuboot_nsib/bootloader_adding", "app_dev/bootloaders_dfu/mcuboot_nsib/bootloader_adding"), + ("ug_bootloader_adding", "app_dev/bootloaders_dfu/mcuboot_nsib/bootloader_adding_sysbuild"), # "Enabling a bootloader chain using child and parent images (removed in v3.0.0)" + ("app_dev/bootloaders_and_dfu/bootloader_adding", "app_dev/bootloaders_dfu/mcuboot_nsib/bootloader_adding_sysbuild"), + ("config_and_build/bootloaders_and_dfu/bootloader_adding", "app_dev/bootloaders_dfu/mcuboot_nsib/bootloader_adding_sysbuild"), + ("config_and_build/bootloaders/bootloader_adding", "app_dev/bootloaders_dfu/mcuboot_nsib/bootloader_adding_sysbuild"), + ("config_and_build/bootloaders_dfu/mcuboot_nsib/bootloader_adding", "app_dev/bootloaders_dfu/mcuboot_nsib/bootloader_adding_sysbuild"), ("ug_bootloader", "app_dev/bootloaders_dfu/mcuboot_nsib/bootloader"), # Secure bootloader chain ("app_dev/bootloaders_and_dfu/bootloader", "app_dev/bootloaders_dfu/mcuboot_nsib/bootloader"), + ("app_dev/bootloaders_dfu/mcuboot_nsib/bootloader_adding", "app_dev/bootloaders_dfu/mcuboot_nsib/bootloader_adding_sysbuild"), ("config_and_build/bootloaders_and_dfu/bootloader", "app_dev/bootloaders_dfu/mcuboot_nsib/bootloader"), ("config_and_build/bootloaders/bootloader", "app_dev/bootloaders_dfu/mcuboot_nsib/bootloader"), ("config_and_build/bootloaders_dfu/mcuboot_nsib/bootloader", "app_dev/bootloaders_dfu/mcuboot_nsib/bootloader"), @@ -222,11 +224,12 @@ ("device_guides/nrf53/features_nrf53", "app_dev/device_guides/nrf53/features_nrf53"), # Features of nRF53 Series ("device_guides/nrf53/building_nrf53", "app_dev/device_guides/nrf53/building_nrf53"), # Building and programming with nRF53 Series ("device_guides/nrf53/fota_update_nrf5340", "app_dev/device_guides/nrf53/fota_update_nrf5340"), # FOTA updates with nRF5340 DK - ("device_guides/nrf53/multi_image_nrf5340", "app_dev/device_guides/nrf53/multi_image_nrf5340"), # Multi-image builds on the nRF5340 DK using child and parent images + ("device_guides/nrf53/multi_image_nrf5340", "app_dev/config_and_build/sysbuild/index"), # Multi-image builds on the nRF5340 DK using child and parent images (removed in v3.0.0) ("device_guides/nrf53/simultaneous_multi_image_dfu_nrf5340", "app_dev/device_guides/nrf53/simultaneous_multi_image_dfu_nrf5340"), # Simultaneous multi-image DFU with nRF5340 DK ("device_guides/nrf53/serial_recovery", "app_dev/device_guides/nrf53/serial_recovery"), # MCUboot’s serial recovery of the networking core image ("device_guides/nrf53/logging_nrf5340", "app_dev/device_guides/nrf53/logging_nrf5340"), # Getting logging output with nRF5340 DK ("device_guides/nrf53/thingy53_application_guide", "app_dev/device_guides/thingy53/thingy53_application_guide"), # Application guide for Thingy:53 + ("app_dev/device_guides/nrf53/multi_image_nrf5340", "app_dev/config_and_build/sysbuild/index"), ("app_dev/device_guides/nrf53/thingy53_application_guide", "app_dev/device_guides/thingy53/thingy53_application_guide"), ("device_guides/working_with_nrf/nrf53/qspi_xip_guide", "app_dev/device_guides/nrf53/qspi_xip_guide_nrf5340"), # External execute in place (XIP) configuration on the nRF5340 SoC ("device_guides/nrf53/qspi_xip_guide_nrf5340", "app_dev/device_guides/nrf53/qspi_xip_guide_nrf5340"), diff --git a/doc/_zoomin/ncs.tags.yml b/doc/_zoomin/ncs.tags.yml index a3e934b56f04..d2f0d544bc5c 100644 --- a/doc/_zoomin/ncs.tags.yml +++ b/doc/_zoomin/ncs.tags.yml @@ -84,7 +84,6 @@ mapping_topics: "development-kits", "evaluation-kits", "prototyping-platforms"] - nrf/app_dev/config_and_build/sysbuild/*.html: ["applications", "samples", "kconfig"] - - nrf/app_dev/config_and_build/multi_image.html: ["applications", "samples", "kconfig"] - nrf/app_dev/config_and_build/building.html: ["applications", "samples", "development-kits", "evaluation-kits", "prototyping-platforms", "kconfig"] @@ -127,7 +126,6 @@ mapping_topics: "nrf52832", "nrf52820", "nrf52811", "nrf52810", "nrf52805", "nrf21540", "npm1100", "npm1300", "npm6001", "applications"] - - nrf/app_dev/bootloaders_dfu/mcuboot_nsib/bootloader_adding.html: ["kconfig"] - nrf/app_dev/bootloaders_dfu/mcuboot_nsib/bootloader_config.html: ["kconfig"] - nrf/app_dev/bootloaders_dfu/qspi_xip_split_image.html: ["nrf52840", "thingy53", "nrf5340"] - nrf/app_dev/bootloaders_dfu/dfu_tools_mcumgr_cli.html: ["nrf91-series", "nrf70-series", @@ -214,7 +212,6 @@ mapping_topics: - nrf/app_dev/device_guides/nrf53/building_nrf53.html: ["nrf5340", "development-kits", "nrf-connect-vsc"] - nrf/app_dev/device_guides/nrf53/fota_update_nrf5340.html: ["nrf5340", "development-kits"] - - nrf/app_dev/device_guides/nrf53/multi_image_nrf5340.html: ["nrf5340", "development-kits"] - nrf/app_dev/device_guides/nrf53/simultaneous_multi_image_dfu_nrf5340.html: ["nrf5340", "development-kits"] - /nrf/app_dev/device_guides/nrf53/serial_recovery.html: ["nrf5340", "development-kits"] diff --git a/doc/nrf/app_dev/bootloaders_dfu/mcuboot_nsib/bootloader.rst b/doc/nrf/app_dev/bootloaders_dfu/mcuboot_nsib/bootloader.rst index b0b017732953..8fd41d1a4e40 100644 --- a/doc/nrf/app_dev/bootloaders_dfu/mcuboot_nsib/bootloader.rst +++ b/doc/nrf/app_dev/bootloaders_dfu/mcuboot_nsib/bootloader.rst @@ -67,8 +67,7 @@ The |NCS| currently supports two implementations: .. figure:: ../images/bootloader_memory_layout.svg :alt: Memory layout -By default, building an application with any bootloader configuration creates a :ref:`multi-image build `, where the :ref:`partition_manager` manages its memory partitions. -In this case, bootloaders are built as child images. +By default, building an application with any bootloader configuration uses :ref:`sysbuild` to build multiple image, where the :ref:`partition_manager` manages its memory partitions. When building an application with :ref:`Cortex-M Security Extensions (CMSE) enabled `, then :ref:`Trusted Firmware-M (TF-M) ` is built with the image automatically. From the bootloader perspective, the TF-M is part of the booted application image. @@ -96,7 +95,7 @@ More specifically, the immutable bootloader always performs the following steps The next stage in the boot chain can either be an application or another bootloader. Firmware images have a version number, and the bootloader will select the slot with the latest firmware. - For more information about creating a second-stage bootloader, see :ref:`ug_bootloader_adding_upgradable`. + For more information about creating a second-stage bootloader, see :ref:`ug_bootloader_adding_sysbuild_upgradable`. #. Verification of the next stage in the boot chain. diff --git a/doc/nrf/app_dev/bootloaders_dfu/mcuboot_nsib/bootloader_adding.rst b/doc/nrf/app_dev/bootloaders_dfu/mcuboot_nsib/bootloader_adding.rst deleted file mode 100644 index 7d0f1dbc480d..000000000000 --- a/doc/nrf/app_dev/bootloaders_dfu/mcuboot_nsib/bootloader_adding.rst +++ /dev/null @@ -1,410 +0,0 @@ -.. _ug_bootloader_adding: - -Enabling a bootloader chain using child and parent images (deprecated) -###################################################################### - -.. note:: - This feature is now deprecated. - See :ref:`ug_bootloader_adding_sysbuild`. - -.. contents:: - :local: - :depth: 2 - -You can add a bootloader chain to an application in the following ways: - -* Permanently: - - * Using Kconfig fragments. - * Using :file:`prj.conf` Kconfig project configuration files. - -* Temporarily (for a single build): - - * Using :ref:`one-time CMake arguments `. - * Using :ref:`zephyr: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. - -Both Kconfig fragments and Kconfig project configuration files use the same Kconfig syntax for 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_immutable: - -Adding an immutable bootloader -****************************** - -The following sections describe how to add either |NSIB| or MCUboot as an immutable bootloader. - -.. _ug_bootloader_adding_immutable_b0: - -Adding |NSIB| as an immutable bootloader -======================================== - -To build |NSIB| with a Zephyr or |NCS| sample, enable the :kconfig:option:`CONFIG_SECURE_BOOT` in the application's :file:`prj.conf` file, in an associated Kconfig fragment, or using the command line: - -.. code-block:: console - - west build -b nrf52840dk/nrf52840 zephyr/samples/hello_world -- -DCONFIG_SECURE_BOOT=y - -|how_to_configure| - -Like other child 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 -- \ - -DCONFIG_SECURE_BOOT=y \ - -Db0_CONF_FILE=prj_minimal.conf - -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_immutable_keys: - -Adding a custom signature key file -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To add a signature key file to this bootloader, set the :kconfig:option:`CONFIG_SB_SIGNING_KEY_FILE` option in the application's :file:`prj.conf` file, in an associated Kconfig fragment, or using the command line: - -.. tabs:: - - .. group-tab:: Kconfig / prj.conf - - .. code-block:: console - - CONFIG_SB_SIGNING_KEY_FILE="priv.pem" - - .. group-tab:: Command line - - .. code-block:: console - - -DCONFIG_SB_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 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). - - * If the :file:`prj.conf` file is external to the directory, the key's location is determined relative to the application directory, not to the configuration file. - -* 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 / prj.conf - - .. code-block:: console - - CONFIG_SB_SIGNING_KEY_FILE="../../_keys/priv.pem" - - Or - - .. code-block:: console - - CONFIG_SB_SIGNING_KEY_FILE="/home/user/ncs/_keys/priv.pem" - - .. group-tab:: Command line - - .. code-block:: console - - -DCONFIG_SB_SIGNING_KEY_FILE=\"../../_keys/priv.pem\" - - Or - - .. code-block:: console - - -DCONFIG_SB_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 - - -DCONFIG_SB_SIGNING_KEY_FILE=\"$NCS/_keys/priv.pem\" - -.. note:: - - The public key string must be an absolute path to the location of the public key 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:`prj.conf` file or Kconfig fragment, 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/subsys/bootloader/Kconfig`. - -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:`CONFIG_SB_SIGNING_OPENSSL` Kconfig option. -* :ref:`Using a custom command ` - Uses the :kconfig:option:`CONFIG_SB_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_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:`prj.conf` file, in an associated Kconfig fragment, or using the command line: - -.. tabs:: - - .. group-tab:: Kconfig / prj.conf - - .. code-block:: console - - CONFIG_SECURE_BOOT=y - CONFIG_SB_SIGNING_CUSTOM=y - CONFIG_SB_SIGNING_PUBLIC_KEY="/path/to/pub.pem" - CONFIG_SB_SIGNING_COMMAND="my_command" - - .. group-tab:: Command line - - .. code-block:: console - - west build -b nrf52840dk/nrf52840 zephyr/samples/hello_world -- \ - -DCONFIG_SECURE_BOOT=y \ - -DCONFIG_SB_SIGNING_CUSTOM=y \ - -DCONFIG_SB_SIGNING_PUBLIC_KEY=\"/path/to/pub.pem\" \ - -DCONFIG_SB_SIGNING_COMMAND=\"my_command\" - - Escaped quotations avoid malformed-string warnings from Kconfig. - -.. note:: - - The public key string must be an absolute path to the location of the public key file, as mentioned previously in :ref:`ug_bootloader_adding_immutable_keys`. - -See :kconfig:option:`CONFIG_SB_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:`CONFIG_SB_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:`prj.conf` file or Kconfig fragment 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_immutable_mcuboot: - -Adding MCUboot as an immutable bootloader -========================================= - -To build :doc:`MCUboot ` with a Zephyr or |NCS| sample, enable the :kconfig:option:`CONFIG_BOOTLOADER_MCUBOOT` in the application's :file:`prj.conf` file, an associated Kconfig fragment, or using the command line: - -.. code-block:: console - - west build -b nrf52840dk/nrf52840 zephyr/samples/hello_world -- -DCONFIG_BOOTLOADER_MCUBOOT=y - -|how_to_configure| -Like other child 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_immutable_mcuboot_keys: - -Adding a custom signature key file -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To pass the signature key file into the MCUboot image, set its :kconfig:option:`CONFIG_BOOT_SIGNATURE_KEY_FILE` option to the selected private key file. -You can set the option in :file:`bootloader/mcuboot/boot/zephyr/prj.conf`, an associated Kconfig fragment, or using the command line: - -.. tabs:: - - .. group-tab:: Kconfig / prj.conf - - .. code-block:: console - - CONFIG_BOOT_SIGNATURE_KEY_FILE="priv.pem" - - .. group-tab:: Command line - - .. code-block:: console - - -Dmcuboot_CONFIG_BOOT_SIGNATURE_KEY_FILE=\"priv.pem\" - - Escaped quotations avoid malformed-string warnings from Kconfig. - -The path of the key works as :ref:`described above ` for |NSIB|, except the application directory for relative pathing is considered to be :file:`bootloader/mcuboot`. - -See :ref:`ug_fw_update_keys` for information on how to generate custom keys for a project. - -We recommend you also set the associated configuration for a key type to ensure MCUboot compiles the public key into its image correctly. - -.. code-block:: console - - west build -b nrf52840dk/nrf52840 zephyr/samples/hello_world -- \ - -DCONFIG_BOOTLOADER_MCUBOOT=y \ - -Dmcuboot_CONFIG_BOOT_SIGNATURE_KEY_FILE=\"../../priv-ecdsa256.pem\" \ - -Dmcuboot_CONFIG_BOOT_SIGNATURE_TYPE_ECDSA_P256=y - -You can find specific configuration options for keys with this bootloader in :file:`bootloader/mcuboot/boot/zephyr/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_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_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:`CONFIG_BOOTLOADER_MCUBOOT` Kconfig option with either the build command or in the application's :file:`prj.conf` file: - - .. code-block:: - - west build -b nrf52840dk/nrf52840 zephyr/samples/hello_world -- \ - -DCONFIG_SECURE_BOOT=y \ - -DCONFIG_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 -- \ - -DCONFIG_BOOTLOADER_MCUBOOT=y \ - -DCONFIG_SECURE_BOOT=y \ - -Dmcuboot_CONF_FILE=prj_minimal.conf \ - -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_presigned_variants: - -Generating pre-signed variants -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enable the :kconfig:option:`CONFIG_BUILD_S1_VARIANT` Kconfig option when building the upgradable bootloader to automatically generate :ref:`pre-signed variants ` of the image for both slots: - -.. code-block:: - - west build -b nrf52840dk/nrf52840 zephyr/samples/hello_world -- \ - -DCONFIG_SECURE_BOOT=y \ - -DCONFIG_BOOTLOADER_MCUBOOT=y \ - -DCONFIG_BUILD_S1_VARIANT=y - -This is a necessary step for creating application update images for use with :ref:`ug_fw_update`. - -The S1 variant is built as a separate child image called ``s1_image``. -For this reason, any modifications to the configuration of the S1 variant must be done to the ``s1_image`` child image. -By default, this child image is an exact duplicate of the original 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 ``s1_image`` must be bigger than the one for original image. - -.. _ug_bootloader_testing: - -Testing the bootloader chain -**************************** - -To test either of the bootloaders and the secure bootloader chain, build and program them with any sample as described in :ref:`Adding a bootloader chain `. - -By default, both |NSIB| and MCUboot print information to their serial output on boot. -This output includes information about the validation of images in its slots, as well as firmware-specific information if using :kconfig:option:`CONFIG_FW_INFO` with the |NSIB|. -To see this output: - -1. |connect_terminal| -#. Reset the development kit. -#. Observe that each bootloader in the chain prints its information upon boot (some values may vary by build): - -.. tabs:: - - .. tab:: |NSIB| - - .. code-block:: - - Attempting to boot slot 0. - Attempting to boot from address 0x9000. - Verifying signature against key 0. - Hash: 0xc0...71 - Firmware signature verified. - Firmware version 1 - Setting monotonic counter (version: 1, slot: 0) - - .. tab:: MCUboot - - .. code-block:: - - [00:00:00.359,039] mcuboot: Starting bootloader - [00:00:00.365,295] mcuboot: Primary image: magic=unset, swap_type=0x1, copy_done=0x3, image_ok=0x3 - [00:00:00.375,671] mcuboot: Secondary image: magic=unset, swap_type=0x1, copy_done=0x3, image_ok=0x3 - [00:00:00.386,169] mcuboot: Boot source: none - [00:00:00.391,815] mcuboot: Swap type: none - [00:00:00.420,166] mcuboot: Bootloader chainload address offset: 0xc000 - [00:00:00.428,039] mcuboot: Jumping to the first image slot - -When compiled with minimal configurations that disable logging output, such as ``prj_minimal.conf``, you can disable the bootloader information output altogether or per-bootloader. -Refer to the source code directories of each bootloader to see what minimal configuration options are already available, or add them through a custom Kconfig fragment if desired. diff --git a/doc/nrf/app_dev/bootloaders_dfu/mcuboot_nsib/bootloader_config.rst b/doc/nrf/app_dev/bootloaders_dfu/mcuboot_nsib/bootloader_config.rst index 6abd407b0fb0..e4bfb87c868b 100644 --- a/doc/nrf/app_dev/bootloaders_dfu/mcuboot_nsib/bootloader_config.rst +++ b/doc/nrf/app_dev/bootloaders_dfu/mcuboot_nsib/bootloader_config.rst @@ -20,37 +20,32 @@ However, there are other ways to customize your application using Kconfig option Using custom project configurations *********************************** -You can use custom project configuration options for the associated image, specifying them at build time using :ref:`ug_multi_image_variables`, either temporarily until you clean the build pristinely or permanently. +You can use custom project configuration options for the associated image, specifying them at build time. +These settings are temporary and will remain enabled until you clean the build pristinely. For example, you can temporarily assign custom project configurations for both the bootloaders and a sample application as follows: .. code-block:: console west build -b nrf52840dk/nrf52840 zephyr/samples/hello_world -- \ - -Db0_CONF_FILE=prj_immutable.conf \ - -Dmcuboot_CONF_FILE=prj_upgradable.conf \ - -DCONF_FILE=prj_app.conf - -In the example above, :file:`prj_app.conf` includes :kconfig:option:`CONFIG_SECURE_BOOT` and :kconfig:option:`CONFIG_BOOTLOADER_MCUBOOT` to enable the immutable and upgradable bootloaders by default. -The configuration applied during the command execution is taken into account until you clean the build pristinely. - -Alternatively, you can follow :ref:`ug_multi_image_permanent_changes` and store configuration options for child images in separate files in the application source directory. -For example, in the |NCS| applications and samples that use different :ref:`build types for configuration `, the :file:`child_image` folder in the application source directory is often used to apply :ref:`permanent configuration changes `. + -Db0_FILE_SUFFIX=immutable \ + -Dmcuboot_FILE_SUFFIX=upgradable \ + -Dapp_FILE_SUFFIX=app You can use custom project configuration files in combination with temporary configuration options associated with a single build, set using either the command line or Kconfig fragments. Assigning Kconfig fragments *************************** -You can use Kconfig fragments specific to bootloaders to set temporary configuration options for the associated image, specifying them at build time using :ref:`ug_multi_image_variables`. +You can use Kconfig fragments specific to bootloaders to set temporary configuration options for the associated image, specifying them at build time. -For example, you can assign the :file:`my-custom-fragment.conf` fragment to the |NSIB|, which uses the child name of ``b0``, as follows: +For example, you can assign the :file:`my-custom-fragment.conf` fragment to the |NSIB|, which uses the image name of ``b0``, as follows: .. code-block:: console west build -b nrf52840dk/nrf52840 zephyr/samples/hello_world -- \ - -DCONFIG_SECURE_BOOT=y \ - -DCONFIG_BOOTLOADER_MCUBOOT=y \ + -DSB_CONFIG_SECURE_BOOT_APPCORE=y \ + -DSB_CONFIG_BOOTLOADER_MCUBOOT=y \ -Db0_EXTRA_CONF_FILE=my-custom-fragment.conf In the same way, you can replace ``b0`` with ``mcuboot`` to apply the :file:`my-custom-fragment.conf` fragment to the MCUboot image: @@ -58,13 +53,13 @@ In the same way, you can replace ``b0`` with ``mcuboot`` to apply the :file:`my- .. code-block:: console west build -b nrf52840dk/nrf52840 zephyr/samples/hello_world -- \ - -DCONFIG_SECURE_BOOT=y \ - -DCONFIG_BOOTLOADER_MCUBOOT=y \ + -DSB_CONFIG_SECURE_BOOT_APPCORE=y \ + -DSB_CONFIG_BOOTLOADER_MCUBOOT=y \ -Dmcuboot_EXTRA_CONF_FILE=my-custom-fragment.conf -You can use this method to apply Kconfig fragments to any child image in the build, as well as to set any Kconfig option that can be set from the command line. +You can use this method to apply Kconfig fragments to any image in the build, and set any Kconfig option that is available from the command line. -See :ref:`ug_multi_image_variables` for more information about customizing images using this method. +See :ref:`sysbuild` for more information about customizing images using this method. Customizing partitions ********************** diff --git a/doc/nrf/app_dev/bootloaders_dfu/mcuboot_nsib/bootloader_dfu_image_versions.rst b/doc/nrf/app_dev/bootloaders_dfu/mcuboot_nsib/bootloader_dfu_image_versions.rst index eb7f1d408f6c..9ec1629b8820 100644 --- a/doc/nrf/app_dev/bootloaders_dfu/mcuboot_nsib/bootloader_dfu_image_versions.rst +++ b/doc/nrf/app_dev/bootloaders_dfu/mcuboot_nsib/bootloader_dfu_image_versions.rst @@ -13,7 +13,7 @@ The version can have the form of a single number. Alternatively, it can be based on a more advanced versioning scheme. For example, the semantic versioning scheme uses three numbers to denote major, minor, and patch versions, respectively. -The choice of the versioning scheme depends on the :ref:`selected bootloader ` and the configuration of the bootloader, including :ref:`ug_fw_update_downgrade_protection`. +The choice of the versioning scheme depends on the :ref:`selected bootloader ` and the configuration of the bootloader, including :ref:`ug_fw_update_downgrade_protection`. The |NCS| :ref:`build system ` can automatically handle building of the bootloader together with the application. The build system can also sign the application images and provide versioning information for the images. @@ -30,14 +30,14 @@ This option can refer to two different things: * If NSIB directly boots your application image, the Kconfig option denotes the application image version. * If NSIB boots a secondary-stage bootloader, the Kconfig option denotes the version of the secondary-stage bootloader. In such case, the application is booted by the secondary-state bootloader and the application image version is configured using the versioning scheme of the secondary-stage bootloader. - For example, if you opted for :ref:`ug_bootloader_adding_upgradable_mcuboot`, the application image versioning configuration is described in :ref:`ug_fw_update_image_versions_mcuboot`. + For example, if you opted for :ref:`ug_bootloader_adding_sysbuild_upgradable_mcuboot`, the application image versioning configuration is described in :ref:`ug_fw_update_image_versions_mcuboot`. .. _ug_fw_update_image_versions_mcuboot: Configuring image version with MCUboot ************************************** -To assign a semantic version number to your application when you have opted for booting application directly by the MCUboot bootloader (that is, if you have opted for either :ref:`ug_bootloader_adding_immutable_mcuboot` or :ref:`ug_bootloader_adding_upgradable_mcuboot`), it is recommended to use the :file:`VERSION` file that contains the version information for the application image. +To assign a semantic version number to your application when you have opted for booting application directly by the MCUboot bootloader (that is, if you have opted for either :ref:`ug_bootloader_adding_sysbuild_immutable_mcuboot` or :ref:`ug_bootloader_adding_sysbuild_upgradable_mcuboot`), it is recommended to use the :file:`VERSION` file that contains the version information for the application image. Using a :file:`VERSION` file allows you to independently configure the version value for each build instance of the application. See Zephyr's :ref:`zephyr:app-version-details` page for more information. diff --git a/doc/nrf/app_dev/bootloaders_dfu/mcuboot_nsib/bootloader_downgrade_protection.rst b/doc/nrf/app_dev/bootloaders_dfu/mcuboot_nsib/bootloader_downgrade_protection.rst index 433221050d06..8e8c0a1d5429 100644 --- a/doc/nrf/app_dev/bootloaders_dfu/mcuboot_nsib/bootloader_downgrade_protection.rst +++ b/doc/nrf/app_dev/bootloaders_dfu/mcuboot_nsib/bootloader_downgrade_protection.rst @@ -91,8 +91,8 @@ Downgrade protection using |NSIB| 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. +Special handling is needed when updating the S1 variant of an image when :ref:`ug_bootloader_adding_sysbuild_upgradable`. +See :ref:`ug_bootloader_adding_sysbuild_presigned_variants` for details. See :ref:`zephyr:sysbuild_kconfig_namespacing` in the Zephyr documentation for information on how to set options for built images in sysbuild. .. bootloader_monotonic_counter_nsib_end diff --git a/doc/nrf/app_dev/bootloaders_dfu/mcuboot_nsib/bootloader_mcuboot_nsib.rst b/doc/nrf/app_dev/bootloaders_dfu/mcuboot_nsib/bootloader_mcuboot_nsib.rst index f9604bcb06e9..8000652695fb 100644 --- a/doc/nrf/app_dev/bootloaders_dfu/mcuboot_nsib/bootloader_mcuboot_nsib.rst +++ b/doc/nrf/app_dev/bootloaders_dfu/mcuboot_nsib/bootloader_mcuboot_nsib.rst @@ -19,7 +19,6 @@ Following that, you can :ref:`add an immutable bootloader` to ensure compatibility across different builds. The dynamically generated partitions can change between builds. -This is important also when you use a precompiled HEX file as a child image (sub-image) instead of building it. -In such cases, the newly generated application images may no longer use a partition map that is compatible with the partition map used by the bootloader. -As a result, the newly built application image may not be bootable by the bootloader. The memory partitions that must be defined in the static partition map depend on the selected bootloader chain. For details, see :ref:`ug_bootloader_flash`. @@ -134,7 +131,7 @@ To enable external flash with MCUboot, complete the following steps: #. Enable the :kconfig:option:`CONFIG_PM_EXTERNAL_FLASH_MCUBOOT_SECONDARY` Kconfig option. (Depending on the build configuration, this option will be set to ``y`` automatically.) -#. Update the ``CONFIG_BOOT_MAX_IMG_SECTORS`` `MCUboot Kconfig option`_ accordingly for child images. +#. Update the ``CONFIG_BOOT_MAX_IMG_SECTORS`` `MCUboot Kconfig option`_ accordingly. This option defines the maximum number of image sectors MCUboot can handle, as MCUboot typically increases slot sizes when external flash is enabled. Otherwise the ``CONFIG_BOOT_MAX_IMG_SECTORS`` Kconfig option defaults to the value used for internal flash, and the application may not boot if the value is set too low. @@ -150,8 +147,7 @@ To enable external flash with MCUboot, complete the following steps: The Quad Serial Peripheral Interface (QSPI) NOR flash memory driver supports these features, and it can access the QSPI external flash memory of the nRF52840 DK and nRF5340 DK. See the test in :file:`tests/modules/mcuboot/external_flash` for reference. -This test passes both devicetree overlay files and Kconfig fragments to the MCUboot child image through its :file:`child_image` folder. -See also :ref:`ug_multi_image_variables` for more details on how to pass configuration files to a child image. +This test passes both devicetree overlay files and Kconfig fragments to the MCUboot image through its :file:`sysbuild` folder. Troubleshooting *************** diff --git a/doc/nrf/app_dev/bootloaders_dfu/mcuboot_nsib/bootloader_signature_keys.rst b/doc/nrf/app_dev/bootloaders_dfu/mcuboot_nsib/bootloader_signature_keys.rst index 4737dd998672..cec23169826d 100644 --- a/doc/nrf/app_dev/bootloaders_dfu/mcuboot_nsib/bootloader_signature_keys.rst +++ b/doc/nrf/app_dev/bootloaders_dfu/mcuboot_nsib/bootloader_signature_keys.rst @@ -11,11 +11,10 @@ Signature keys A signature key can be used by :ref:`bootloader` to validate the next image in the boot chain. Dedicated host tools like :doc:`mcuboot:imgtool` can be used to sign application update images. -When you use |NSIB|, a private/public key pair is by default generated during the build when you are :ref:`ug_bootloader_adding_immutable_keys`. +When you use MCUboot or :ref:`enable a bootloader chain through sysbuild `, the default configuration uses keys that were generated once and are stored in the public MCUboot Git repository. +When you use |NSIB|, a private/public key pair is by default generated during the build when you are :ref:`ug_bootloader_adding_sysbuild_immutable_keys`. You can use the methods described in the following sections to explicitly define how the key pair is to be generated. -When you use MCUboot or you are :ref:`ug_bootloader_adding_upgradable_mcuboot`, MCUboot uses keys that were generated once and are stored in the public MCUboot Git repository by default. - .. note:: These key pairs should only be used during development. See :ref:`ug_fw_update_development_keys` for more details. @@ -151,7 +150,7 @@ You can add this feature to your own project and check its functionality as foll The public key associated with the original private signing key must not be included in the public key list. -#. Program the application to the target development kit and :ref:`check its console output `. +#. Program the application to the target development kit and check its console output. With the first firmware version, ``priv_a.pem`` and ``pub_a.pem`` are used for signing and validating the image. .. code-block:: console diff --git a/doc/nrf/app_dev/companion_components.rst b/doc/nrf/app_dev/companion_components.rst index 09de6703cb5f..7b5fdd7057ae 100644 --- a/doc/nrf/app_dev/companion_components.rst +++ b/doc/nrf/app_dev/companion_components.rst @@ -48,7 +48,7 @@ The following table lists the available companion components: - Bootloader tailored for the :ref:`two-stage bootloader `. - :ref:`Bootloader requirements ` - :file:`samples/bootloader` - - :ref:`ug_bootloader_adding_immutable_b0` + - :ref:`ug_bootloader_adding_sysbuild_immutable_b0` * - :ref:`SUIT flash companion ` - Companion image that allows the Secure Domain Firmware to access the external memory during the :ref:`Software Updates for Internet of Things (SUIT) ` firmware upgrade. - :ref:`Sample requirements ` diff --git a/doc/nrf/app_dev/config_and_build/config_and_build_system.rst b/doc/nrf/app_dev/config_and_build/config_and_build_system.rst index 49f17073175a..f82385cd2dac 100644 --- a/doc/nrf/app_dev/config_and_build/config_and_build_system.rst +++ b/doc/nrf/app_dev/config_and_build/config_and_build_system.rst @@ -136,12 +136,12 @@ Memory layout configuration The memory layout configuration is provided by the :ref:`partition_manager` script, specific to the |NCS|. The script must be enabled to provide the memory layout configuration. -It is impacted by various elements, such as Kconfig configuration options or the presence of child images. +It is impacted by various elements, such as Kconfig configuration options or the presence of other images. Partition Manager ensures that all required partitions are in the correct place and have the correct size. If enabled, the memory layout can be controlled in the following ways: -* Dynamically (default) - In this scenario, the layout is impacted by various elements, such as Kconfig configuration options or the presence of child images. +* Dynamically (default) - In this scenario, the layout is impacted by various elements, such as Kconfig configuration options or the presence of other images. Partition Manager ensures that all required partitions are in the correct place and have the correct size. * Statically - In this scenario, you need to provide the static configuration. See :ref:`ug_pm_static` for information about how to do this. @@ -149,18 +149,6 @@ If enabled, the memory layout can be controlled in the following ways: After CMake has run, a :file:`partitions.yml` file with the memory layout will have been created in the :file:`build` directory. This process also creates a set of header files that provides defines, which can be used to refer to memory layout elements. -Child images ------------- - -.. important:: - |sysbuild_related_deprecation_note| - -The |NCS| build system allows the application project to become a root for the sub-applications known in the |NCS| as child images. -Examples of child images are bootloader images, network core images, or security-related images. -Each child image is a separate application. - -For more information, see :ref:`ug_multi_image`. - .. _app_build_file_suffixes: Custom configurations @@ -171,7 +159,7 @@ When you select a given file suffix for the :ref:`configuration phase `_ of ``w This includes :ref:`repository applications ` and the out-of-tree applications (:ref:`workspace ` and :ref:`freestanding applications `). For this reason, unlike in Zephyr, ``--sysbuild`` does not have to be explicitly mentioned in the command prompt when building a repository application. -This setting only applies to repositories delivered with the |NCS|, to maintain compatibility with child/parent images. If you want to disable this feature, for example if you want to explicitly use the ``--sysbuild`` parameter on the command line every time you build, :ref:`configure west to disable this default setting `. @@ -293,11 +280,6 @@ Moreover, this |NCS| setting does not apply to the following areas: Custom build types ================== -.. important:: - |file_suffix_related_deprecation_note| - It is still required for some applications that use build types with :ref:`multiple images `. - Check the application and sample documentation pages for which variable to use. - A build type is a feature that defines the way in which the configuration files are to be handled. For example, selecting a build type lets you generate different build configurations for *release* and *debug* versions of the application. @@ -305,7 +287,7 @@ In the |NCS|, the build type is controlled using the configuration files, whose When you select a build type for the :ref:`configuration phase `, the compiler will use a specific set of files to create a specific build configuration for the application. The :file:`prj.conf` file is the application-specific default, but many applications and samples include source files for generating the build configuration differently, for example :file:`prj_release.conf` or :file:`prj_debug.conf`. -Similarly, the build type can be included in file names for board configuration, Partition Manager's static configuration, child image Kconfig configuration, and others. +Similarly, the build type can be included in file names for board configuration, Partition Manager's static configuration, other image Kconfig configuration, and others. In this way, these files are made dependent on the build type and will only be used when the corresponding build type is invoked. For example, if an application uses :file:`pm_static_release.yml` to define Partition Manager's static configuration, this file will only be used when the application's :file:`prj_release.conf` file is used to select the release build type. @@ -318,8 +300,6 @@ The following software components can be made dependent on the build type: * The Partition Manager's :ref:`static configuration `. When the build type has been inferred, the file :file:`pm_static_.yml` will have precedence over :file:`pm_static.yml`. -* The :ref:`child image Kconfig configuration `. - Certain child image configuration files located in the :file:`child_image/` directory can be defined per build type. The devicetree configuration is not affected by the build type. @@ -327,17 +307,6 @@ For more information about how to invoke build types, see :ref:`cmake_options`. .. _app_build_additions_multi_image: -Multi-image builds -================== - -.. important:: - |sysbuild_related_deprecation_note| - -The |NCS| build system extends Zephyr's with support for multi-image builds. -You can find out more about these in the :ref:`ug_multi_image` section. - -The |NCS| allows you to :ref:`build types ` instead of using a single :file:`prj.conf` file. - Boilerplate CMake file ====================== diff --git a/doc/nrf/app_dev/config_and_build/index.rst b/doc/nrf/app_dev/config_and_build/index.rst index f9dff575034f..9cb0f2eef328 100644 --- a/doc/nrf/app_dev/config_and_build/index.rst +++ b/doc/nrf/app_dev/config_and_build/index.rst @@ -42,6 +42,5 @@ Make sure to consider :ref:`app_bootloaders` and :ref:`app_dfu` already at this hardware/index kconfig/index sysbuild/index - multi_image building output_build_files diff --git a/doc/nrf/app_dev/config_and_build/multi_image.rst b/doc/nrf/app_dev/config_and_build/multi_image.rst deleted file mode 100644 index bca2861a7437..000000000000 --- a/doc/nrf/app_dev/config_and_build/multi_image.rst +++ /dev/null @@ -1,407 +0,0 @@ -.. _ug_multi_image: - -Multi-image builds using child and parent images -################################################ - -.. contents:: - :local: - :depth: 2 - -.. caution:: - |sysbuild_related_deprecation_note| - -The firmware programmed to a device can be composed of either one application or several separate images. -In the latter case, the *parent* :term:`image file` requires one or more other images (the *child images*) to be present. -The child image then *chain-loads*, or *boots*, the parent image, which could also be a child image to another parent image, and boots that one. - -The most common use cases for builds composed of multiple images are applications that require a bootloader to be present or applications for multi-core CPUs. - -Using multiple images has the following advantages: - -* You can run the linker multiple times and partition the final firmware into several regions. - This partitioning is often useful for bootloaders. -* Since there is a symbol table for each image, the same symbol names can exist multiple times in the final firmware. - This is useful for bootloader images, which can require their own copy of a library that the application uses, but in a different version or configuration. -* In multi-core builds, the :term:`build configuration` of a child image in a separate core can be made known to the parent image. - -For the list of image files output by the build system for the multi-image builds, refer to :ref:`app_build_output_files` page. - -.. _ug_multi_image_when_to_use_images: - -When to use multiple images -*************************** - -In the |NCS|, multiple images are required in the following scenarios: - -First-stage and second-stage bootloaders - The first-stage bootloader establishes a root of trust by verifying the next step in the boot sequence. - This first-stage bootloader is immutable, which means it cannot be updated or deleted. - If a second-stage bootloader is present, then the first-stage bootloader is responsible for booting and updating the second-stage bootloader, which in turn is responsible for booting and updating the application. - As such, the first-stage bootloader, the second-stage bootloader, and the application must be located in different images. - In this scenario, the application is the parent image and the bootloaders are two separate child images. - - See :ref:`ug_bootloader` and :ref:`ug_bootloader_adding` for more information. - -nRF5340 development kit support - The nRF5340 development kit (DK) contains two separate processors: a network core and an application core. - When programming an application for the nRF5340 DK, the application must be divided into at least two images, one for each core. - - See :ref:`ug_nrf5340` for more information. - -nRF5340 Audio development kit support - The nRF5340 Audio development kit (DK) is based on the nRF5340 development kit and also contains two separate processors. - When programming an application for the nRF5340 Audio DK, the application core image is built from a combination of different configuration files. - The network core image is programmed with an application-specific precompiled Bluetooth Low Energy Controller binary file that contains the LE Audio Controller Subsystem for nRF53. - - See the documentation for :ref:`nrf53_audio_app` for more information. - -.. _ug_multi_image_default_config: - -Default configuration -********************* - -The |NCS| samples are set up to build all related images as one solution, starting from the parent image. -This is referred to as a *multi-image build*. - -When building the parent image, you can configure how the child image should be handled: - -* Build the child image from the source and include it with the parent image. - This is the default setting. -* Use a prebuilt HEX file of the child image and include it with the parent image. -* Ignore the child image. - -When building the child image from the source or using a prebuilt HEX file, the build system merges the HEX files of both the parent and child image, so that they can be programmed in one single step. -This means that you can enable and integrate an additional image just by using the default configuration. - -To change the default configuration and configure how a child image is handled, locate the ``BUILD_STRATEGY`` Kconfig options for the child image in the parent image configuration. -For example, to use a prebuilt HEX file of the MCUboot instead of building it, select :kconfig:option:`CONFIG_MCUBOOT_BUILD_STRATEGY_USE_HEX_FILE` instead of the default :kconfig:option:`CONFIG_MCUBOOT_BUILD_STRATEGY_FROM_SOURCE`, and specify the HEX file in :kconfig:option:`CONFIG_MCUBOOT_HEX_FILE`. -To ignore an MCUboot child image, select :kconfig:option:`CONFIG_MCUBOOT_BUILD_STRATEGY_SKIP_BUILD` instead of :kconfig:option:`CONFIG_MCUBOOT_BUILD_STRATEGY_FROM_SOURCE`. - -.. _ug_multi_image_defining: - -Defining and enabling a child image -*********************************** - -You can enable existing child images in the |NCS| by enabling the respective modules in the parent image and selecting the desired build strategy. - -To turn an application that you have implemented into a child image that can be included in a parent image, you must update the build scripts to enable the child image and add the required configuration options. -You should also know how image-specific variables are disambiguated and what targets of the child images are available. - -.. _ug_multi_image_build_scripts: - -Updating the build scripts -========================== - -To make it possible to enable a child image from a parent image, you must include the child image in the build script. -If you need to perform this operation out-of-tree (that is, without modifying |NCS| code), or from the top-level CMakeLists.txt in your sample, see :ref:`ug_multi_image_add_child_image_oot`. - -To do so, place the code from the following example in the CMake tree that is conditional on a configuration option. -In the |NCS|, the code is included in the :file:`CMakeLists.txt` file for the samples, and in the MCUboot repository. - -.. code-block:: cmake - - if (CONFIG_SECURE_BOOT) - add_child_image( - NAME b0 - SOURCE_DIR ${CMAKE_CURRENT_LIST_DIR}/bootloader - ) - endif() - - if (CONFIG_BOOTLOADER_MCUBOOT) - add_child_image( - NAME mcuboot - SOURCE_DIR ${MCUBOOT_DIR}/boot/zephyr - ) - endif() - -In this code, ``add_child_image`` registers the child image with the given name and file path and executes the build scripts of the child image. -Note that both the child image's application build scripts and the core build scripts are executed. -The core build scripts might use a different configuration and possibly different devicetree settings. - -If you have to execute a child image on a different core, you must specify the namespace for the child image as *domain* when adding the child image. -See the following example: - -.. code-block:: cmake - - add_child_image( - NAME hci_ipc - SOURCE_DIR ${ZEPHYR_BASE}/samples/bluetooth/hci_ipc - DOMAIN CPUNET - ) - -A *domain* is well-defined if there is the ``CONFIG_DOMAIN_${DOMAIN}_BOARD`` configuration option in Kconfig. - -.. _ug_multi_image_add_child_image_oot: - -Adding a child image using Zephyr modules -========================================= - -Any call to ``add_child_image`` must be done *after* :file:`nrf/cmake/extensions.cmake` is invoked, but *before* :file:`multi_image.cmake` is invoked. -In some scenarios, this is not possible without modifying the |NCS| build code, for example, from top-level sample files and project :file:`CMakeLists.txt` files. - -To avoid this issue, use the *Modules* mechanism provided by the Zephyr build system. -The following example shows how to add the required module from a top-level sample :file:`CMakeLists.txt`. - -.. code-block:: cmake - - cmake_minimum_required(VERSION 3.20.0) - - set(ZEPHYR_EXTRA_MODULES ${CMAKE_CURRENT_LIST_DIR}) - - find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE}) - project(app) - - target_sources(app PRIVATE src/main.c) - -A :file:`zephyr/module.yml` file is needed at the base of the added module. -The following example specifies only the path to the :file:`CMakeLists.txt` of the new module. -See :ref:`modules` for more details. - -.. code-block:: - - build: - cmake: aci - -The :file:`CMakeLists.txt` located in the directory pointed to by :file:`zephyr/module.yml` will be invoked when ``add_child_image`` can be invoked. - -.. code-block:: cmake - - add_child_image( - NAME remote - SOURCE_DIR ${CMAKE_CURRENT_LIST_DIR}/../remote - DOMAIN remote - BOARD ${CONFIG_APP_REMOTE_BOARD} - ) - -Adding configuration options -============================ - -When enabling a child image, you must select the build strategy to define how the image should be included. -The following three options are available: - -* ``_BUILD_STRATEGY_FROM_SOURCE`` - Build the child image from source along with the parent image. -* ``_BUILD_STRATEGY_USE_HEX_FILE`` - Merge the specified HEX file of the child image with the parent image, using ``_HEX_FILE`` to specify the HEX file. -* ``_BUILD_STRATEGY_SKIP_BUILD`` - Ignore the child image when building and build only the parent image. - -.. note:: - - Child images that are built with the build strategy ``_BUILD_STRATEGY_SKIP_BUILD`` or ``_BUILD_STRATEGY_USE_HEX_FILE`` must define a :ref:`static partition `. - -Add these configuration options to the Kconfig file of your child image, replacing ```` with the uppercase name of your child image that is specified in ``add_child_image``. -To do this, include the :file:`Kconfig.template.build_strategy` template as follows: - -.. code-block:: Kconfig - - module=MCUBOOT - source "${ZEPHYR_NRF_MODULE_DIR}/subsys/partition_manager/Kconfig.template.build_strategy" - -.. _ug_multi_image_variables: - -Image-specific variables -======================== - -The child and parent images are executed in different CMake processes and thus have different namespaces. - -Variables in the parent image are not propagated to the child image, with the following exceptions: - -* Any variable named ``_VARIABLEONE`` in a parent image is propagated to the child image named ```` as ``VARIABLEONE``. - See `Temporary variables in child images`_ for more information. -* CMake build settings, such as ``BOARD_DIR``, build type, toolchain info, partition manager info, and similar are always passed to child images. - See `Permanent configuration changes to child images`_ for more information. - -Using these two exceptions, you can set variables in child images from either parent images or the command line, and you can also set variables globally across all images. - -.. _ug_multi_image_variables_fragments: - -Temporary variables in child images ------------------------------------ - -It is possible to provide variables to the child images. -These variables will be valid until you :ref:`clean the build directory pristinely `. - -For example, to change the ``VARIABLEONE`` variable for the ``childimageone`` child image and the parent image, specify the CMake command as follows: - - .. parsed-literal:: - :class: highlight - - cmake -D\ *childimageone*\_\ *VARIABLEONE*\=value -D\ *VARIABLEONE*\=value - -You can extend the CMake command used to create the child images by adding flags to the CMake variable ``EXTRA_MULTI_IMAGE_CMAKE_ARGS``. -For example, add ``--trace-expand`` to that variable to output more debug information. - -With west, you can pass these configuration variables into CMake by using the ``--`` separator: - - .. code-block:: console - - west build -b nrf52840dk/nrf52840 zephyr/samples/hello_world -- \ - -Dmcuboot_CONF_FILE=prj_a.conf \ - -DCONF_FILE=app_prj.conf - -Child image Kconfig modification -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -It is possible to provide Kconfig configuration for child images, either as individual settings or using Kconfig fragments. -Each child image is referenced using its image name. - -These temporary settings will be valid until you :ref:`clean the build directory pristinely `. - -The following example sets the configuration option ``CONFIG_VARIABLEONE=val`` in the child image ``childimageone``: - - .. parsed-literal:: - :class: highlight - - cmake -D\ *childimageone*\_\ *CONFIG_VARIABLEONE=val*\ [...] - -You can add a Kconfig fragment to the child image default configuration in a similar way. -The following example adds an extra Kconfig fragment ``extrafragment.conf`` to ``childimageone``: - - .. parsed-literal:: - :class: highlight - - cmake -D\ *childimageone*\_EXTRA_CONF_FILE=\ *extrafragment.conf*\ [...] - -It is also possible to provide a custom configuration file as a replacement for the default Kconfig file for the child image. -The following example uses the custom configuration file ``myfile.conf`` when building ``childimageone``: - - .. parsed-literal:: - :class: highlight - - cmake -D\ *childimageone*\_CONF_FILE=\ *myfile.conf*\ [...] - -If your application includes multiple child images, then you can combine all the above as follows: - -* Setting ``CONFIG_VARIABLEONE=val`` in the main application. -* Adding a Kconfig fragment ``extrafragment.conf`` to the ``childimageone`` child image, using ``-Dchildimageone_EXTRA_CONF_FILE=extrafragment.conf``. -* Using ``myfile.conf`` as configuration for the ``quz`` child image, using ``-Dquz_CONF_FILE=myfile.conf``. - - .. parsed-literal:: - :class: highlight - - cmake -DCONFIG_VARIABLEONE=val -D\ *childimageone*\_EXTRA_CONF_FILE=\ *extrafragment.conf*\ -Dquz_CONF_FILE=\ *myfile.conf*\ [...] - -See :ref:`ug_bootloader` for more details. - -.. note:: - - The build system grabs the Kconfig fragment or configuration file specified in a CMake argument relative to that image's application directory. - For example, the build system uses ``nrf/samples/bootloader/my-fragment.conf`` when building with the ``-Db0_EXTRA_CONF_FILE=my-fragment.conf`` option, whereas ``-DEXTRA_CONF_FILE=my-fragment.conf`` grabs the fragment from the main application's directory, such as ``zephyr/samples/hello_world/my-fragment.conf``. - -You can also merge multiple fragments into the overall configuration for an image by giving a list of Kconfig fragments as a string, separated using ``;``. -The following example shows how to combine ``abc.conf``, Kconfig fragment of the ``childimageone`` child image, with the ``extrafragment.conf`` fragment: - - .. parsed-literal:: - :class: highlight - - cmake -D\ *childimageone*\_EXTRA_CONF_FILE='\ *extrafragment.conf*\;\ *abc.conf*\' - -When the build system finds the fragment, it outputs their merge during the CMake build output as follows: - -.. parsed-literal:: - :class: highlight - - ... - Merged configuration '\ *extrafragment.conf*\' - Merged configuration '\ *abc.conf*\' - ... - -Child image devicetree modification -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You can provide devicetree overlays for a child image using ``*.overlay`` files. - -The following example sets the devicetree overlay ``extra.overlay`` to ``childimageone``: - -.. parsed-literal:: - :class: highlight - - cmake -D\ *childimageone*\_DTC_OVERLAY_FILE='\ *extra.overlay*\' - -The build system does also automatically apply any devicetree overlay located in the ``child_image`` folder and named as follows (where ``ACI_NAME`` is the name of the child image): - -* ``child_image/.overlay`` -* ``child_image//.overlay`` -* ``child_image//_.overlay`` -* ``child_image//boards/.overlay`` -* ``child_image//boards/_.overlay`` - -.. note:: - - The build system grabs the devicetree overlay files specified in a CMake argument relative to that image's application directory. - For example, the build system uses ``nrf/samples/bootloader/my-dts.overlay`` when building with the ``-Db0_DTC_OVERLAY_FILE=my-dts.overlay`` option, whereas ``-DDTC_OVERLAY_FILE=my-dts.overlay`` grabs the fragment from the main application's directory, such as ``zephyr/samples/hello_world/my-dts.overlay``. - -.. _ug_multi_image_permanent_changes: - -Permanent configuration changes to child images ------------------------------------------------ - -You can make a project automatically pass Kconfig configuration files, fragments, and devicetree overlays to child images by placing them under a predefined path. -For example, in the |NCS| applications and samples that use different :ref:`build types `, the :file:`child_image` folder in the application source directory is often used to apply :ref:`permanent configuration changes `. - -The listing below describes how to leverage this functionality, where ``ACI_NAME`` is the name of the child image to which the configuration will be applied. - -When you are using :ref:`app_build_additions_build_types` and the configuration name has been inferred, the child image Kconfig overlay file is searched at :file:`child_image/_.conf`. -Alternatively, the child image Kconfig configuration file can be introduced as :file:`child_image//prj.conf` and follow the same pattern as the parent Kconfig. -For example, :file:`child_image/mcuboot/prj_release.conf` can be used to define the ``release`` build type for the ``mcuboot`` child image. - -Child image targets -=================== - -You can indirectly invoke a selection of child image targets from the parent image. -Currently, the child targets that can be invoked from the parent targets are ``menuconfig``, ``guiconfig``, and any targets listed in ``EXTRA_KCONFIG_TARGETS``. - -To disambiguate targets, use the same prefix convention used for variables. -For example, to run menuconfig, invoke the ``menuconfig`` target to configure the parent image and ``mcuboot_menuconfig`` to configure the MCUboot child image. - -You can also invoke any child target directly from its build directory. -Child build directories are located at the root of the parent's build directory. - -Controlling the build process -============================= - -The child image is built using CMake's build command ``cmake --build``. -This mechanism allows additional control of the build process through CMake. - -CMake options -------------- - -The following CMake options are propagated from the CMake command of the parent image to the CMake command of the child image: - -* ``CMAKE_BUILD_TYPE`` -* ``CMAKE_VERBOSE_MAKEFILE`` - -You can add other CMake options to a specific child image in the same way as you can set :ref:`Image-specific variables `. -For example, add ``-Dmcuboot_CMAKE_VERBOSE_MAKEFILE`` to the parent's CMake command to build the ``mcuboot`` child image with verbose output. - -To enable additional debug information for the multi-image build command, set the CMake option ``MULTI_IMAGE_DEBUG_MAKEFILE`` to the desired debug mode. -For example, add ``-DMULTI_IMAGE_DEBUG_MAKEFILE=explain`` to log the reasons why a command was executed. - -See :ref:`cmake_options` for instructions on how to specify these CMake options for the build. - -CMake environment variables ---------------------------- - -Unlike CMake options, CMake environment variables allow you to control the build process without re-invoking CMake. - -You can use the CMake environment variables `VERBOSE`_ and `CMAKE_BUILD_PARALLEL_LEVEL`_ to control the verbosity and the number of parallel jobs for a build: - -When using the command line or |VSC| terminal window, you must set them before invoking west. -They apply to both the parent and child images. -For example, to build with verbose output and one parallel job, use the following command, where *board_target* is the target for the development kit for which you are building: - -.. parsed-literal:: - :class: highlight - - west build -b *board_target* -- -DCMAKE_VERBOSE_MAKEFILE=1 -DCMAKE_BUILD_PARALLEL_LEVEL=1 - -Memory placement -**************** - -In a multi-image build, all images must be placed in memory so that they do not overlap. -The flash memory start address for each image must be specified by, for example, :kconfig:option:`CONFIG_FLASH_LOAD_OFFSET`. - -Hardcoding the image locations like this works fine for simple use cases like a bootloader that prepares a device, where there are no further requirements on where in memory each image must be placed. -However, more advanced use cases require a memory layout where images are located in a specific order relative to one another. - -The |NCS| provides a Python tool that allows you to specify this kind of relative placement or even a static placement based on start addresses and sizes for the different images. - -See :ref:`partition_manager` for more information about how to set up your partitions and configure your build system. diff --git a/doc/nrf/app_dev/device_guides/fem/fem_simple_gpio.rst b/doc/nrf/app_dev/device_guides/fem/fem_simple_gpio.rst index e4691885d9ba..05f8a5308613 100644 --- a/doc/nrf/app_dev/device_guides/fem/fem_simple_gpio.rst +++ b/doc/nrf/app_dev/device_guides/fem/fem_simple_gpio.rst @@ -52,10 +52,10 @@ To use the Simple GPIO implementation of FEM with SKY66112-11, complete the foll See the official `SKY66112-11 page`_ for more information. #. On nRF53 devices, you must also apply the same devicetree node mentioned in **Step 1** to the network core using sysbuild. - To apply the overlay to the correct network core child image, create an overlay file named :file:`sysbuild/*childImageName*/boards/nrf5340dk_nrf5340_cpunet.overlay` in your application directory, for example :file:`sysbuild/ipc_radio/boards/nrf5340dk_nrf5340_cpunet.overlay`. + To apply the overlay to the correct network core image, create an overlay file named :file:`sysbuild/*image_name*/boards/nrf5340dk_nrf5340_cpunet.overlay` in your application directory, for example :file:`sysbuild/ipc_radio/boards/nrf5340dk_nrf5340_cpunet.overlay`. For more information, see the :ref:`Migrating to sysbuild ` page. - The *childImageName* default value is set to ``ipc_radio``: + The *image_name* value is ``ipc_radio``: ``ipc_radio`` represents all applications with support for the combination of both 802.15.4 and Bluetooth. You can configure your application using the following sysbuild configurations: diff --git a/doc/nrf/app_dev/device_guides/nrf52/fota_update.rst b/doc/nrf/app_dev/device_guides/nrf52/fota_update.rst index c838dbb9ca51..a5256ab8b8aa 100644 --- a/doc/nrf/app_dev/device_guides/nrf52/fota_update.rst +++ b/doc/nrf/app_dev/device_guides/nrf52/fota_update.rst @@ -14,7 +14,7 @@ You can also use FOTA updates to replace the application. See the :ref:`app_dfu` page for general Device Firmware Update (DFU) information, such as supported methods for sending and receiving updates on the device. .. note:: - For the possibility of introducing an upgradable bootloader, refer to :ref:`ug_bootloader_adding`. + To implement an upgradable bootloader, refer to :ref:`ug_bootloader_adding_sysbuild`. .. fota_upgrades_intro_end @@ -52,7 +52,7 @@ To enable support for FOTA updates, do the following: .. fota_upgrades_over_ble_mandatory_mcuboot_start * Use MCUboot as the upgradable bootloader (``SB_CONFIG_BOOTLOADER_MCUBOOT`` must be enabled). - For more information, go to the :ref:`ug_bootloader_adding` page. + For more information, see the :ref:`ug_bootloader_adding_sysbuild` page. .. fota_upgrades_over_ble_mandatory_mcuboot_end @@ -184,7 +184,7 @@ FOTA update sample The :zephyr:code-sample:`smp-svr` demonstrates how to set up your project to support FOTA updates. -The sample documentation is from the Zephyr project and is incompatible with the :ref:`ug_multi_image`. +The sample documentation is from the Zephyr project. 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: @@ -195,7 +195,7 @@ In |NCS|, you can build and program the :zephyr:code-sample:`smp-svr` as any oth .. parsed-literal:: :class: highlight - west build -b *board_target* -- -DEXTRA_CONF_FILE=overlay-bt.conf -DSB_CONFG_NETCORE_HCI_IPC=y + west build -b *board_target* -- -DEXTRA_CONF_FILE=overlay-bt.conf -DSB_CONFIG_NETCORE_HCI_IPC=y west flash .. group-tab:: nRF52 SoCs diff --git a/doc/nrf/app_dev/device_guides/nrf53/building_nrf53.rst b/doc/nrf/app_dev/device_guides/nrf53/building_nrf53.rst index c5ef47fd9119..a24b458b13ff 100644 --- a/doc/nrf/app_dev/device_guides/nrf53/building_nrf53.rst +++ b/doc/nrf/app_dev/device_guides/nrf53/building_nrf53.rst @@ -31,7 +31,7 @@ You can build and program separate images or combined images using the |nRFVSC|. .. group-tab:: Multi-image build - If you are working with Bluetooth LE, Thread, Zigbee, or Matter samples, the network core sample is built as a child image when you build the application core image (see :ref:`ug_nrf5340_multi_image` above). + If you are working with Bluetooth® LE, Thread, Zigbee, or Matter samples, the network core sample is built as a separate image when you build the application core image. Complete the following steps to build and program a multi-image build to the nRF5340 application core and network core: diff --git a/doc/nrf/app_dev/device_guides/nrf53/features_nrf53.rst b/doc/nrf/app_dev/device_guides/nrf53/features_nrf53.rst index 2a866192a52c..392c16a907e4 100644 --- a/doc/nrf/app_dev/device_guides/nrf53/features_nrf53.rst +++ b/doc/nrf/app_dev/device_guides/nrf53/features_nrf53.rst @@ -150,7 +150,6 @@ You can use either the SoftDevice Controller or the Zephyr Bluetooth LE Controll See :ref:`ug_ble_controller` for more information. For the application core, the |NCS| provides a series of :ref:`Bluetooth Low Energy samples `, in addition to the :zephyr:code-sample-category:`bluetooth` samples. -|multi_image| .. note:: Most of the provided Bluetooth LE samples should run on the nRF5340 DK, but not all have been thoroughly tested. @@ -198,7 +197,6 @@ This Zephyr sample is designed specifically to enable the nRF IEEE 802.15.4 radi The sample implements the RPMsg transport using the `OpenAMP`_ library to communicate with the nRF IEEE 802.15.4 radio driver serialization host that runs on a separate core (in this case, the nRF5340 application core). For the application core, the |NCS| provides a series of samples for the :ref:`Thread `, :ref:`Zigbee `, and :ref:`Matter ` protocols. -|multi_image| Multiprotocol support ===================== @@ -231,7 +229,6 @@ For the network core, the |NCS| provides the :ref:`ipc_radio`. The :ref:`ipc_radio` enables both the Bluetooth LE Controller and the nRF IEEE 802.15.4 radio driver and simultaneously exposes the functionality of both stacks to the application. For the application core, the |NCS| provides a series of samples for the :ref:`Thread ` and :ref:`Zigbee ` protocols. -|multi_image| See the :ref:`ug_multiprotocol_support` user guide for instructions on how to enable multiprotocol support for Thread or Zigbee in combination with Bluetooth. @@ -254,13 +251,12 @@ Direct use of the radio peripheral Samples that directly use the radio peripheral can run on the network core of the nRF5340. They do not require any functionality from the application core. -However, on nRF5340, the application core is responsible for starting the network core and connecting its GPIO pins (see :kconfig:option:`CONFIG_SOC_NRF53_CPUNET_ENABLE` and the code in :file:`zephyr/boards/nordic/nrf5340dk/nrf5340_cpunet_reset.c`). +However, on nRF5340, the application core is responsible for starting the network core and connecting its GPIO pins (see :kconfig:option:`CONFIG_SOC_NRF53_CPUNET_ENABLE` and the code in :file:`zephyr/soc/nordic/nrf53/nrf53_cpunet_mgmt.c`). Therefore, you must always program the application core, even if the firmware is supposed to run only on the network core. You can use the :ref:`nrf5340_empty_app_core` sample for this purpose. -Configure the network core application to automatically include this sample as a child image. +Configure the network core application to automatically include this sample as the application core image. This is the default configuration for the listed network core samples. -For more information, see :kconfig:option:`CONFIG_NCS_SAMPLE_EMPTY_APP_CORE_CHILD_IMAGE` and :ref:`ug_nrf5340_multi_image`. No radio communication diff --git a/doc/nrf/app_dev/device_guides/nrf53/fota_update_nrf5340.rst b/doc/nrf/app_dev/device_guides/nrf53/fota_update_nrf5340.rst index 80a0f7050ffc..32e09a92752b 100644 --- a/doc/nrf/app_dev/device_guides/nrf53/fota_update_nrf5340.rst +++ b/doc/nrf/app_dev/device_guides/nrf53/fota_update_nrf5340.rst @@ -24,8 +24,6 @@ FOTA over Bluetooth Low Energy :start-after: fota_upgrades_over_ble_mandatory_mcuboot_start :end-before: fota_upgrades_over_ble_mandatory_mcuboot_end -Bluetooth buffers configuration introduced by the :kconfig:option:`CONFIG_NCS_SAMPLE_MCUMGR_BT_OTA_DFU_SPEEDUP` Kconfig option is also automatically applied to the network core child image by the dedicated overlay file. - .. include:: /app_dev/device_guides/nrf52/fota_update.rst :start-after: fota_upgrades_over_ble_additional_information_start :end-before: fota_upgrades_over_ble_additional_information_end diff --git a/doc/nrf/app_dev/device_guides/nrf53/index.rst b/doc/nrf/app_dev/device_guides/nrf53/index.rst index a4d32e31a2ba..f01514b1cbb7 100644 --- a/doc/nrf/app_dev/device_guides/nrf53/index.rst +++ b/doc/nrf/app_dev/device_guides/nrf53/index.rst @@ -48,7 +48,6 @@ Refer to their documentation for more information. features_nrf53 building_nrf53 fota_update_nrf5340 - multi_image_nrf5340 simultaneous_multi_image_dfu_nrf5340 serial_recovery logging_nrf5340 diff --git a/doc/nrf/app_dev/device_guides/nrf53/multi_image_nrf5340.rst b/doc/nrf/app_dev/device_guides/nrf53/multi_image_nrf5340.rst deleted file mode 100644 index 7c82b3bfba87..000000000000 --- a/doc/nrf/app_dev/device_guides/nrf53/multi_image_nrf5340.rst +++ /dev/null @@ -1,64 +0,0 @@ -.. _ug_nrf5340_multi_image: - -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. -For this to work, the network core image must be explicitly added as a child image to one of the application core images. -See :ref:`ug_multi_image_defining` for details. - -.. note:: - When using the :ref:`nrf5340_empty_app_core` sample, the image hierarchy is inverted. - In this case, the network core image is the parent image and the application core image is the child image. - -Default build configuration -*************************** - -By default, the two images are built together for all Bluetooth LE, Thread, Zigbee, and Matter samples in the |NCS|. -Samples that are designed to run only on the network core include the :ref:`nrf5340_empty_app_core` sample as a child image. -For other samples, the images are built separately. - -The :term:`build configuration` depends on the following Kconfig options that must be set in the configuration of the parent image: - -* :kconfig:option:`CONFIG_BT_HCI_IPC` - set to ``y`` in all Bluetooth LE samples for the application core -* :kconfig:option:`CONFIG_NRF_802154_SER_HOST` - set to ``y`` in all Thread, Zigbee, and Matter samples for the application core -* :kconfig:option:`CONFIG_NCS_SAMPLE_EMPTY_APP_CORE_CHILD_IMAGE` - set to ``y`` in all network core samples that require the :ref:`nrf5340_empty_app_core` sample - -The combination of these options determines which (if any) sample is included in the build of the parent image: - -.. list-table:: - :header-rows: 1 - - * - Enabled options - - Child image sample for the network core - - Child image sample for the application core - * - :kconfig:option:`CONFIG_BT_HCI_IPC` - - :zephyr:code-sample:`bluetooth_hci_ipc` - - --- - * - :kconfig:option:`CONFIG_NRF_802154_SER_HOST` - - :zephyr:code-sample:`nrf_ieee802154_rpmsg` - - --- - * - :kconfig:option:`CONFIG_NCS_SAMPLE_EMPTY_APP_CORE_CHILD_IMAGE` - - --- - - :ref:`nrf5340_empty_app_core` - -Configuration of the child image -******************************** - -When a network sample is built automatically as a child image in a multi-image build, you can define the relevant Kconfig options (if required) in a :file:`.conf` file. -Name the file :file:`network_sample*\ .conf`, where *network_sample* is the name of the child image (for example, :file:`hci_ipc.conf`). -Place the file in a :file:`child_image` subfolder of the application sample directory. -See :ref:`ug_multi_image_variables` for more information. - -This way of defining the Kconfig options allows to align the configurations of both images. - -For example, see the :ref:`ble_throughput` child image configuration in :file:`nrf/samples/bluetooth/throughput/child_image/hci_ipc.conf`. diff --git a/doc/nrf/app_dev/device_guides/nrf53/simultaneous_multi_image_dfu_nrf5340.rst b/doc/nrf/app_dev/device_guides/nrf53/simultaneous_multi_image_dfu_nrf5340.rst index 60ca09359bcd..6dec016703e8 100644 --- a/doc/nrf/app_dev/device_guides/nrf53/simultaneous_multi_image_dfu_nrf5340.rst +++ b/doc/nrf/app_dev/device_guides/nrf53/simultaneous_multi_image_dfu_nrf5340.rst @@ -12,8 +12,7 @@ To enable the simultaneous update of multiple images in the MCUboot, set the fol * :kconfig:option:`CONFIG_PCD_APP` - Enable commands exchange with the network core. * :kconfig:option:`CONFIG_UPDATEABLE_IMAGE_NUMBER` - Enable support for multiple update partitions by setting this option to ``2``. -As described in :ref:`multi-image build guide `, make sure to add the child image prefix to the name of Kconfig options that are used when building MCUboot as a child image (for example, ``child_image_CONFIG_PCD_APP``). -If not changed, then the default child image prefix for MCUboot is ``mcuboot_`` (for example, ``mcuboot_CONFIG_PCD_APP``). +As described in Zephyr's documentation about :ref:`sysbuild`, make sure to add the image prefix to the name of Kconfig options that are used when building MCUboot, which for MCUboot is ``mcuboot_`` (for example, ``mcuboot_CONFIG_PCD_APP``). .. note:: diff --git a/doc/nrf/app_dev/device_guides/nrf54h/ug_nrf54h20_configuration.rst b/doc/nrf/app_dev/device_guides/nrf54h/ug_nrf54h20_configuration.rst index 0fbfaea6750a..d9d6d0687a3a 100644 --- a/doc/nrf/app_dev/device_guides/nrf54h/ug_nrf54h20_configuration.rst +++ b/doc/nrf/app_dev/device_guides/nrf54h/ug_nrf54h20_configuration.rst @@ -73,4 +73,3 @@ Additionally, the build process generates the following user information configu You must flash all the HEX files into the device. For more information on building images for the nRF54H20 DK, see :ref:`ug_nrf54h20_gs`. -For additional information on multi-image builds see :ref:`ug_multi_image`. diff --git a/doc/nrf/app_dev/device_guides/nrf91/nrf91_features.rst b/doc/nrf/app_dev/device_guides/nrf91/nrf91_features.rst index bc1e9d5571c5..9d8b6114298e 100644 --- a/doc/nrf/app_dev/device_guides/nrf91/nrf91_features.rst +++ b/doc/nrf/app_dev/device_guides/nrf91/nrf91_features.rst @@ -80,8 +80,7 @@ Therefore, you must build it for any of the following board targets, depending o * ``thingy91x/nrf9151/ns`` The application image might require other images to be present. -Some samples include the :ref:`bootloader` sample (:kconfig:option:`CONFIG_SECURE_BOOT`) and :doc:`mcuboot:index-ncs` (:kconfig:option:`CONFIG_BOOTLOADER_MCUBOOT`). -Depending on the configuration, all these images can be built at the same time in a :ref:`multi-image build `. +Some samples include the :ref:`bootloader` sample (``SB_CONFIG_SECURE_BOOT_APPCORE``) and :doc:`mcuboot:index-ncs` (``SB_CONFIG_BOOTLOADER_MCUBOOT``). .. _lte_modem: diff --git a/doc/nrf/app_dev/device_guides/thingy53/building_thingy53.rst b/doc/nrf/app_dev/device_guides/thingy53/building_thingy53.rst index f860411da205..28bdcf8b586c 100644 --- a/doc/nrf/app_dev/device_guides/thingy53/building_thingy53.rst +++ b/doc/nrf/app_dev/device_guides/thingy53/building_thingy53.rst @@ -28,7 +28,7 @@ The board targets of interest for Thingy:53 in the |NCS| are listed in the follo | nRF5340 SoC - Network core |``thingy53/nrf5340/cpunet`` | +--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ -The |NCS| uses :ref:`ug_multi_image` for Thingy:53 by default. +The |NCS| uses :ref:`configuration_system_overview_sysbuild` by default. When you choose ``thingy53/nrf5340/cpuapp`` or ``thingy53/nrf5340/cpuapp/ns`` as the board target when building a sample or application, you will generate firmware for both the application core and network core: * The application core firmware consists of MCUboot bootloader and an application image. @@ -166,7 +166,7 @@ To build and program the source code from the command line, complete the followi west build -b *board_target* -d *destination_directory_name* The board target should be ``thingy53/nrf5340/cpuapp`` or ``thingy53/nrf5340/cpuapp/ns`` when building samples for the application core. - The proper child image for ``thingy53/nrf5340/cpunet`` will be built automatically. + The image for ``thingy53/nrf5340/cpunet`` will be built automatically. See :ref:`thingy53_build_pgm_targets` for details. #. Program the sample or application: diff --git a/doc/nrf/app_dev/device_guides/thingy53/thingy53_application_guide.rst b/doc/nrf/app_dev/device_guides/thingy53/thingy53_application_guide.rst index 24efaff923c7..f84ff43f8daf 100644 --- a/doc/nrf/app_dev/device_guides/thingy53/thingy53_application_guide.rst +++ b/doc/nrf/app_dev/device_guides/thingy53/thingy53_application_guide.rst @@ -102,7 +102,7 @@ The Nordic Thingy:53 has an RF front-end with two 2.4 GHz antennas: The samples in the |NCS| use **ANT1** by default, with the nRF21540 gain set to +10 dBm. You can configure the TX gain with the :kconfig:option:`CONFIG_MPSL_FEM_NRF21540_TX_GAIN_DB` Kconfig option to select between +10 dBm or +20 dBm gain. -To use the **ANT2** antenna, disable the :kconfig:option:`CONFIG_MPSL_FEM` Kconfig option in the network core's child image configuration. +To use the **ANT2** antenna, disable the :kconfig:option:`CONFIG_MPSL_FEM` Kconfig option in the network core's image configuration. .. note:: Transmitting with TX output power above +10 dBM is not permitted in some regions. @@ -117,7 +117,6 @@ FOTA over Bluetooth Low Energy :start-after: fota_upgrades_over_ble_intro_start :end-before: fota_upgrades_over_ble_intro_end -Bluetooth buffers configuration introduced by the :kconfig:option:`CONFIG_NCS_SAMPLE_MCUMGR_BT_OTA_DFU_SPEEDUP` Kconfig option is also automatically applied to the network core child image by the dedicated overlay file. Thingy:53 supports network core upgrade out of the box. .. include:: /app_dev/device_guides/nrf52/fota_update.rst diff --git a/doc/nrf/app_dev/device_guides/wifi_coex.rst b/doc/nrf/app_dev/device_guides/wifi_coex.rst index 060149ff54d6..9939d33c373f 100644 --- a/doc/nrf/app_dev/device_guides/wifi_coex.rst +++ b/doc/nrf/app_dev/device_guides/wifi_coex.rst @@ -57,7 +57,6 @@ The following are the common requirements to use the coexistence feature: .. note:: When using the nRF5340, apply steps 1 and 2 only to the network core. - See :ref:`ug_multi_image`. .. note:: Do not enable Wi-Fi coexistence on the nRF5340 SoC in conjunction with Coded Phy and FEM, as this can lead to undefined behavior. @@ -129,9 +128,9 @@ To enable Wi-Fi coexistence on the nRF70 Series device, complete the following s The second element is the pin number on that port. #. On the nRF5340, you must also apply the same devicetree node mentioned in step 1 to the network core using sysbuild build system. For more information, see the :ref:`Migrating to sysbuild ` page. - To do so, apply the overlay to the correct network core child image by creating an overlay file named :file:`sysbuild/*childImageName*/boards/nrf5340dk_nrf5340_cpunet.overlay.overlay` in your application directory, for example :file:`sysbuild/ipc_radio/boards/nrf5340dk_nrf5340_cpunet.overlay`. + Apply the overlay to the correct network core image by creating an overlay file named :file:`sysbuild/*image_name*/boards/nrf5340dk_nrf5340_cpunet.overlay` in your application directory, for example :file:`sysbuild/ipc_radio/boards/nrf5340dk_nrf5340_cpunet.overlay`. - The ``*childImageName*`` default value is set to ``ipc_radio`` :ref:`ipc_radio`. + The ``*image_name*`` value is ``ipc_radio`` :ref:`ipc_radio`. ``ipc_radio`` represents all applications with support for the combination of both 802.15.4 and Bluetooth. You can configure your application using the following sysbuild configurations: @@ -210,10 +209,10 @@ To enable the generic three-wire coexistence, do the following: The second element is the pin number on that port. #. On nRF53 devices, you must also apply the same devicetree node mentioned in **Step 1** to the network core using sysbuild. - To apply the overlay to the correct network core child image, create an overlay file named :file:`sysbuild/*childImageName*/boards/nrf5340dk_nrf5340_cpunet.overlay` in your application directory, for example :file:`sysbuild/ipc_radio/boards/nrf5340dk_nrf5340_cpunet.overlay`. + To apply the overlay to the correct network core image, create an overlay file named :file:`sysbuild/*image_name*/boards/nrf5340dk_nrf5340_cpunet.overlay` in your application directory, for example :file:`sysbuild/ipc_radio/boards/nrf5340dk_nrf5340_cpunet.overlay`. For more information, see the :ref:`Migrating to sysbuild ` page. - The *childImageName* default value is set to ``ipc_radio``: + The *image_name* value is ``ipc_radio``: ``ipc_radio`` represents all applications with support for the combination of both 802.15.4 and Bluetooth. You can configure your application using the following sysbuild configurations: diff --git a/doc/nrf/includes/hci_ipc_overlay.txt b/doc/nrf/includes/hci_ipc_overlay.txt deleted file mode 100644 index 27730f8f9e78..000000000000 --- a/doc/nrf/includes/hci_ipc_overlay.txt +++ /dev/null @@ -1,4 +0,0 @@ -.. note:: - - If you use nRF5340 DK, the additional configuration of the network core will be taken from the :file:`child_image` directory. - For more details, see :ref:`ug_multi_image_variables`. diff --git a/doc/nrf/libraries/bluetooth/rpc.rst b/doc/nrf/libraries/bluetooth/rpc.rst index 422ef7f67666..7909398576ec 100644 --- a/doc/nrf/libraries/bluetooth/rpc.rst +++ b/doc/nrf/libraries/bluetooth/rpc.rst @@ -145,7 +145,7 @@ The behavior of the Bluetooth implementation is almost the same as Zephyr's with The Bluetooth LE API is not strictly real-time by design, so the additional latency introduced by the IPC communication should be acceptable in most applications. To reduce the latency, consider using a different transport backend for nRF RPC. See :ref:`nrf_rpc_architecture` for details. - * Using advanced Bluetooth LE configurations, such as multiple simultaneous connections or advanced security features can be a limitation, because the child image (:ref:`ble_rpc_host` or :ref:`ipc_radio`) might require significantly more memory than the MCU it runs on has available. + * Using advanced Bluetooth LE configurations, such as multiple simultaneous connections or advanced security features can be a limitation, because the image (:ref:`ble_rpc_host` or :ref:`ipc_radio`) might require significantly more memory than the MCU it runs on has available. Typically, network or radio cores are more memory-constrained than the application MCU. * The :c:func:`bt_gatt_cancel` function is not implemented. * The ``flags`` field of the :c:struct:`bt_gatt_subscribe_params` structure is atomic, so it cannot be correctly handled by the nRF RPC. diff --git a/doc/nrf/libraries/dfu/dfu_multi_image.rst b/doc/nrf/libraries/dfu/dfu_multi_image.rst index abb19253b746..5b5822f21e81 100644 --- a/doc/nrf/libraries/dfu/dfu_multi_image.rst +++ b/doc/nrf/libraries/dfu/dfu_multi_image.rst @@ -14,7 +14,7 @@ Images included in a DFU multi-image package are identified by numeric identifie The library provides a way for the user to register custom functions for writing a single image with a given identifier. Because the library makes no assumptions about the formats of images included in a written package, it serves as a general-purpose solution for device firmware upgrades. -For example, it can be used to upgrade the :ref:`nRF5340 ` firmware. +For example, it can be used to upgrade the nRF5340 firmware. Configuration ************* diff --git a/doc/nrf/libraries/dfu/pcd.rst b/doc/nrf/libraries/dfu/pcd.rst index a79146c60313..e773428bbaf0 100644 --- a/doc/nrf/libraries/dfu/pcd.rst +++ b/doc/nrf/libraries/dfu/pcd.rst @@ -28,10 +28,9 @@ This is done to avoid compromised code from being able to perform updates of the The network core uses the PCD library to look for instructions on where to find the updates. Once an update instruction is found, this library is used to transfer the firmware update image. -On the application core, this library is used :ref:`MCUboot `. +On the application core, this library is used by :ref:`MCUboot `. On the network core, the library is used by the :ref:`nc_bootloader` sample. - API documentation ***************** diff --git a/doc/nrf/protocols/matter/end_product/bootloader.rst b/doc/nrf/protocols/matter/end_product/bootloader.rst index aa9fb399b96f..dffff154f98c 100644 --- a/doc/nrf/protocols/matter/end_product/bootloader.rst +++ b/doc/nrf/protocols/matter/end_product/bootloader.rst @@ -15,7 +15,7 @@ This page contains guidelines for configuring the MCUboot bootloader in Matter p Adding MCUboot to application ***************************** -Read :ref:`ug_bootloader_adding_immutable_mcuboot` to learn how to add MCUboot to an |NCS| application. +Read :ref:`ug_bootloader_adding_sysbuild_immutable_mcuboot` to learn how to add MCUboot to an |NCS| application. Some Matter samples include :term:`Device Firmware Update (DFU)` support out of the box, as listed in the :ref:`sample feature matrix table `. MCUboot minimal configuration @@ -123,7 +123,7 @@ If the signature check fails, MCUboot rejects the image and either: As the key pair is publicly known, it provides no protection against the image forgery. For this reason, when making a real product, it is of the greatest importance to replace it with a unique key pair, known only to the device maker. - Read :ref:`ug_bootloader_adding_immutable_mcuboot_keys` to learn how to configure MCUboot to use a custom key pair. + Read :ref:`ug_bootloader_adding_sysbuild_immutable_mcuboot_keys` to learn how to configure MCUboot to use a custom key pair. Downgrade protection ******************** diff --git a/doc/nrf/releases_and_maturity/migration/migration_guide_2.7.rst b/doc/nrf/releases_and_maturity/migration/migration_guide_2.7.rst index 55c845771e92..f6512253d82d 100644 --- a/doc/nrf/releases_and_maturity/migration/migration_guide_2.7.rst +++ b/doc/nrf/releases_and_maturity/migration/migration_guide_2.7.rst @@ -178,13 +178,13 @@ Applications using build types For applications using build types: * The :makevar:`CONF_FILE` used for :ref:`app_build_additions_build_types` is now deprecated and is being replaced with the :makevar:`FILE_SUFFIX` variable, inherited from Zephyr. - You can read more about it in :ref:`app_build_file_suffixes`, :ref:`cmake_options`, and the :ref:`related Zephyr documentation `. + For more information, see :ref:`app_build_file_suffixes`, :ref:`cmake_options`, and the :ref:`related Zephyr documentation `. If your application uses build types, it is recommended to update the :file:`sample.yaml` to use the new variable instead of :makevar:`CONF_FILE`. For applications using child images: - * With the inheritance of Zephyr's :ref:`sysbuild in the |NCS| `, the :ref:`ug_multi_image` are deprecated. + * With the inheritance of Zephyr's :ref:`sysbuild in the |NCS| `, parent-child image support is deprecated. If your application uses parent and child images, it is recommended to migrate your application to sysbuild before the multi-image builds are removed in one of the upcoming |NCS| releases. See `Migrating from multi-image builds to sysbuild`_. diff --git a/doc/nrf/releases_and_maturity/migration/migration_sysbuild.rst b/doc/nrf/releases_and_maturity/migration/migration_sysbuild.rst index 45c2ab02cbfb..9ab0bff08b9e 100644 --- a/doc/nrf/releases_and_maturity/migration/migration_sysbuild.rst +++ b/doc/nrf/releases_and_maturity/migration/migration_sysbuild.rst @@ -7,8 +7,8 @@ Migrating from multi-image builds to sysbuild :local: :depth: 2 -: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|. +Zephyr's :ref:`sysbuild` is a build system used to configure, build, and program multiple images as part of a single project. +It replaces the child/parent system for multi-image builds in the |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: @@ -563,7 +563,7 @@ The expected output files are the following: 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`). +In child/parent image configurations, an application could include additional configuration files in the ``child_image`` folder that would be applied to these images. 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: diff --git a/doc/nrf/releases_and_maturity/migration/nRF54H20_migration_2.7/migration_guide_2.4.99-cs3_to_2.7_application.rst b/doc/nrf/releases_and_maturity/migration/nRF54H20_migration_2.7/migration_guide_2.4.99-cs3_to_2.7_application.rst index cc113143b22d..484446bce9f2 100644 --- a/doc/nrf/releases_and_maturity/migration/nRF54H20_migration_2.7/migration_guide_2.4.99-cs3_to_2.7_application.rst +++ b/doc/nrf/releases_and_maturity/migration/nRF54H20_migration_2.7/migration_guide_2.4.99-cs3_to_2.7_application.rst @@ -649,7 +649,7 @@ Applications using build types For applications using child images: - * With the inheritance of Zephyr's :ref:`sysbuild in the |NCS| `, the :ref:`ug_multi_image` are deprecated. + * With the inheritance of Zephyr's :ref:`sysbuild in the |NCS| `, the multi-image builds are deprecated. If your application uses parent and child images, it is recommended to migrate your application to sysbuild before the multi-image builds are removed in one of the upcoming |NCS| releases. See :ref:`child_parent_to_sysbuild_migration`. See the :ref:`documentation in Zephyr ` for more information about sysbuild. diff --git a/doc/nrf/releases_and_maturity/migration/nRF54H20_migration_2.7/migration_guide_2.6.99-cs2_to_2.7_application.rst b/doc/nrf/releases_and_maturity/migration/nRF54H20_migration_2.7/migration_guide_2.6.99-cs2_to_2.7_application.rst index 47a0a16f545b..52e414820b59 100644 --- a/doc/nrf/releases_and_maturity/migration/nRF54H20_migration_2.7/migration_guide_2.6.99-cs2_to_2.7_application.rst +++ b/doc/nrf/releases_and_maturity/migration/nRF54H20_migration_2.7/migration_guide_2.6.99-cs2_to_2.7_application.rst @@ -568,7 +568,7 @@ Applications using build types For applications using child images: - * With the inheritance of Zephyr's :ref:`sysbuild in the |NCS| `, the :ref:`ug_multi_image` are deprecated. + * With the inheritance of Zephyr's :ref:`sysbuild in the |NCS| `, the multi-image builds are deprecated. If your application uses parent and child images, it is recommended to migrate your application to sysbuild before the multi-image builds are removed in one of the upcoming |NCS| releases. See :ref:`child_parent_to_sysbuild_migration`. See the :ref:`documentation in Zephyr ` for more information about sysbuild. diff --git a/doc/nrf/releases_and_maturity/releases/release-notes-1.0.0.rst b/doc/nrf/releases_and_maturity/releases/release-notes-1.0.0.rst index d3ae859ec431..745e1cc06c8a 100644 --- a/doc/nrf/releases_and_maturity/releases/release-notes-1.0.0.rst +++ b/doc/nrf/releases_and_maturity/releases/release-notes-1.0.0.rst @@ -249,7 +249,7 @@ Documentation * Added or updated the following documentation: * nRF BLE Controller (experimental) - * :ref:`ug_multi_image` + * Multi-image build * :ref:`partition_manager` * :ref:`nrf_desktop` * :ref:`shell_bt_nus_readme` diff --git a/doc/nrf/releases_and_maturity/releases/release-notes-1.2.0.rst b/doc/nrf/releases_and_maturity/releases/release-notes-1.2.0.rst index 3c888e51427c..772bf24b0397 100644 --- a/doc/nrf/releases_and_maturity/releases/release-notes-1.2.0.rst +++ b/doc/nrf/releases_and_maturity/releases/release-notes-1.2.0.rst @@ -513,7 +513,7 @@ Documentation * :ref:`ug_nrf5340` - added * :ref:`ug_thingy91` - added * :ref:`ug_ble_controller` - added - * :ref:`ug_multi_image` - updated with content that was removed from the Zephyr fork + * Multi-image builds - updated with content that was removed from the Zephyr fork * nrfxlib: diff --git a/doc/nrf/releases_and_maturity/releases/release-notes-1.3.0.rst b/doc/nrf/releases_and_maturity/releases/release-notes-1.3.0.rst index c42947056d7a..da5812843385 100644 --- a/doc/nrf/releases_and_maturity/releases/release-notes-1.3.0.rst +++ b/doc/nrf/releases_and_maturity/releases/release-notes-1.3.0.rst @@ -401,7 +401,7 @@ MCUboot Build system ============ -* Added support for :ref:`ug_multi_image` for multi-core projects. +* Added support for multi-image builds for multi-core projects. * Facilitated defining non-secure boards out of tree. Any board that matches ``*_ns`` or ``*ns`` is now considered non-secure, and its child images board is set to the secure variant. * Added support for defining external flash in the :ref:`partition_manager`. @@ -433,7 +433,7 @@ In addition to documentation related to the changes listed above, the following * :ref:`ug_nrf52` - added * :ref:`ug_thingy91` - added :ref:`thingy91_serialports` * :ref:`ug_nfc` - added -* :ref:`ug_bootloader` - added :ref:`ug_bootloader_adding` +* :ref:`ug_bootloader` - added upgradeable bootloader * Cloud client - updated * :ref:`crypto_test` - added * :ref:`libraries` - improved the structure of the library documentation diff --git a/doc/nrf/releases_and_maturity/releases/release-notes-1.4.0.rst b/doc/nrf/releases_and_maturity/releases/release-notes-1.4.0.rst index dc16976fee6a..c1d6aca8997b 100644 --- a/doc/nrf/releases_and_maturity/releases/release-notes-1.4.0.rst +++ b/doc/nrf/releases_and_maturity/releases/release-notes-1.4.0.rst @@ -447,7 +447,7 @@ MCUboot * Updated MCUboot to facilitate using it as the second stage bootloader: * Added minimal configuration overlay file for MCUboot that makes it fit within 16 kB when MCUboot is used as the second stage bootloader. - Updated :ref:`documentation ` with specific instructions on how and when to use this configuration. + Updated the documentation on adding bootloader with specific instructions on how and when to use this configuration. sdk-mcuboot ----------- @@ -483,7 +483,7 @@ Build system * Added a warning if no static partition manager configuration is provided when one image (or more) is not built from source in a multi-image build. * Enabled choosing a build strategy for Zephyr's :zephyr:code-sample:`bluetooth_hci_ipc` sample when it is built as a child image. - See :ref:`ug_multi_image` for details. + See multi-image builds for details. * Improved multi-core builds by disassociating domain names from board names. * Bugfixes: diff --git a/doc/nrf/releases_and_maturity/releases/release-notes-1.6.0.rst b/doc/nrf/releases_and_maturity/releases/release-notes-1.6.0.rst index 4b2881629437..b6c7c690f7a8 100644 --- a/doc/nrf/releases_and_maturity/releases/release-notes-1.6.0.rst +++ b/doc/nrf/releases_and_maturity/releases/release-notes-1.6.0.rst @@ -569,8 +569,8 @@ In addition to documentation related to the changes listed above, the following * Added the following bootloader user guides: - * :ref:`ug_bootloader_adding` - * :ref:`ug_bootloader_testing` + * Upgradeable bootloader + * Bootloader output testing * :ref:`ug_bootloader_external_flash` * :ref:`ug_bootloader_config` * :ref:`ug_fw_update` @@ -580,7 +580,7 @@ In addition to documentation related to the changes listed above, the following * :ref:`ug_bootloader` - Updated architecture information for clarifying first- and second-stage bootloader design. * "Immutable bootloader" references have been changed to "|NSIB|". -* :ref:`ug_multi_image` - Added more information regarding child image usage, configuration options, and image-specific variables. +* Multi-image builds - Added more information regarding child image usage, configuration options, and image-specific variables. * :ref:`partition_manager` - Added section about partition reports. * :ref:`ug_tfm` - Added references to new crypto samples that utilize TF-M and information about the TF-M minimal build. * :ref:`ug_thread` - The following sections were added or changed considerably: diff --git a/doc/nrf/releases_and_maturity/releases/release-notes-1.7.0.rst b/doc/nrf/releases_and_maturity/releases/release-notes-1.7.0.rst index 14cabbf9f923..a43dc7c3845c 100644 --- a/doc/nrf/releases_and_maturity/releases/release-notes-1.7.0.rst +++ b/doc/nrf/releases_and_maturity/releases/release-notes-1.7.0.rst @@ -515,7 +515,7 @@ In addition to documentation related to the changes listed above, the following * :ref:`ug_app_dev` section pages: - * :ref:`ug_multi_image` - Updated with the section about Child image devicetree overlays. + * Multi-image builds - Updated with the section about Child image devicetree overlays. * :ref:`ug_radio_fem` - Updated for the nRF21540 release. * :ref:`ug_nrf91` user guide - Restructured into several subpages. diff --git a/doc/nrf/releases_and_maturity/releases/release-notes-2.7.0.rst b/doc/nrf/releases_and_maturity/releases/release-notes-2.7.0.rst index 6b31492d4541..ab0bdd61ef57 100644 --- a/doc/nrf/releases_and_maturity/releases/release-notes-2.7.0.rst +++ b/doc/nrf/releases_and_maturity/releases/release-notes-2.7.0.rst @@ -19,7 +19,7 @@ Highlights This release introduces significant, potentially breaking, changes to the SDK: * The `previous method to define a board (hardware model)`_ is deprecated and being replaced by :ref:`a new method (hardware model v2) `. -* The previous method to define :ref:`multi-image builds (parent-child images) ` is deprecated and being replaced by :ref:`zephyr:sysbuild`. +* The previous method to define multi-image builds (parent-child images) is deprecated and being replaced by :ref:`zephyr:sysbuild`. All samples and applications in the SDK have been migrated. Consult respective documentation as additional or changed parameters might be needed to build them successfully. @@ -56,7 +56,7 @@ Added the following features as supported: * Hardware model v2 (HWMv2), an improved extensible system for defining boards. This is the default boards definition system from this |NCS| release and onwards. See `Migrating to the current hardware model`_. - * :ref:`zephyr:sysbuild`, an improved and extensible system for multi-image build, replacing :ref:`ug_multi_image` (parent/child images). + * :ref:`zephyr:sysbuild`, an improved and extensible system for multi-image build, replacing parent/child images. See `Migrating from multi-image builds to sysbuild`_. * Samples and applications that use short-range radio and run on multi-core SoCs were migrated to use the :ref:`ipc_radio` as the default image for the network/radio core. Samples previously used for the network/radio core are no longer used in the default builds: :zephyr:code-sample:`bluetooth_hci_ipc`, :zephyr:code-sample:`nrf_ieee802154_rpmsg`, ``nRF5340: Multiprotocol RPMsg``, and :ref:`ble_rpc_host`. diff --git a/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst b/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst index 2c192ea98aa2..484b6a8fdd97 100644 --- a/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst +++ b/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst @@ -46,7 +46,9 @@ Board support Build and configuration system ============================== -|no_changes_yet_note| +* Removed support for the deprecated multi-image builds (parent-child images) functionality. + All |NCS| projects must now use :ref:`sysbuild`. + See :ref:`child_parent_to_sysbuild_migration` for an overview of differences with parent-child image and how to migrate. Bootloaders and DFU =================== diff --git a/doc/nrf/security/tfm.rst b/doc/nrf/security/tfm.rst index 48d3f3b30722..8947497c76d3 100644 --- a/doc/nrf/security/tfm.rst +++ b/doc/nrf/security/tfm.rst @@ -35,7 +35,6 @@ Building ******** TF-M is one of the images that are built as part of a multi-image application. -For more information about multi-image builds, see :ref:`ug_multi_image`. To add TF-M to your build, enable the :kconfig:option:`CONFIG_BUILD_WITH_TFM` configuration option by adding it to your :file:`prj.conf` file. @@ -158,8 +157,8 @@ By default, one of the ports is used by the non-secure UART0 peripheral from the There are several options to get UART output from the secure TF-M: * Disable the output for the network core and change the pins used by TF-M. - The network core will usually have an |NCS| child image. - To configure a child image, see Configuration of the child image section described in :ref:`ug_nrf5340_multi_image`. + The network core will usually have an |NCS| image. + To learn how to configure an image, see the Configuration namespacing section in Zephyr's documentation about :ref:`sysbuild`. To configure logging in an |NCS| image, see :ref:`ug_logging`. To change the pins used by TF-M, the RXD (:kconfig:option:`CONFIG_TFM_UART1_RXD_PIN`) and TXD (:kconfig:option:`CONFIG_TFM_UART1_TXD_PIN`) Kconfig options in the application image can be set to **P1.00** (32) and **P1.01** (33). diff --git a/doc/nrf/shortcuts.txt b/doc/nrf/shortcuts.txt index 2a8bd9da8fd1..2fe95ecb4ea2 100644 --- a/doc/nrf/shortcuts.txt +++ b/doc/nrf/shortcuts.txt @@ -86,10 +86,6 @@ .. |file_suffix_related_deprecation_note| replace:: This feature is deprecated and is being replaced by :ref:`suffix-based configurations `. You can continue to use it until the transition is complete in the |NCS| and the feature is removed in one of the upcoming |NCS| releases. -.. |sysbuild_related_deprecation_note| replace:: This feature is deprecated and is being replaced by Zephyr's :ref:`zephyr:sysbuild`. - You can continue to use it until the transition is complete in the |NCS| and the feature is removed in one of the upcoming |NCS| releases. - For more information, see :ref:`zephyr:sysbuild`, :ref:`sysbuild_images`, :ref:`zephyr_samples_sysbuild`, and :ref:`sysbuild_forced_options`. - .. |nrfjprog_deprecation_note| replace:: Starting with the |NCS| v2.8.0, nrfjprog is in the process of being archived. It will remain available for download, but `nRF Util (device command) `_ will gradually replace it. @@ -246,8 +242,6 @@ .. |parameters_override_west_config| replace:: The parameters and options passed in the command line always take precedence over ``west config`` settings. -.. |multi_image| replace:: These samples are built for the application core and, by default, include the network core application as child image in a multi-image build (see :ref:`ug_nrf5340_multi_image`). - .. |migration_contact_devzone| replace:: While we strive to document all breaking changes, the migration guides might not include the detailed migration steps for your use case. If you need assistance, contact Nordic Semiconductor's technical support on `DevZone`_. diff --git a/doc/nrf/test_and_optimize/optimizing/power_general.rst b/doc/nrf/test_and_optimize/optimizing/power_general.rst index ca5b786f41a6..5a2b01af247b 100644 --- a/doc/nrf/test_and_optimize/optimizing/power_general.rst +++ b/doc/nrf/test_and_optimize/optimizing/power_general.rst @@ -58,7 +58,7 @@ To disable serial output, you must change the project configuration associated w .. note:: If the application consists of multiple images, like applications built for the nRF53 Series, logging must be disabled on both images. - See :ref:`ug_nrf5340` and :ref:`ug_multi_image`. + See :ref:`ug_nrf5340`. 1. Set the project configuration :kconfig:option:`CONFIG_SERIAL` to ``n`` irrespective of whether you are building the sample for the :ref:`SPE-only ` board targets or board targets with :ref:`NSPE `. #. For the board target with NSPE (for example, ``nrf9160dk/nrf9160/ns``), ensure that serial logging is also disabled in Trusted Firmware-M by setting :kconfig:option:`CONFIG_TFM_LOG_LEVEL_SILENCE` to ``y``. diff --git a/modules/mcuboot/boot/zephyr/Kconfig b/modules/mcuboot/boot/zephyr/Kconfig index 251b730cc72b..781cdc003d87 100644 --- a/modules/mcuboot/boot/zephyr/Kconfig +++ b/modules/mcuboot/boot/zephyr/Kconfig @@ -70,7 +70,6 @@ config MCUBOOT_NRF_CLEANUP_NONSECURE_RAM config BOOT_SIGNATURE_KEY_FILE string "MCUBoot PEM key file" - depends on !MCUBOOT_BUILD_STRATEGY_FROM_SOURCE help Absolute path to PEM key file containing the private key corresponding to the public key included in MCUBoot. This will be used to sign the diff --git a/samples/Kconfig b/samples/Kconfig index 7d58eb3d4370..c3a6d150fd94 100644 --- a/samples/Kconfig +++ b/samples/Kconfig @@ -25,7 +25,7 @@ menu "Image build variants" config NCS_MCUBOOT_IN_BUILD bool "MCUBoot is included in the build [READ ONLY]" help - Helper option used to communicate to child images that MCUboot is included in the build. + Helper option used to communicate to images that MCUboot is included in the build. endmenu diff --git a/samples/bluetooth/central_hr_coded/README.rst b/samples/bluetooth/central_hr_coded/README.rst index b6f45a0013a6..823344c9a918 100644 --- a/samples/bluetooth/central_hr_coded/README.rst +++ b/samples/bluetooth/central_hr_coded/README.rst @@ -17,8 +17,6 @@ The sample supports the following development kits: .. table-from-sample-yaml:: -.. include:: /includes/hci_ipc_overlay.txt - The sample also requires a device running a Heart Rate Server with LE Coded PHY support to connect to. For example, another development kit running the :ref:`peripheral_hr_coded` sample. diff --git a/samples/bluetooth/direct_test_mode/README.rst b/samples/bluetooth/direct_test_mode/README.rst index 0c2fc1b17591..76eba935f5f7 100644 --- a/samples/bluetooth/direct_test_mode/README.rst +++ b/samples/bluetooth/direct_test_mode/README.rst @@ -326,8 +326,8 @@ The :file:`dtm_uart_twowire.c` file is an implementation of the UART interface s The :file:`dtm_hci.c` and :file:`hci_uart.c` files are an implementation of the HCI UART interface specified in the `Bluetooth Core Specification`_, Volume 4, Part A (the flow control can be configured by an overlay file). The default selection of UART pins is defined in :file:`zephyr/boards/arm/board_name/board_name.dts`. -You can change the defaults using the symbols ``tx-pin`` and ``rx-pin`` in the DTS overlay file of the child image at the project level. -The configuration files for the :ref:`nrf5340_remote_shell` subimage are located in the :file:`child_image/remote_shell` or :file:`sysbuild/remote_shell` directory. +You can change the defaults using the symbols ``tx-pin`` and ``rx-pin`` in the DTS overlay file of the image at the project level. +The configuration files for the :ref:`nrf5340_remote_shell` subimage are located in the :file:`sysbuild/remote_shell` directory. The HCI interface allows for a custom ``remote_hci`` image to be used with |nRF5340DKnoref|. .. note:: diff --git a/samples/bluetooth/direction_finding_central/README.rst b/samples/bluetooth/direction_finding_central/README.rst index 13a36519a965..3344e0d596d1 100644 --- a/samples/bluetooth/direction_finding_central/README.rst +++ b/samples/bluetooth/direction_finding_central/README.rst @@ -60,8 +60,8 @@ nRF5340 configuration files The following additional configuration files are available for the :ref:`nRF5340 DK `: -* The Bluetooth LE controller is part of a child image meant to run on the network core. - The configuration for the child image is stored in the :file:`child_image/` subdirectory. +* The Bluetooth LE controller is part of an image meant to run on the network core. + The configuration for the image is stored in the :file:`sysbuild/` subdirectory. * The DTS overlay file :file:`boards/nrf5340dk_nrf5340_cpuapp.overlay` is available for the application core. This file forwards the control over GPIOs to network core, which provides control over GPIOs to the radio peripheral in order to execute antenna switching. @@ -76,7 +76,7 @@ To build this sample with AoD mode only, set :makevar:`EXTRA_CONF_FILE` to the : For more information about configuration files in the |NCS|, see :ref:`app_build_system`. -To build this sample for :ref:`nRF5340 DK `, with AoD mode only, add content of :file:`overlay-aod.conf` file to :file:`child_image/hci_ipc.conf` file. +To build this sample for the :ref:`nRF5340 DK ` with AoD mode only, add the content of the :file:`overlay-aod.conf` file to the :file:`sysbuild/hci_ipc/prj.conf` file. .. bt_dir_finding_central_aod_end diff --git a/samples/bluetooth/fast_pair/input_device/README.rst b/samples/bluetooth/fast_pair/input_device/README.rst index df174fc022f9..c84dd9ca6fb6 100644 --- a/samples/bluetooth/fast_pair/input_device/README.rst +++ b/samples/bluetooth/fast_pair/input_device/README.rst @@ -27,8 +27,6 @@ The sample supports the following development kits: .. include:: /includes/tfm.txt -.. include:: /includes/hci_ipc_overlay.txt - Overview ******** diff --git a/samples/bluetooth/iso_combined_bis_and_cis/README.rst b/samples/bluetooth/iso_combined_bis_and_cis/README.rst index 226d1d5a32bc..ad598eb2b510 100644 --- a/samples/bluetooth/iso_combined_bis_and_cis/README.rst +++ b/samples/bluetooth/iso_combined_bis_and_cis/README.rst @@ -26,9 +26,6 @@ The sample supports the following development kits: To test the sample, you need two additional devices. You can use any of the development kits listed above and mix different development kits. - -.. include:: /includes/hci_ipc_overlay.txt - The sample also requires a connection to a computer with a serial terminal |ANSI| for each of the development kits. Overview diff --git a/samples/bluetooth/peripheral_hids_keyboard/README.rst b/samples/bluetooth/peripheral_hids_keyboard/README.rst index 501f067d4160..57c743773f9f 100644 --- a/samples/bluetooth/peripheral_hids_keyboard/README.rst +++ b/samples/bluetooth/peripheral_hids_keyboard/README.rst @@ -23,8 +23,6 @@ The sample supports the following development kits: .. include:: /includes/tfm.txt -.. include:: /includes/hci_ipc_overlay.txt - If the NFC_OOB_PAIRING feature is enabled, the sample requires a smartphone or a tablet with Android v8.0.0 or newer. Overview diff --git a/samples/bluetooth/peripheral_hids_mouse/README.rst b/samples/bluetooth/peripheral_hids_mouse/README.rst index 939575fcfcf9..88b6c5848dfd 100644 --- a/samples/bluetooth/peripheral_hids_mouse/README.rst +++ b/samples/bluetooth/peripheral_hids_mouse/README.rst @@ -22,8 +22,6 @@ The sample supports the following development kits: .. include:: /includes/tfm.txt -.. include:: /includes/hci_ipc_overlay.txt - Overview ******** diff --git a/samples/bluetooth/peripheral_hr_coded/README.rst b/samples/bluetooth/peripheral_hr_coded/README.rst index 4c42d4cec48b..26e262f43bd7 100644 --- a/samples/bluetooth/peripheral_hr_coded/README.rst +++ b/samples/bluetooth/peripheral_hr_coded/README.rst @@ -17,8 +17,6 @@ The sample supports the following development kits: .. table-from-sample-yaml:: -.. include:: /includes/hci_ipc_overlay.txt - The sample also requires a device running a Heart Rate Server with LE Coded PHY support to connect to. For example, another development kit running the :ref:`bluetooth_central_hr_coded` sample. diff --git a/samples/bluetooth/peripheral_mds/README.rst b/samples/bluetooth/peripheral_mds/README.rst index 08f51e13d256..afc898f3f9bd 100644 --- a/samples/bluetooth/peripheral_mds/README.rst +++ b/samples/bluetooth/peripheral_mds/README.rst @@ -21,8 +21,6 @@ The sample supports the following development kits: .. include:: /includes/tfm.txt -.. include:: /includes/hci_ipc_overlay.txt - Overview ******** diff --git a/samples/bluetooth/peripheral_power_profiling/README.rst b/samples/bluetooth/peripheral_power_profiling/README.rst index 6700b200d990..2706db3bd8d2 100644 --- a/samples/bluetooth/peripheral_power_profiling/README.rst +++ b/samples/bluetooth/peripheral_power_profiling/README.rst @@ -18,8 +18,6 @@ The sample supports the following development kits: .. table-from-sample-yaml:: -.. include:: /includes/hci_ipc_overlay.txt - Optionally, you can use the `Power Profiler Kit II (PPK2)`_ for power profiling and optimizing your configuration. You can use also your proprietary solution for measuring the power consumption. diff --git a/samples/bluetooth/throughput/README.rst b/samples/bluetooth/throughput/README.rst index 2d30bd314ac9..7767fc17e582 100644 --- a/samples/bluetooth/throughput/README.rst +++ b/samples/bluetooth/throughput/README.rst @@ -21,8 +21,6 @@ The sample supports the following development kits: You can use any two of the development kits listed above and mix different development kits. -.. include:: /includes/hci_ipc_overlay.txt - The sample also requires a connection to a computer with a serial terminal |ANSI| for each of the development kits. Overview diff --git a/samples/bootloader/README.rst b/samples/bootloader/README.rst index 8563afb1450b..c37d531a406c 100644 --- a/samples/bootloader/README.rst +++ b/samples/bootloader/README.rst @@ -16,7 +16,7 @@ See :ref:`ug_bootloader` for more information about the full bootloader chain. .. note:: Currently, the NSIB does not support performing firmware updates over the SMP transport. - If the application using the NSIB requires SMP-based firmware updates, such as Bluetooth® LE DFU, :ref:`include MCUboot as a second-stage bootloader `. + If the application using the NSIB requires SMP-based firmware updates, such as Bluetooth® LE DFU, :ref:`include MCUboot as a second-stage bootloader `. .. _bootloader_rot: @@ -157,8 +157,6 @@ Monotonic counter :start-after: bootloader_monotonic_counter_nsib_start :end-before: bootloader_monotonic_counter_nsib_end -To set options for child images, such as NSIB and MCUboot, see the :ref:`ug_multi_image_variables` section. - .. _bootloader_build_and_run: Building and running @@ -169,20 +167,20 @@ Building and running .. include:: /includes/build_and_run.txt .. caution:: - |NSIB| should be included as a child image in a multi-image build, rather than being built stand-alone. + |NSIB| should be included as an image in a project using sysbuild, rather than being built stand-alone. While it is technically possible to build the NSIB by itself and merge it into other application images, this process is not supported. To reduce the development time and potential issues with this route, let the existing |NCS| infrastructure for multi-image builds handle the integration. - The NSIB is automatically added as a child image when the :kconfig:option:`CONFIG_SECURE_BOOT` Kconfig option is set in the application. + The NSIB is automatically added as an image when the ``SB_CONFIG_SECURE_BOOT_APPCORE`` sysbuild Kconfig option is set. -For building and running the NSIB with an application, see :ref:`ug_bootloader_adding_immutable`. +For building and running the NSIB with an application, see :ref:`ug_bootloader_adding_sysbuild_immutable`. Building and running using |VSC| ================================ .. include:: /includes/build_and_run_bootloader.txt -To add the NSIB as a child image to your application, complete the following steps: +To add the NSIB as an image to your application, complete the following steps: 1. :ref:`Create a private key in PEM format `. #. Enable the |NSIB| through Kconfig as follows: @@ -207,11 +205,6 @@ To add the NSIB as a child image to your application, complete the following ste #. Select :guilabel:`Flash` in the :guilabel:`Actions View` to program the resulting image to your device. -Testing -======= - -See :ref:`ug_bootloader_testing` for testing of the expected runtime behavior of the NSIB when built with an application. - Dependencies ************ diff --git a/samples/cellular/smp_svr/README.rst b/samples/cellular/smp_svr/README.rst index cea969ed606a..611a4644cde4 100644 --- a/samples/cellular/smp_svr/README.rst +++ b/samples/cellular/smp_svr/README.rst @@ -46,11 +46,6 @@ The nRF52840 SoC needs to enable UART1 on the devicetree using the following con MCUboot configuration --------------------- -The sample has defined configuration and device tree overlay files for MCUboot that are available in the sample folder: - -* :file:`child_image/mcuboot.conf` - Defines the MCUboot recovery mode. -* :file:`child_image/mcuboot/boards/nrf9160dk_nrf52840_0_14_0.overlay` - Define UART1 for MCUmgr. - The MCUboot configuration is enabled automatically at build. Partition management diff --git a/samples/common/mcumgr_bt_ota_dfu/Kconfig b/samples/common/mcumgr_bt_ota_dfu/Kconfig index f35e51406a88..ba124e4de095 100644 --- a/samples/common/mcumgr_bt_ota_dfu/Kconfig +++ b/samples/common/mcumgr_bt_ota_dfu/Kconfig @@ -123,10 +123,6 @@ config NCS_SAMPLE_MCUMGR_BT_OTA_DFU_SPEEDUP size. The buffer configuration should be the same in the Network Core and Application Core image. - This configuration option is automatically applied for the Network - Core child image if the NCS_SAMPLE_MCUMGR_BT_OTA_DFU_SPEEDUP option is - enabled in the main image. - if NCS_SAMPLE_MCUMGR_BT_OTA_DFU_SPEEDUP config BT_L2CAP_TX_MTU diff --git a/samples/net/aws_iot/README.rst b/samples/net/aws_iot/README.rst index ac7e7e0aac4c..f763ce61c2b7 100644 --- a/samples/net/aws_iot/README.rst +++ b/samples/net/aws_iot/README.rst @@ -158,12 +158,11 @@ The sample includes pre-configured configuration files for the development kits The following configuration and DTS overlay files are included to host the MCUboot secondary image slot on external flash for the nRF7002 DK: * :file:`boards/nrf7002dk_nrf5340_cpuapp_ns.overlay` - DTS overlay file for the application image. -* :file:`child_image/mcuboot/nrf7002dk_nrf5340_cpuapp.overlay` - DTS overlay file for the MCUboot child image. -* :file:`child_image/mcuboot/nrf7002dk_nrf5340_cpuapp.conf` - Configuration file for the MCUboot child image. +* :file:`sysbuild/mcuboot/nrf7002dk_nrf5340_cpuapp.overlay` - DTS overlay file for the MCUboot image. +* :file:`sysbuild/mcuboot/nrf7002dk_nrf5340_cpuapp.conf` - Configuration file for the MCUboot image. Files that are located under the :file:`/boards` folder are automatically merged with the :file:`prj.conf` file when you build for the corresponding target. -Files that are located under the :file:`/child_image/mcuboot` folder are used to configure the MCUboot child image. -To read more about child images, see :ref:`ug_multi_image`. +Files that are located under the :file:`/sysbuild/mcuboot` folder are used to configure the MCUboot image. .. include:: /libraries/modem/nrf_modem_lib/nrf_modem_lib_trace.rst :start-after: modem_lib_sending_traces_UART_start diff --git a/samples/nrf5340/empty_net_core/README.rst b/samples/nrf5340/empty_net_core/README.rst index d16618875ca9..10cb6d89b1e1 100644 --- a/samples/nrf5340/empty_net_core/README.rst +++ b/samples/nrf5340/empty_net_core/README.rst @@ -8,7 +8,6 @@ nRF5340: Empty firmware for network core :depth: 2 The sample demonstrates how to generate an empty network core firmware. -When building an MCUboot child image with the nRF5340 :ref:`ug_nrf5340_multi_image_dfu` feature, the empty network core sample is built together with the application to prevent build failures related to missing Partition Manager definitions in the :ref:`ug_multi_image`. The sample is used only by the applications that do not use the network core. In the mentioned case, the empty network core sample is automatically added to build by the :kconfig:option:`CONFIG_NCS_SAMPLE_EMPTY_NET_CORE_CHILD_IMAGE` option which depends on the :kconfig:option:`CONFIG_SOC_NRF53_CPUNET_ENABLE` option. diff --git a/samples/nrf5340/netboot/README.rst b/samples/nrf5340/netboot/README.rst index c3b715b0be68..1c40e324cd69 100644 --- a/samples/nrf5340/netboot/README.rst +++ b/samples/nrf5340/netboot/README.rst @@ -21,7 +21,6 @@ Overview The network core bootloader sample protects the flash memory areas allocated to both itself and the application running on the network core. -You must use this sample as a child image of a :ref:`multi-image ` build, where MCUboot is enabled and there is a network core application. MCUboot verifies and shares with the network core bootloader any new network core application image received through a device firmware update (DFU) transport layer, like a serial or a Bluetooth® LE connection. For this reason, without MCUboot, this sample does nothing else but directly launches the application. @@ -70,13 +69,13 @@ Building and running This sample can be found under :file:`samples/nrf5340/netboot/` in the |NCS| folder structure. -Follow the steps below to include the sample as a child image in a :ref:`multi-image ` build that contains a network core application: +To include the sample as an image in a sysbuild project that contains a network core application, add the following sysbuild Kconfig options in the project: -#. To add MCUboot to the build, enable the :kconfig:option:`CONFIG_BOOTLOADER_MCUBOOT` option in the application that runs on the application core. - The build system includes the sample in the build by automatically enabling the :kconfig:option:`CONFIG_SECURE_BOOT` option for the application that runs on the network core. -#. To enable the :ref:`subsys_pcd` library for MCUboot, set the :kconfig:option:`CONFIG_PCD_APP` option when building its image. +* ``SB_CONFIG_BOOTLOADER_MCUBOOT`` +* ``SB_CONFIG_SECURE_BOOT_NETCORE`` +* ``SB_CONFIG_NETCORE_APP_UPDATE`` -The build system generates a new set of firmware update files. +The build system includes the sample in the build automatically and generates a new set of firmware update files. These files match the ones described in :ref:`mcuboot:mcuboot_ncs`, except that they contain the network core application firmware and are prefixed with ``net_core_``. See :ref:`configure_application` for information on how to enable the required configuration options. diff --git a/samples/tfm/provisioning_image/README.rst b/samples/tfm/provisioning_image/README.rst index 19ae3fd6340c..7d0719887931 100644 --- a/samples/tfm/provisioning_image/README.rst +++ b/samples/tfm/provisioning_image/README.rst @@ -13,8 +13,8 @@ This sample does not include a TF-M image, it is a Zephyr image intended to be f After completion, the device is in the Platform Root-of-Trust (PRoT) security lifecycle state called **PRoT Provisioning**. For more information about the PRoT security lifecycle, see `ARM Platform Security Model 1.1`_. -When built for the nrf5340dk/nrf5340/cpuapp target, this image by default also includes the :ref:`provisioning_image_net_core` sample as a child image for the network core (``nrf5340dk/nrf5340/cpunet`` target). -The child image demonstrates how to disable the debugging access on the network core by writing to the UICR.APPROTECT register. +When built for the ``nrf5340dk/nrf5340/cpuapp`` board target, this image by default also includes the :ref:`provisioning_image_net_core` sample as an image for the network core (``nrf5340dk/nrf5340/cpunet`` board target). +The image demonstrates how to disable the debugging access on the network core by writing to the ``UICR.APPROTECT`` register. Requirements ************ diff --git a/samples/tfm/provisioning_image_net_core/README.rst b/samples/tfm/provisioning_image_net_core/README.rst index cc92876ec8c3..85432da4a5a7 100644 --- a/samples/tfm/provisioning_image_net_core/README.rst +++ b/samples/tfm/provisioning_image_net_core/README.rst @@ -10,7 +10,7 @@ TF-M: Provisioning image for network core Running this provisioning image in the network core will disable the debugging access, as required by the Trusted Firmware-M (TF-M) provisioning process. The debugging is disabled by enabling the APPROTECT in the UICR register. -This sample is included by default as a child image of the :ref:`provisioning image` sample which runs on the application core. +This sample is included by default as an image of the :ref:`provisioning image` sample that runs on the application core. The provisioning images initialize the provisioning process of a device in a manner compatible with TF-M. The APPROTECT feature is explained in detail in :ref:`app_approtect`. diff --git a/samples/zigbee/ncp/README.rst b/samples/zigbee/ncp/README.rst index 4db6fa74322d..47ecb492f058 100644 --- a/samples/zigbee/ncp/README.rst +++ b/samples/zigbee/ncp/README.rst @@ -189,7 +189,6 @@ When you select `Communication through USB`_, MCUboot is built with support for If you want to use the default UART serial communication channel, set the :kconfig:option:`CONFIG_BOOTLOADER_MCUBOOT` Kconfig option to enable MCUboot. To use the same MCUboot configuration as in `Communication through USB`_, you need to provide MCUboot with the Kconfig options included in the :file:`sysbuild/mcuboot_usb.conf` file. -See :ref:`ug_multi_image_variables` to learn how to set the required options. MCUboot with the USB DFU requires a larger partition. To increase the partition, define the :makevar:`PM_STATIC_YML_FILE` variable that provides the path to the :file:`pm_static__.yml` static configuration file for the board target of your choice. diff --git a/scripts/partition_manager/partition_manager.rst b/scripts/partition_manager/partition_manager.rst index 9ddcea54fe64..4063a2763141 100644 --- a/scripts/partition_manager/partition_manager.rst +++ b/scripts/partition_manager/partition_manager.rst @@ -8,11 +8,9 @@ Partition Manager :depth: 2 The Partition Manager is a Python script that sets the start address and size of all the flash and RAM partitions in a multi-image build context. -When creating an application that requires child images, like a bootloader, you can configure the Partition Manager to control where each image should be placed in memory, and how the RAM should be shared. +When creating an application that requires other images, like a bootloader, you can configure the Partition Manager to control where each image should be placed in memory, and how the RAM should be shared. -See :ref:`ug_multi_image` for more information about multi-image builds. - -The Partition Manager is activated for all multi-image builds, regardless of which build strategy is used for the child image. +The Partition Manager is activated for all sysbuild builds. .. note:: When you build a multi-image application using the Partition Manager, the devicetree source flash partitions are ignored. @@ -35,11 +33,11 @@ Flash partition types Image partitions An image partition is the flash memory area reserved for an image to which the image binary is written. - When the Partition Manager is active, there is one *root image* and one or more *child images*. + When the Partition Manager is active, there is one *root image* and one or more *other images*. The name of the root image is ``app``. It is always implicitly defined. - Child images are explicitly defined in :file:`pm.yml` files. - The size of the root image partition is dynamic, while the sizes of all child image partitions are statically defined. + Other images are explicitly defined in :file:`pm.yml` files. + The size of the root image partition is dynamic, while the sizes of all other image partitions are statically defined. Placeholder partitions A placeholder partition does not contain an image, but reserves space for other uses. @@ -75,12 +73,12 @@ Permanent placeholder RAM partitions Configuration ************* -Each child image must define its Partition Manager configuration in a file called :file:`pm.yml`. -This file must be stored in the same folder as the main :file:`CMakeLists.txt` file of the child image. +Each additional image must define its Partition Manager configuration in a :file:`pm.yml` file. +This file must be stored in the same folder as the main :file:`CMakeLists.txt` file of the other image. .. note:: - :file:`pm.yml` is only used for child images. - The root application does not need to define a :file:`pm.yml` file, because its partition size and placement is implied by the size and placement of the child image partitions. + :file:`pm.yml` is only used for additional images. + The root application does not need to define a :file:`pm.yml` file, because its partition size and placement is implied by the size and placement of the other image partitions. If a root application defines a :file:`pm.yml` file, it is silently ignored. The Partition Manager configuration can be also provided by a *subsystem*, intended as a software component. @@ -124,7 +122,7 @@ placement: dict This property specifies the placement of the partition relative to other partitions, to the start or end of the flash, or to the root image ``app``. A partition with the placement property set is either an image partition or a placeholder partition. - If the partition name is the same as the image name (as defined in a ``CMakeLists.txt``; see :ref:`ug_multi_image_defining` for details), this partition is the image partition. + If the partition name is the same as the image name, this partition is the image partition. All other partitions are placeholder partitions. Each :file:`pm.yml` file must define exactly one image partition. @@ -584,7 +582,7 @@ As partition manager does not know if partitions are used at runtime, consider t .. note:: - When using an application configured with an MCUboot child image, both images use the same partition manager configuration, which means that the app and MCUboot have exactly the same partition maps. + When using an application configured with an MCUboot image, both images use the same partition manager configuration, which means that the app and MCUboot have exactly the same partition maps. The accessibility at runtime of flash partitions depends on the configurations of both the application and MCUboot and the values they give to the ``DEFAULT_DRIVER_KCONFIG`` option of the partition manager region specification. .. _pm_build_system: @@ -592,7 +590,7 @@ As partition manager does not know if partitions are used at runtime, consider t Build system ************ -The build system finds the child images that have been enabled and their configurations. +The build system identifies the enabled images and their configurations. For each image, the Partition Manager's CMake code infers the paths to the following files and folders from the name and from other global properties: @@ -600,7 +598,7 @@ For each image, the Partition Manager's CMake code infers the paths to the follo * The compiled HEX file * The generated include folder -After CMake finishes configuring the child images, the Partition Manager script is executed in configure time (``execute_process``) with the lists of names and paths as arguments. +When CMake has completed configuring the additional images, the Partition Manager script is executed in configure time (``execute_process``) with the lists of names and paths as arguments. The configurations generated by the Partition Manager script are imported as CMake variables (see :ref:`pm_cmake_usage`). The Partition Manager script outputs a :file:`partitions.yml` file. @@ -615,7 +613,7 @@ Generated output After the main Partition Manager script has finished, another script runs. This script takes the :file:`partitions.yml` file as input and creates the following output files: -* A C header file :file:`pm_config.h` for each child image and for the root application +* A C header file :file:`pm_config.h` for each other image and for the root application * A key-value file :file:`pm.config` The header files are used in the C code, while the key-value file is imported into the CMake namespace. @@ -786,7 +784,7 @@ If you do not set :makevar:`PM_STATIC_YML_FILE`, the build system will use the f #. Otherwise, if the file :file:`pm_static_.yml` exists, it will be used. #. Otherwise, if the file :file:`pm_static.yml` exists, it will be used. -For :ref:`ug_multi_image` where the image targets a different domain, :ref:`ug_multi_image_build_scripts` uses the same search algorithm, but a domain specific configuration file is also searched. +In builds where the image targets a different domain, the Partition Manager employs the same search algorithm but also looks for a domain-specific configuration file. For example, :file:`pm_static___.yml` or :file:`pm_static__.yml`. Use a static partition layout to ensure consistency between builds, as the settings storage will be at the same location after the DFU. @@ -813,14 +811,14 @@ You can add or remove partitions as described in the following sections. Configuring dynamic partitions ============================== -For child images that use dynamic partition sizing, the Partition Manager allows you to use the ``CONFIG_PM_PARTITION_SIZE_`` Kconfig option to adjust the partition size. +For additional images that use dynamic partition sizing, the Partition Manager allows you to use the ``CONFIG_PM_PARTITION_SIZE_`` Kconfig option to adjust the partition size. This is particularly useful when you want to optimize the memory usage of MCUboot to the smallest possible size by enabling cryptographic functionalities. .. note:: - To match the reduced size, you need to set the ``CONFIG_PM_PARTITION_SIZE_`` Kconfig option in the child image's configuration. - For example, ``CONFIG_PM_PARTITION_SIZE_MCUBOOT`` must be set for the MCUboot child image. + To match the reduced size, you need to set the ``CONFIG_PM_PARTITION_SIZE_`` Kconfig option in the other image's configuration. + For example, ``CONFIG_PM_PARTITION_SIZE_MCUBOOT`` must be set for the MCUboot image. -The ``CONFIG_PM_PARTITION_SIZE_`` Kconfig option allows you to specify the memory size for each child image's partition directly in the Kconfig file. +The ``CONFIG_PM_PARTITION_SIZE_`` Kconfig option allows you to specify the memory size for each image's partition directly in the Kconfig file. This allows for precise control over memory allocation which is crucial for system performance optimization. Common variants of this Kconfig option include the following: @@ -867,9 +865,6 @@ The region defaults to ``flash_primary`` if no ``region`` property is specified. size: 0x1000 span: [example] # Only if this partition had the span property set originally. -.. note:: - Child images that are built with the build strategy *partition_name*\ _BUILD_STRATEGY_SKIP_BUILD or *partition_name*\ _BUILD_STRATEGY_USE_HEX_FILE must define a static partition to ensure correct placement of the dynamic partitions. - .. _ug_pm_static_remove: Removing a static partition diff --git a/scripts/partition_manager_output.py b/scripts/partition_manager_output.py index 23c4cf945ca9..080cd3e1f1ca 100644 --- a/scripts/partition_manager_output.py +++ b/scripts/partition_manager_output.py @@ -151,9 +151,9 @@ def write_gpm_config(gpm_config, regions_config, name, out_path): ---------------------------------------------------------- --- WARNING: Partition image '{image}' is a container --- --- partition with a span of one or more images, but --- - --- has the same name of its child image. Container --- + --- has the same name of its image. Container --- --- partitions are not allowed to share the name of --- - --- the child image that defines it. --- + --- the image that defines it. --- --- --- --- A pm_static.yml file defining appears to be --- --- overriding this. If possible, please rename the --- @@ -163,9 +163,9 @@ def write_gpm_config(gpm_config, regions_config, name, out_path): else: raise PartitionError( f"Partition image '{image}' is a container with a span of one " - "or more images, but has the same name of its child image. " + "or more images, but has the same name of its image. " "Container partitions are not allowed to share the name of the " - " child image that defines it. Please rename the span " + " image that defines it. Please rename the span " f"'{image}' in the pm.yml file of child '{image}'.") image_config_lines.append('#define PM_ADDRESS {}'.format(hex(gpm_config[domain][pm_image]['address']))) diff --git a/subsys/partition_manager/Kconfig b/subsys/partition_manager/Kconfig index 8b26e31fdb98..c79c73bb6cbc 100644 --- a/subsys/partition_manager/Kconfig +++ b/subsys/partition_manager/Kconfig @@ -12,8 +12,8 @@ config PARTITION_MANAGER_ENABLED Option which can be checked to see whether or not the partition manager is enabled in the current build. Note that this should ideally be a hidden option, but it can't due to limitations - in how parent images impose options on child images. Don't - change the value of this option. + in how sysbuild imposes options on images. Do not change the value + of this option. # Override this option to use custom flash map implementation when partition # manager is enabled. @@ -201,8 +201,6 @@ config PM_EXTERNAL_FLASH_SIZE_BITS config PM_EXTERNAL_FLASH_MCUBOOT_SECONDARY bool "Place MCUboot secondary in external flash" depends on BOOTLOADER_MCUBOOT || MCUBOOT - # Only depend on the chosen for the parent image. The value of this - # option is propagated to the MCUboot child image automatically. depends on PM_EXTERNAL_FLASH_ENABLED || MCUBOOT default y if BOOTLOADER_MCUBOOT help diff --git a/tests/benchmarks/multicore/idle/README.rst b/tests/benchmarks/multicore/idle/README.rst index 19c39140336e..07801d16f19f 100644 --- a/tests/benchmarks/multicore/idle/README.rst +++ b/tests/benchmarks/multicore/idle/README.rst @@ -24,7 +24,7 @@ Overview The test demonstrates how to build a multicore idle application with :ref:`configuration_system_overview_sysbuild`. -When building with sysbuild, the build system adds child images based on the options selected in the project's additional configuration and build files. +When building with sysbuild, the build system adds images based on the options selected in the project's additional configuration and build files. This test shows how to inform the build system about dedicated sources for additional images. The test comes with the following additional files: diff --git a/tests/benchmarks/multicore/idle_gpio/README.rst b/tests/benchmarks/multicore/idle_gpio/README.rst index 9df8665f9a6f..719eeb7636cf 100644 --- a/tests/benchmarks/multicore/idle_gpio/README.rst +++ b/tests/benchmarks/multicore/idle_gpio/README.rst @@ -24,7 +24,7 @@ Overview The test demonstrates how to build a multicore idle application with :ref:`configuration_system_overview_sysbuild`. -When building with sysbuild, the build system adds child images based on the options selected in the project's additional configuration and build files. +When building with sysbuild, the build system adds images based on the options selected in the project's additional configuration and build files. This test shows how to inform the build system about dedicated sources for additional images. The test comes with the following additional files: diff --git a/tests/modules/mcuboot/external_flash/sysbuild/mcuboot/prj.conf b/tests/modules/mcuboot/external_flash/sysbuild/mcuboot/prj.conf index 944f3c8b6f9d..0b61de98efa2 100644 --- a/tests/modules/mcuboot/external_flash/sysbuild/mcuboot/prj.conf +++ b/tests/modules/mcuboot/external_flash/sysbuild/mcuboot/prj.conf @@ -4,7 +4,7 @@ # SPDX-License-Identifier: LicenseRef-Nordic-5-Clause # -# In order to provide board specific configurations to the MCUboot child image +# In order to provide board specific configurations to the MCUboot image # we also need to provide a base configuration for MCUboot. This file contains # the basic configurations needed to successfully build and run MCUboot.