nRF Connect SDK Intermediate – [Lesson 8] – Sysbuild configuration – v2.6.2 – v2.5.2

Multi-Image build (predecessor to Sysbuild)

To explain multi-image builds, first consider how a program for an Nordic SoC works without any framework for building multiple images. In this scenario, you build the bootloader first, then the application. Both build separately, without any knowledge of each other. You must ensure that the bootloader and application agree on their flash storage locations (partition information). After the images build, you write the output file (typically a hex file) from each build to the Nordic SoC separately. The following figure illustrates this process:

You can use this method in the nRF Connect SDK, but it’s not the default. Instead, the nRF Connect SDK uses the Multi-image build system, which handles building multiple images. In multi-image builds, the application builds as the main image, and all other images are added as child images.

The following simplified figure illustrates the multi-image build system:

The following subsections cover the main features of multi-image builds.

Building images in order and choosing the default child image

When you build the main application, the multi-image build system automatically builds all child images in the correct order. For example, if you add CONFIG_BOOTLOADER_MCUBOOT=y to the Zephyr Hello World sample, multi-image builds are enabled. Upcoming exercises examine this in more detail. In the following figure, item (1) shows that a child image is built, as seen in the resulting build log:

Although you can add custom child images to applications, most use cases involve bootloaders and network core images. The nRF Connect SDK includes default samples that you can use as child images. When you enable certain features, the multi-image build system activates and automatically selects an appropriate image based on your main application configuration:

• CONFIG_SECURE_BOOT: Adds the Nordic Secure Immutable Bootloader sample as child image.
• CONFIG_BOOTLOADER_MCUBOOT: Adds the MCUboot application as child image.
• nRF5340: Supported Protocols gives an overview over configurations add which samples as child images, when building for the nRF5340.

Configuring child images

Child images are often built from samples in the nRF Connect SDK. Because we don’t recommend making changes to the nRF Connect SDK source, how can you configure the child images? Multi-image builds let you configure image-specific variables by overlaying or changing existing child image configurations. You can configure child images in two main ways: using CMake arguments or using a predefined folder structure and configuration files.

To use CMake arguments, you can overlay individual Kconfig options using -D<child_image>_CONFIG_WHATEVER=y (for example, -Dmcuboot_CONFIG_LOG_DEFAULT_LEVEL=3). The following image shows this approach:

You can also overlay files using CMake arguments with -D<child_image>_EXTRA_CONF_FILE or -D<child_image>_DTC_OVERLAY_FILE. To overwrite Kconfig, use -D<child_image>_CONF_FILE.

Alternatively, you can use a folder structure to add files to the project. This is the recommended method and is used in most examples to configure child images. Place these files in a directory named child_image and name them after the child image (typically child_image/mcuboot.conf or child_image/mcuboot/prj.conf). For a complete list, see Multi-image builds: Permanent configuration changes to child images:

The following example shows a simple project with MCUboot overlays:

Generate output files

The multi-image build system also generates output files for programming or DFU of the Nordic SoC. When you use the “Flash” function in the VS Code Extension for a single image build, build/zephyr/zephyr.hex programs to the Nordic SoC. For multi-image builds, build/zephyr/merged.hex is used instead. For a list of output build files generated by multi-image builds, see Multi-image builds: What image files are. For a more comprehensive list of generated output builds in the nRF Connect SDK, see the Build and configuration system documentation. The multi-image build system also generates different output build files for different cores when relevant.

Partitioning

Multi-image builds use Partition Manager for partitioning.