Zephyr includes the open-source MCUboot bootloader as a module, and makes it easy to use as a bootloader for Zephyr applications. A Zephyr app can be easily built to load with MCUboot. Zephyr uses a tool called Sysbuild that also enables building the MCUboot bootloader and Zephyr app with the same build command. To use Sysbuild with CLI, see Building a sample with MCUboot and Sysbuild. A more advanced use-case is MCUboot RAM Loading with Zephyr.
This guide uses NXP's MCUXpresso extension for VS Code to build a sample app with MCUboot. To get started with VS Code, see the Zephyr Knowledge Hub. Basic knowledge of using VS Code to import and build applications is required before following these steps.
To get started, import the Zephyr application into VS Code. This example uses the hello_world sample:
To enable Sysbuild for this project, start in the Projects view, right-click on the project, click the Configure menu, and click "Set Sysbuild".
A pop-up appears in the center of the top of the VS Code window. Select the Enable option. To learn more, see Configuring Sysbuild in VS Code.
We also want to configure the app to build for MCUboot by setting the Cmake variable SB_CONFIG_BOOTLOADER_MCUBOOT=y. To configure Cmake variables, Expand the project, and expand the Build Configurations. Select the build configuration to edit, and click the pencil icon on the right. Here we are editing the default "debug" configuration for the hello_world project.
In the field CMake Extra Args, add SB_CONFIG_BOOTLOADER_MCUBOOT="y" and CONFIG_BUILD_OUTPUT_HEX="y", then click Save. To learn more, see Cmake Variables in VS Code.
To build the project, right-click the project and select Pristine Build. This builds two images: one for MCUboot, and another for the app hello_world.
After both images have been built for the first time, hex outputs need to be enabled for the mcuboot context. Right click over the project name -> Configure -> Open Kconfig Configuration
When the new window appears, choose the mcuboot domain.
In the MCUboot configurations window Build and Link Features -> Build Options -> Build a binary in HEX format, then click Save
Build the project another time
Debugging the app will not program the MCUboot image to the flash. But we can flash either image to the board using VS Code. In the Projects view, right-click the project and select Flash the Selected Target.
In the pop-up at the top of the window, select the zephyr.hex file in Domain: mcuboot. VS Code will flash that zephyr.hex file to the board.
Now you we can debug or flash the app.
When the board boots, it prints similar to below. This shows MCUboot boots first, finds the app image in slot0, and jumps to the hello_world app.
*** Booting MCUboot v2.4.0-rc1-3-gee39e2d694bd ***
*** Using Zephyr OS build v4.4.0 ***
I: Starting bootloader
I: Image index: 0, Swap type: none
I: Image index: 0, Swap type: none
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: Image index: 0, Swap type: none
I: Image index: 0, Swap type: none
I: Image index: 0, Swap type: none
I: Image index: 0, Swap type: none
I: Bootloader chainload address offset: 0x14000
I: Image version: v0.0.0
I: Jumping to the first image slot
*** Booting Zephyr OS build v4.4.0 ***
Hello World! frdm_mcxn947/mcxn947/cpu0