Zephyr sysbuild / multi image

[tejlmand]

This is an PR for a direction of multi image support in Zephyr, as discussed in dev-review meeting Nov. 11. 2021.

Fixes: #40309

Documentation PR: #43846

Depends on: #41301

With #37872 the issue regarding multi image build system came up again.

This PR takes another direction, as it does not interfere with the existing Zephyr CMake build system infrastructure.

Zephyr build code and samples are not impacted with this PR.

Instead a dedicated west build project has been created in <zephyr>/sysbuild (feel free to propose alternative location).
This project is capable of building a regular Zephyr sample as well as MCUBoot.

Each sample is seen as a dedicated project.

west build has been extended to support multi image for building, as well as west flash supports flashing of all images in the multi image build.

Per default, everything builds as normal, that is a single image build IS Still build as:

west build -bnrf52840dk_nrf52840 samples/hello_world

which gives:

-- west build: making build dir /projects/github/ncs/zephyr/build pristine
-- west build: generating a build system
Loading Zephyr default modules (Zephyr base).
-- Application: /projects/github/ncs/zephyr/samples/hello_world
...

but the same sample can now also be build and flash with mcuboot (or in principle any other multi image setup), simply by enabling MCUboot and build with sysbuild option:

$ west build -bnrf52840dk_nrf52840 samples/hello_world/ --sysbuild -- -DSB_CONFIG_BOOTLOADER_MCUBOOT=y
...
   *********************************
   * Running CMake for hello_world *
   *********************************
...
-- Build files have been written to: /projects/github/ncs/zephyr/build/hello_world
-- 
   *****************************
   * Running CMake for mcuboot *
   *****************************
...
-- Build files have been written to: /projects/github/ncs/zephyr/build/mcuboot
-- Configuring done
-- Generating done
-- Build files have been written to: /projects/github/ncs/zephyr/build
-- west build: building application
[9/16] Performing build step for 'mcuboot'
[1/257] Preparing syscall dependency handling

[247/257] Linking C executable zephyr/zephyr_pre0.elf

[251/257] Linking C executable zephyr/zephyr_pre1.elf

[257/257] Linking C executable zephyr/zephyr.elf
Memory region         Used Size  Region Size  %age Used
           FLASH:       37836 B        48 KB     76.98%
            SRAM:       23808 B       256 KB      9.08%
        IDT_LIST:          0 GB         2 KB      0.00%
[11/16] Performing build step for 'hello_world'
[1/155] Preparing syscall dependency handling

[145/155] Linking C executable zephyr/zephyr_pre0.elf

[149/155] Linking C executable zephyr/zephyr_pre1.elf

[155/155] Linking C executable zephyr/zephyr.elf
Memory region         Used Size  Region Size  %age Used
           FLASH:       17680 B       412 KB      4.19%
            SRAM:        5440 B       256 KB      2.08%
        IDT_LIST:          0 GB         2 KB      0.00%
[16/16] Completed 'hello_world'

where it can be seen that both hello_world and mcuboot were successfully build.

Both samples can be flash in a single invocation with west flash:

$ west flash
-- west flash: rebuilding
[0/6] Performing build step for 'mcuboot'
ninja: no work to do.
[1/6] Performing build step for 'hello_world'
ninja: no work to do.
[6/6] Completed 'hello_world'
-- west flash: using runner nrfjprog
-- runners.nrfjprog: mass erase requested
Using board 683848500
-- runners.nrfjprog: Flashing file: /projects/github/ncs/zephyr/build/mcuboot/zephyr/zephyr.hex
Parsing image file.
Applying system reset.
Verified OK.
Enabling pin reset.
Applying pin reset.
-- runners.nrfjprog: Board with serial number 683848500 flashed successfully.
-- west flash: using runner nrfjprog
Using board 683848500
-- runners.nrfjprog: Flashing file: /projects/github/ncs/zephyr/build/hello_world/zephyr/zephyr.signed.hex
-- runners.nrfjprog: Flashing file: /projects/github/ncs/zephyr/build/hello_world/zephyr/zephyr.signed.hex
Parsing image file.
Applying system reset.
Verified OK.
Enabling pin reset.
Applying pin reset.
-- runners.nrfjprog: Board with serial number 683848500 flashed successfully.
-- runners.nrfjprog: Board with serial number 683848500 flashed successfully.

Resulting in following output on the terminal.

*** Booting Zephyr OS build v2.7.99-1479-g6fb2ea314f83  ***
I: Starting bootloader
I: Primary image: magic=unset, swap_type=0x1, copy_done=0x3, image_ok=0x3
I: Secondary image: magic=unset, swap_type=0x1, copy_done=0x3, image_ok=0x3
I: Boot source: none
I: Swap type: none
I: Bootloader chainload address offset: 0xc000
I: Jumping to the first image slot
*** Booting Zephyr OS build v2.7.99-1479-g6fb2ea314f83  ***
Hello World! nrf52840dk_nrf52840

Running ninja -Cbuild sysbuild_menuconfig will provide a sysbuild configuration interface:

menuconfig for hello_world is started as always so that the user doesn't need to change workflow.

• west build -bnrf52840dk_nrf52840 samples/hello_world -t menuconfig
  

menuconfig for mcuboot can be started by pre-fixing menuconfig with the name of the image.

• west build -bnrf52840dk_nrf52840 samples/hello_world/ -t mcuboot_menuconfig
  

If users want to build using sysbuild per default, then a config build option can be set, like:

$ west config build.sysbuild true

which will build using sysbuild per default.
A user enabling sysbuild per default can still choose to build without sysbuild in specific cases by applying --no-sysbuild, like:

$ west build -bnrf52840dk_nrf52840 samples/hello_world/ ---no-sysbuild

Slides from devreview presentaion:
SYSBuild architectural overview

---

List of alternative name proposals instead of sysbuild:

• Aeolus, proposed here

  In Greek mythology, Aeolus was the keeper of the winds

[tejlmand]

FYI @shubhamkulkarni97

[nashif]

@tejlmand does this support the model used in #37872, where mcuboot is not a zephyr application but a baremetal bootloader or this #37098 (secureshield)?

[tejlmand]

@tejlmand does this support the model used in #37872, where mcuboot is not a zephyr application but a baremetal bootloader

The infrastructure in this RFC supports adding extra bootloaders, either Zephyr based or bare-metal.
The exact implementation details for the Espressif mcuboot or Espressif IDF bootloader is something I will coordinate with @shubhamkulkarni97 and @sylvioalves .

or this #37098 (secureshield)?

This is one more PR which should benefit from the multi image build infrastructure in this RFC.
@YuguoWH feel free to take a look at this RFC, and let me know if you would like to see how #37098 could fit into this scheme.

[nordicjm]

The issue with setting up a build and re-configuring it with menuconfig and getting an invalid string for e.g. the mcuboot signing key seems to be an issue with how the cmake cache works.

[nvlsianpu]

As I understand there is dedicated namespace for these Kconfig properties (and will never merge to with the application properties).
For instance this property does something else than CONFIG_BOOTLOADER_MCUBOOT of zephyr-rtos app.
I want to avoid confusion.

[tejlmand]

I believe the help text can definitely be improved.

But whether we should invent two different setting names or have them identical as now depends a lot on how you look at this.

The Zephyr setting states:

zephyr/Kconfig.zephyr

Lines 682 to 686 in 83d73f6

	This option signifies that the target uses MCUboot as a bootloader,
	or in other words that the image is to be chain-loaded by MCUboot.
	This sets several required build system and Device Tree options in
	order for the image generated to be bootable using the MCUboot open
	source bootloader. Currently this includes:

and my view on this is that this is also true for the sysbuild BOOTLOADER_MCUBOOT because it propagates this setting to the application so that the app is chain loaded by MCUboot, as well as devicetree is setup accordingly.
Not inside sysbuild itself, but in the images built by sysbuild.
Ref:

zephyr/share/sysbuild/CMakeLists.txt

Lines 33 to 37 in 70e05e2

	# Propagate bootloader and signing settings from this system to the MCUboot and
	# application image build systems.
	if(SB_CONFIG_BOOTLOADER_MCUBOOT)
	set(${app_name}_CONFIG_BOOTLOADER_MCUBOOT y CACHE STRING
	"MCUBOOT is enabled as bootloader" FORCE

Of course sysbuild itself does one more thing which the application itself cannot do, and that is building and flashing of MCUboot in addition.

I believe having identical name for BOOTLOADER_MCUBOOT makes it easier for users to transition to sysbuild and understand how to build a sample with MCUboot, and that the small addition that sysbuild provides is not sufficient to justify two different names.

[mbolivar-nordic]

OK with the west changes. Please send a follow-up commit adding --domain to the synopsis (not going to -1 so you don't have to get your +1s again)

[tejlmand]

Please send a follow-up commit adding --domain to the synopsis (not going to -1 so you don't have to get your +1s again)

Done: #48678

[ram1kor]

Hi, I still have a question on "sysbuild with custom board."
When I build application with "west build -p -b <custum_board>" the build goes thru without any issues. But when I try to build "west build -p -b <custum_board> --sysbuild -- -DSB_CONFIG_BOOTLOADER_MCUBOOT=n" the build is not able to find the custom board. Please let me know what are the configuration changes that I am missing for using sysbuild for custom board. Note: I do not want to add the custom board under zephyr/board/arm but I would like to maintain the architecture as shown in the attached image.

[tejlmand]

do not want to add the custom board under zephyr/board/arm but I would like to maintain the architecture as shown in the attached image.

@ram1kor are you perhaps setting a board root in your sample's CMakeLists.txt file like this:

set(BOARD_ROOT ${CMAKE_CURRENT_LIST_DIR})

If you are, then sysbuild will not be able to pick up your board root cause it doesn't parse the CMakeLists.txt file of the sample.
What you can do is telling sysbuild about your custom board root like this:

west build --sysbuild -b <your_board> <your_sample> -- -DBOARD_ROOT=<path-to-your-sample>

another option is to turn your repo into a Zephyr module and specify the boards root at the module.yml using board_root: <path>.
That will have a second benefit, as that will allow any of your samples or Zephyt test sample to be built against your custom board.
See more here: https://docs.zephyrproject.org/latest/develop/modules.html#build-settings

[gkujawsk]

I've tried to build hello_world for nucleo_f746zg board according to the instruction using the following command:
west build -b nucleo_f746zg samples/hello_world/ --sysbuild -- -DSB_CONFIG_BOOTLOADER_MCUBOOT=y
However, the build complains about #include <st/f7/stm32f746zgtx-pinctrl.dtsi> not being found:
zephyr/boards/arm/nucleo_f746zg/nucleo_f746zg.dts:9:10: fatal error: st/f7/stm32f746zgtx-pinctrl.dtsi: No such file or directory

pinctrl.dtsi files comes with stm32-hal. It seems that the build system misses the include path pointing to stm32-hal.

In the very same time the traditional build (eg without --sysbuild option) works correctly.

[erwango]

@gkujawsk Please run west update