MCUXpresso SDK Documentation
Open on Repo Open an Issue
Source (.md/.rst) Page PDF (.pdf)

MCUboot opensource

MCUboot opensource#

Overview#

The mcuboot_opensource is a second stage bootloader based on MCUBoot project. It is primarily meant to be used together with OTA (over-the-air) update examples to demonstrate functionality of application self-upgrade.

Flash memory layout#

Flash memory is divided into multiple regions to allocate space for bootloader, main application and application update:

  • MCUBoot partition (reserved for bootloader itself, starts at the beginning of the FLASH memory)

  • Primary application partition (active application image)

  • Secondary application partition (candidate application - place to download OTA image to be used for update)

The partitioning is defined by definitions in flash_partitioning.h header file. The MCUBoot partition starts at the very beginning of the FLASH memory and spans up to BOOT_FLASH_ACT_APP. The primary partition occupies range starting from BOOT_FLASH_ACT_APP up to BOOT_FLASH_CAND_APP. The secondary partition starts at BOOT_FLASH_CAND_APP and it is automatically assigned the same size as the primary one. The rest of the memory may be used by the application for arbitrary purposes.

Important notice: should you need to change the partitioning please make sure to update also the header file used by the OTA application! If the partitioning information used by the bootloader and the application is not in sync, it may lead to malfunction of boot/OTA process or to upredictable behavior.

Signing the application image#

MCUBoot expects signed application image in specific format to be present in the primary partition. The very same image format is also used for OTA updates.

A dedicated tool (imgtool) is used to generate application image in the desired format. It is implemented as a Python script which can be found in the SDK package in middleware/mcuboot_opensource/scripts folder.

Alternatively the tool can be installed by the Python package manager:

pip install imgtool

Please note that imgtool version installed by the Python package manager is not guaranteed to be compatible with MCUBoot present in your SDK package.

The mcuboot_opensource SDK project comes with its set of private-public keys. Key pairs used in ota examples are located in middleware\mcuboot_opensource\boot\nxp_mcux_sdk\keys. The public key is already pre-configured in the source code of MCUBoot in a form of an array initializer.

To sign an application binary, imgtool must be provided with respective private key and a set of parameters as in the following example:

imgtool sign --key sign-ecdsa-p256-priv.pem
             --align 4
             --header-size 0x400
             --pad-header
             --slot-size 0x200000
             --max-sectors 800
             --version "1.0"
             app_binary.bin
             app_binary_SIGNED.bin

NOTE that other boards may require different parameters - check their readme file.

The parameters used in the example above are tested with out-of-the-box configuration of MCUBoot and OTA examples in the SDK package. However, some of them may depend on the application or board setup and thus may need to be modified. See the MCUBoot documentation for the meaning of the parameters and align them with your project setup if necessary. https://docs.mcuboot.com/imgtool.html

Using MCUXpresso Secure Provisioning Tool for MCUBoot image signing#

MCUXpresso Secure Provisioning Tool from verion 9 supports automation for MCUBoot image signing. Using this tool it’s possible to setup the device for entire boot chain in a few steps.

Prepare the Demo#

  1. Connect a USB cable between the PC host and the OpenSDA(or USB to Serial) USB port on the target board.

  2. Open a serial terminal on PC for OpenSDA serial(or USB to Serial) device with these settings:

    • 115200 baud rate

    • 8 data bits

    • No parity

    • One stop bit

    • No flow control

    • line ending set for LF (‘\n’)

  3. Build project and program it to the target board.

  4. Either press the reset button on your board or launch the debugger in your IDE to begin running the demo.

Running the demo#

When the demo runs successfully, the terminal will display the following:

hello sbl.
Bootloader Version 1.0.0

Further messages printed to the terminal depend on the content of the FLASH memory. In case there was no application programmed so far (i.e. the FLASH was blank), similar text as the following would be printed:

Primary image: magic=unset, swap_type=0x1, copy_done=0x3, image_ok=0x3
Secondary image: magic=unset, swap_type=0x1, copy_done=0x3, image_ok=0x3
Boot source: none
Swap type: none
erasing trailer; fa_id=2
Unable to find bootable image

At this point the bootloader is in place, resident in the FLASH memory. You may stop debuger, switch to an OTA example and follow the relevant readme located in example’s directory.

Advanced topics#

Flash remapping functionality

Encrypted XIP support

OTA update by using SB3 file

Supported Boards#

LPCXpresso55S69
Hardware requirements

  • LPCXpresso 55S69 board

  • Mini/micro USB cable

  • Personal Computer

Board settings

No special HW settings are required.

In case of MCUBoot for LPC55S69 there is currently no image revert mechanism. This is due to Flash ECC capability that doesn’t allow incremental flash programming. MCUBoot’s revert strategies rely on this mechanism, therefore it’s not currently practical to use any of the MCUBoot’s revert strategies like image swapping by move or stratch area.

MCUBoot memory layout

Region

From

To

Size

MCUboot code

0x00000000

0x0001FFFF

128kB

Primary slot

0x00020000

0x0004FFFF

192kB

Secondary slot

0x00050000

0x0007FFFF

192kB

  • MCUBoot header size is set to 1024 bytes

  • Signing algorithm is ECDSA-P256

  • Write alignment is 4 bytes

  • MCUBoot is configured to use its OVERWRITE_ONLY image handling strategy

  • To manually enter serial recovery mode during reset, keep button SW1 pressed

Image signing example
imgtool sign   --key sign-ecdsa-p256-priv.pem
               --align 4
               --version 1.1
               --slot-size 0x30000
               --header-size 0x400
               --pad-header
               ota_mcuboot_basic.bin
               ota_mcuboot_basic.SIGNED.bin

NOTE - there is alternative prj.conf file named prj-mbedtls.conf that can be used to enable mbedtls with HW crypto acceleration.

FRDM-IMXRT1152
Hardware requirements

  • Type-C USB cable

  • FRDM-IMXRT1152 board

  • Personal Computer

Board settings
MCUBoot layout

Region

From

To

Size

MCUboot code

0x30000000

0x3003FFFF

256kB

Primary slot

0x30040000

0x3023FFFF

2048kB

Secondary slot

0x30240000

0x3043FFFF

2048kB

  • MCUBoot header size is set to 1024 bytes

  • Signing algorithm is ECDSA-P256

  • Write alignment is 4 bytes

  • MCUBoot is configured to use its DIRECT_XIP image handling strategy

  • Flash remapping HW feature is used for zero-overhead image swapping

  • To manually enter serial recovery mode, keep the user button pressed during reset, then release it

Image signing example
imgtool sign   --key sign-ecdsa-p256-priv.pem
               --align 4
               --version 1.1
               --slot-size 0x200000
               --header-size 0x400
               --pad-header
               ota_mcuboot_basic.bin
               ota_mcuboot_basic.SIGNED.bin

Note that for the first image flashed manually together with the bootloader additional imgtool options “–pad” and “–confirm” must be used. Otherwise the bootloader would reject the image for missing data in the trailer area.

EVK-MIMXRT1020
Hardware requirements

  • Mini/micro USB cable

  • MIMXRT1020-EVK board

  • Personal Computer

Board settings
MCUBoot layout

Region

From

To

Size

MCUboot code

0x60000000

0x6003FFFF

256kB

Primary slot

0x60040000

0x6023FFFF

2048kB

Secondary slot

0x60240000

0x6043FFFF

2048kB

  • MCUBoot header size is set to 1024 bytes

  • Signing algorithm is ECDSA-P256

  • Write alignment is 4 bytes

  • MCUBoot is configured to use SWAP_MOVE image handling strategy

  • To manually enter serial recovery mode during reset, keep user button pressed

Image signing example
imgtool sign   --key sign-ecdsa-p256-priv.pem
               --align 4
               --version 1.1
               --slot-size 0x200000
               --header-size 0x400
               --pad-header
               ota_mcuboot_basic.bin
               ota_mcuboot_basic.SIGNED.bin
Custom configuration - Encrypted XIP

Region

From

To

Size

MCUboot code

0x60000000

0x6003FFFF

256kB

Primary slot

0x60040000

0x6023FFFF

2048kB

Secondary slot

0x60240000

0x6043FFFF

2048kB

Encryption metadata

0x60440000

0x60440FFF

4kB

This custom build generates a project with predefined configuration to utilize Encrypted XIP mode. For more information please see Encrypted XIP and MCUboot.

  • MCUBoot header size is set to 1024 bytes

  • Signing algorithm is ECDSA-P256

  • Write alignment is 4 bytes

  • MCUBoot is configured for Encrypted XIP mode using modified MCUBOOT_OVERWRITE_ONLY image update strategy

  • MCUboot uses ECDH-P256 to secure AES key for image encryption

  • Primary slot is encrypted by BEE module to utilize encrypted XIP

Image signing example:

imgtool sign --key sign-ecdsa-p256-priv.pem
             --align 4
             --version 1.1
             --slot-size 0x200000
             --header-size 0x400
             --max-sectors 59
             --pad-header
             -E enc-ec256-pub.pem
             ota_mcuboot_basic.bin
             ota_mcuboot_basic.SIGNED.bin

Project building example:

The project is built using west tool. For more information please see MCUXpresso SDK documentation.

Bootloader:

west build -p always examples/ota_examples/mcuboot_opensource --toolchain iar --config flexspi_nor_debug -b evkmimxrt1020 -t guiproject -DCONF_FILE="examples/ota_examples/_custom_cfg/rt10xx/mcuboot_opensource.conf" -d builds/mcuboot

OTA application:

west build -p always examples/ota_examples/ota_mcuboot_basic --toolchain iar --config flexspi_nor_debug -b evkmimxrt1020 -t guiproject -DCONF_FILE="examples/ota_examples/_custom_cfg/rt10xx/ota_mcuboot_basic.conf" -d builds/ota_mcuboot_basic
MIMXRT1040-EVK
Hardware requirements

  • Mini/micro USB cable

  • MIMXRT1040-EVK board

  • Personal Computer

Board settings
MCUBoot layout

Region

From

To

Size

MCUboot code

0x60000000

0x6003FFFF

256kB

Primary slot

0x60040000

0x6023FFFF

2048kB

Secondary slot

0x60240000

0x6043FFFF

2048kB

  • MCUBoot header size is set to 1024 bytes

  • Signing algorithm is ECDSA-P256

  • Write alignment is 4 bytes

  • MCUBoot is configured to use its DIRECT_XIP image handling strategy

  • Flash remapping HW feature is used for zero-overhead image swapping

  • To manually enter serial recovery mode, keep the user button pressed during reset, then release it

Image signing example
imgtool sign   --key sign-ecdsa-p256-priv.pem
               --align 4
               --version 1.1
               --slot-size 0x200000
               --header-size 0x400
               --pad-header
               ota_mcuboot_basic.bin
               ota_mcuboot_basic.SIGNED.bin

Note that for the first image flashed manually together with the bootloader additional imgtool options “–pad” and “–confirm” must be used. Otherwise the bootloader would reject the image for missing data in the trailer area.

Custom configuration - Encrypted XIP

Region

From

To

Size

MCUboot code

0x60000000

0x6003FFFF

256kB

Primary slot

0x60040000

0x6023FFFF

2048kB

Secondary slot

0x60240000

0x6043FFFF

2048kB

Encryption metadata

0x60440000

0x60440FFF

4kB

This custom build generates a project with predefined configuration to utilize Encrypted XIP mode. For more information please see Encrypted XIP and MCUboot.

  • MCUBoot header size is set to 1024 bytes

  • Signing algorithm is ECDSA-P256

  • Write alignment is 4 bytes

  • MCUBoot is configured for Encrypted XIP mode using modified MCUBOOT_OVERWRITE_ONLY image update strategy

  • MCUboot uses ECDH-P256 to secure AES key for image encryption

  • Primary slot is encrypted by BEE module to utilize encrypted XIP

Image signing example:

imgtool sign --key sign-ecdsa-p256-priv.pem
             --align 4
             --version 1.1
             --slot-size 0x200000
             --header-size 0x400
             --max-sectors 59
             --pad-header
             -E enc-ec256-pub.pem
             ota_mcuboot_basic.bin
             ota_mcuboot_basic.SIGNED.bin

Project building example:

The project is built using west tool. For more information please see MCUXpresso SDK documentation.

Bootloader:

west build -p always examples/ota_examples/mcuboot_opensource --toolchain iar --config flexspi_nor_debug -b evkmimxrt1040 -t guiproject -DCONF_FILE="examples/ota_examples/_custom_cfg/rt10xx/mcuboot_opensource.conf" -d builds/evkmimxrt1040_mcuboot

OTA application:

west build -p always examples/ota_examples/ota_mcuboot_basic --toolchain iar --config flexspi_nor_debug -b evkmimxrt1040 -t guiproject -DCONF_FILE="examples/ota_examples/_custom_cfg/rt10xx/ota_mcuboot_basic.conf" -d builds/evkmimxrt1040_ota_mcuboot_basic
EVKB-IMXRT1050
Hardware requirements

  • Mini/micro USB cable

  • EVKB-IMXRT1050 board

  • Personal Computer

Board settings
MCUBoot layout

Region

From

To

Size

MCUboot code

0x60000000

0x6003FFFF

256kB

Primary slot

0x60040000

0x6023FFFF

2048kB

Secondary slot

0x60240000

0x6043FFFF

2048kB

  • MCUBoot header size is set to 1024 bytes

  • Signing algorithm is ECDSA-P256

  • Write alignment is 4 bytes

  • MCUBoot is configured to use SWAP_MOVE image handling strategy

  • To manually enter serial recovery mode, keep the user button pressed during reset, then release it

Image signing example
imgtool sign   --key sign-ecdsa-p256-priv.pem
               --align 4
               --version 1.0
               --slot-size 0x200000
               --header-size 0x400
               --pad-header
               ota_mcuboot_basic.bin
               ota_mcuboot_basic.SIGNED.bin
Custom configuration - Encrypted XIP

Region

From

To

Size

MCUboot code

0x60000000

0x6003FFFF

256kB

Primary slot

0x60040000

0x6023FFFF

2048kB

Secondary slot

0x60240000

0x6043FFFF

2048kB

Encryption metadata

0x60440000

0x6047FFFF

256kB

This custom build generates a project with predefined configuration to utilize Encrypted XIP mode. For more information please see Encrypted XIP and MCUboot.

  • MCUBoot header size is set to 1024 bytes

  • Signing algorithm is ECDSA-P256

  • Write alignment is 4 bytes

  • MCUBoot is configured for Encrypted XIP mode using modified MCUBOOT_OVERWRITE_ONLY image update strategy

  • MCUboot uses ECDH-P256 to secure AES key for image encryption

  • Primary slot is encrypted by BEE module to utilize encrypted XIP

Image signing example:

imgtool sign --key sign-ecdsa-p256-priv.pem
             --align 4
             --version 1.1
             --slot-size 0x200000
             --header-size 0x400
             --max-sectors 59
             --pad-header
             -E enc-ec256-pub.pem
             ota_mcuboot_basic.bin
             ota_mcuboot_basic.SIGNED.bin

Project building example:

The project is built using west tool. For more information please see MCUXpresso SDK documentation.

Bootloader:

west build -p always examples/ota_examples/mcuboot_opensource --toolchain iar --config flexspi_nor_debug -b evkbimxrt1050 -t guiproject -DCONF_FILE="examples/ota_examples/_custom_cfg/rt10xx/mcuboot_opensource.conf" -d builds/mcuboot

OTA application:

west build -p always examples/ota_examples/ota_mcuboot_basic --toolchain iar --config flexspi_nor_debug -b evkbimxrt1050 -t guiproject -DCONF_FILE="examples/ota_examples/_custom_cfg/rt10xx/ota_mcuboot_basic.conf" -d builds/ota_mcuboot_basic
MIMXRT1060-EVKB
Hardware requirements

  • Mini/micro USB cable

  • MIMXRT1060-EVKB board

  • Personal Computer

Board settings
MCUBoot layout

Region

From

To

Size

MCUboot code

0x60000000

0x6003FFFF

256kB

Primary slot

0x60040000

0x6023FFFF

2048kB

Secondary slot

0x60240000

0x6043FFFF

2048kB

  • MCUBoot header size is set to 1024 bytes

  • Signing algorithm is ECDSA-P256

  • Write alignment is 4 bytes

  • MCUBoot is configured to use its DIRECT_XIP image handling strategy

  • Flash remapping HW feature is used for zero-overhead image swapping

  • To manually enter serial recovery mode, keep the user button pressed during reset, then release it

Image signing example
imgtool sign   --key sign-ecdsa-p256-priv.pem
               --align 4
               --version 1.1
               --slot-size 0x200000
               --header-size 0x400
               --pad-header
               ota_mcuboot_basic.bin
               ota_mcuboot_basic.SIGNED.bin

Note that for the first image flashed manually together with the bootloader additional imgtool options “–pad” and “–confirm” must be used. Otherwise the bootloader would reject the image for missing data in the trailer area.

Custom configuration - Encrypted XIP

Region

From

To

Size

MCUboot code

0x60000000

0x6003FFFF

256kB

Primary slot

0x60040000

0x6023FFFF

2048kB

Secondary slot

0x60240000

0x6043FFFF

2048kB

Encryption metadata

0x60440000

0x60440FFF

4kB

This custom build generates a project with predefined configuration to utilize Encrypted XIP mode. For more information please see Encrypted XIP and MCUboot.

  • MCUBoot header size is set to 1024 bytes

  • Signing algorithm is ECDSA-P256

  • Write alignment is 4 bytes

  • MCUBoot is configured for Encrypted XIP mode using modified MCUBOOT_OVERWRITE_ONLY image update strategy

  • MCUboot uses ECDH-P256 to secure AES key for image encryption

  • Primary slot is encrypted by BEE module to utilize encrypted XIP

Image signing example:

imgtool sign --key sign-ecdsa-p256-priv.pem
             --align 4
             --version 1.1
             --slot-size 0x200000
             --header-size 0x400
             --max-sectors 59
             --pad-header
             -E enc-ec256-pub.pem
             ota_mcuboot_basic.bin
             ota_mcuboot_basic.SIGNED.bin

Project building example:

The project is built using west tool. For more information please see MCUXpresso SDK documentation.

Bootloader:

west build -p always examples/ota_examples/mcuboot_opensource --toolchain iar --config flexspi_nor_debug -b evkbmimxrt1060 -t guiproject -DCONF_FILE="examples/ota_examples/_custom_cfg/rt10xx/mcuboot_opensource.conf" -d builds/mcuboot

OTA application:

west build -p always examples/ota_examples/ota_mcuboot_basic --toolchain iar --config flexspi_nor_debug -b evkbmimxrt1060 -t guiproject -DCONF_FILE="examples/ota_examples/_custom_cfg/rt10xx/ota_mcuboot_basic.conf" -d builds/ota_mcuboot_basic
MIMXRT1060-EVKC
Hardware requirements

  • Mini/micro USB cable

  • MIMXRT1060-EVKC board

  • Personal Computer

Board settings
MCUBoot layout

Region

From

To

Size

MCUboot code

0x60000000

0x6003FFFF

256kB

Primary slot

0x60040000

0x6023FFFF

2048kB

Secondary slot

0x60440000

0x6083FFFF

2048kB

  • MCUBoot header size is set to 1024 bytes

  • Signing algorithm is ECDSA-P256

  • Write alignment is 4 bytes

  • MCUBoot is configured to use its DIRECT_XIP image handling strategy

  • Flash remapping HW feature is used for zero-overhead image swapping

  • To manually enter serial recovery mode, keep the user button pressed during reset, then release it

Image signing example
imgtool sign   --key sign-ecdsa-p256-priv.pem
               --align 4
               --version 1.1
               --slot-size 0x200000
               --header-size 0x400
               --pad-header
               ota_mcuboot_basic.bin
               ota_mcuboot_basic.SIGNED.bin

Note that for the first image flashed manually together with the bootloader additional imgtool options “–pad” and “–confirm” must be used. Otherwise the bootloader would reject the image for missing data in the trailer area.

Custom configuration - Encrypted XIP

Region

From

To

Size

MCUboot code

0x60000000

0x6003FFFF

256kB

Primary slot

0x60040000

0x6023FFFF

2048kB

Secondary slot

0x60240000

0x6043FFFF

2048kB

Encryption metadata

0x60440000

0x60440FFF

4kB

This custom build generates a project with predefined configuration to utilize Encrypted XIP mode. For more information please see Encrypted XIP and MCUboot.

  • MCUBoot header size is set to 1024 bytes

  • Signing algorithm is ECDSA-P256

  • Write alignment is 4 bytes

  • MCUBoot is configured for Encrypted XIP mode using modified MCUBOOT_OVERWRITE_ONLY image update strategy

  • MCUboot uses ECDH-P256 to secure AES key for image encryption

  • Primary slot is encrypted by BEE module to utilize encrypted XIP

Image signing example:

imgtool sign --key sign-ecdsa-p256-priv.pem
             --align 4
             --version 1.1
             --slot-size 0x200000
             --header-size 0x400
             --max-sectors 59
             --pad-header
             -E enc-ec256-pub.pem
             ota_mcuboot_basic.bin
             ota_mcuboot_basic.SIGNED.bin

Project building example:

The project is built using west tool. For more information please see MCUXpresso SDK documentation.

Bootloader:

west build -p always examples/ota_examples/mcuboot_opensource --toolchain iar --config flexspi_nor_debug -b evkcmimxrt1060 -t guiproject -DCONF_FILE="examples/ota_examples/_custom_cfg/rt10xx/mcuboot_opensource.conf" -d builds/mcuboot

OTA application:

west build -p always examples/ota_examples/ota_mcuboot_basic --toolchain iar --config flexspi_nor_debug -b evkcmimxrt1060 -t guiproject -DCONF_FILE="examples/ota_examples/_custom_cfg/rt10xx/ota_mcuboot_basic.conf" -d builds/ota_mcuboot_basic
EVK-MIMXRT1064
Hardware requirements

  • Mini/micro USB cable

  • EVK-MIMXRT1064 board

  • Personal Computer

Board settings
MCUBoot layout

Region

From

To

Size

MCUboot code

0x70000000

0x7003FFFF

256kB

Primary slot

0x70040000

0x7013FFFF

1024kB

Secondary slot

0x70140000

0x7023FFFF

1024kB

  • MCUBoot header size is set to 1024 bytes

  • Signing algorithm is ECDSA-P256

  • Write alignment is 4 bytes

  • MCUBoot is configured to use its DIRECT_XIP image handling strategy

  • Flash remapping HW feature is used for zero-overhead image swapping

  • To manually enter serial recovery mode, keep the user button pressed during reset, then release it

Image signing example
imgtool sign   --key sign-ecdsa-p256-priv.pem
               --align 4
               --version 1.1
               --slot-size 0x100000
               --header-size 0x400
               --pad-header
               ota_mcuboot_basic.bin
               ota_mcuboot_basic.SIGNED.bin

Note that for the first image flashed manually together with the bootloader additional imgtool options “–pad” and “–confirm” must be used. Otherwise the bootloader would reject the image for missing data in the trailer area.

Custom configuration - Encrypted XIP

Region

From

To

Size

MCUboot code

0x70000000

0x7003FFFF

256kB

Primary slot

0x70040000

0x7013FFFF

1024kB

Secondary slot

0x70140000

0x7023FFFF

1024kB

Encryption metadata

0x70240000

0x70240FFF

4kB

This custom build generates a project with predefined configuration to utilize Encrypted XIP mode. For more information please see Encrypted XIP and MCUboot.

  • MCUBoot header size is set to 1024 bytes

  • Signing algorithm is ECDSA-P256

  • Write alignment is 4 bytes

  • MCUBoot is configured for Encrypted XIP mode using modified MCUBOOT_OVERWRITE_ONLY image update strategy

  • MCUboot uses ECDH-P256 to secure AES key for image encryption

  • Primary slot is encrypted by BEE module to utilize encrypted XIP

Image signing example:

imgtool sign --key sign-ecdsa-p256-priv.pem
             --align 4
             --version 1.1
             --slot-size 0x200000
             --header-size 0x400
             --max-sectors 59
             --pad-header
             -E enc-ec256-pub.pem
             ota_mcuboot_basic.bin
             ota_mcuboot_basic.SIGNED.bin

Project building example:

The project is built using west tool. For more information please see MCUXpresso SDK documentation.

Bootloader:

west build -p always examples/ota_examples/mcuboot_opensource --toolchain iar --config flexspi_nor_debug -b evkmimxrt1064 -t guiproject -DCONF_FILE="examples/ota_examples/_custom_cfg/rt1064/mcuboot_opensource.conf" -d builds/mcuboot

OTA application:

west build -p always examples/ota_examples/ota_mcuboot_basic --toolchain iar --config flexspi_nor_debug -b evkmimxrt1064 -t guiproject -DCONF_FILE="examples/ota_examples/_custom_cfg/rt1064/ota_mcuboot_basic.conf" -d builds/ota_mcuboot_basic
MIMXRT1160-EVK
Hardware requirements

  • Mini/micro USB cable

  • MIMXRT1160-EVK board

  • Personal Computer

Board settings
MCUBoot layout

Region

From

To

Size

MCUboot code

0x30000000

0x3003FFFF

256kB

Primary slot

0x30040000

0x3023FFFF

2048kB

Secondary slot

0x30240000

0x3043FFFF

2048kB

  • MCUBoot header size is set to 1024 bytes

  • Signing algorithm is CDSA-P256

  • Write alignment is 4 bytes

  • MCUBoot is configured to use its DIRECT_XIP image handling strategy

  • Flash remapping HW feature is used for zero-overhead image swapping

  • To manually enter serial recovery mode, keep the user button pressed during reset, then release it

Image signing example
imgtool sign   --key sign-ecdsa-p256-priv.pem
               --align 4
               --version 1.1
               --slot-size 0x200000
               --header-size 0x400
               --pad-header
               ota_mcuboot_basic.bin
               ota_mcuboot_basic.SIGNED.bin

Note that for the first image flashed manually together with the bootloader additional imgtool options “–pad” and “–confirm” must be used. Otherwise the bootloader would reject the image for missing data in the trailer area.

MIMXRT1170-EVKB
Hardware requirements

  • Mini/micro USB cable

  • MIMXRT1170-EVKB board

  • Personal Computer

Board settings
MCUBoot layout

Region

From

To

Size

MCUboot code

0x30000000

0x3003FFFF

256kB

Primary slot

0x30040000

0x3023FFFF

2048kB

Secondary slot

0x30240000

0x3043FFFF

2048kB

  • MCUBoot header size is set to 1024 bytes

  • Signing algorithm is ECDSA-P256

  • Write alignment is 4 bytes

  • MCUBoot is configured to use its DIRECT_XIP image handling strategy

  • Flash remapping HW feature is used for zero-overhead image swapping

  • To manually enter serial recovery mode, keep the user button pressed during reset, then release it

Image signing example
imgtool sign   --key sign-ecdsa-p256-priv.pem
               --align 4
               --version 1.1
               --slot-size 0x200000
               --header-size 0x400
               --pad-header
               ota_mcuboot_basic.bin
               ota_mcuboot_basic.SIGNED.bin

Note that for the first image flashed manually together with the bootloader additional imgtool options “–pad” and “–confirm” must be used. Otherwise the bootloader would reject the image for missing data in the trailer area.

MIMXRT1180-EVK
Hardware requirements

  • Mini/micro USB cable

  • MIMXRT1180-EVK board

  • Personal Computer

Board settings

The mcuboot binary must be processed by SPSDK tools to allow ROM code to boot it from flash. If this is not done automatically during build/postbuild it needs to be done manually. When using NXP tools such as MCUXpresso IDE or MCUXpresso Secure Provisioning Tool this should be done automatically by the tool.

MCUBoot layout

Region

From

To

Size

MCUboot code

0x28000000

0x2803FFFF

256kB

Primary slot

0x28040000

0x2823FFFF

2048kB

Secondary slot

0x28240000

0x2843FFFF

2048kB

  • MCUBoot header size is set to 1024 bytes

  • Signing algorithm is ECDSA-P256

  • Write alignment is 4 bytes

  • MCUBoot is configured to use SWAP_MOVE image handling strategy

Image signing example
imgtool sign   --key sign-ecdsa-p256-priv.pem
               --align 4
               --version 1.1
               --slot-size 0x200000
               --header-size 0x400
               --pad-header
               ota_mcuboot_basic.bin
               ota_mcuboot_basic.SIGNED.bin
EVK-MIMXRT595
Hardware requirements

  • Micro USB cable

  • EVK-MIMXRT595 board

  • Personal Computer

Board settings
Jumper setup

JP4: 1-2

Debug console UART is configured to use pins of J27, connect the board with PC by USB/UART converter:

  • board UART RX (pin 1 on J27) - connect to TX pin on converter

  • board UART TX (pin 2 on J27) - connect to RX pin on converter

  • board GND (pin 7 on J29) - connect to GND pin on converter

MCUBoot layout

Region

From

To

Size

MCUboot code

0x80000000

0x8003FFFF

256kB

Primary slot

0x80040000

0x8023FFFF

2048kB

Secondary slot

0x80240000

0x8043FFFF

2048kB

  • MCUBoot header size is set to 1024 bytes

  • Signing algorithm is ECDSA-P256

  • Write alignment is 4 bytes

  • MCUBoot is configured to use its DIRECT_XIP image handling strategy

  • Flash remapping HW feature is used for zero-overhead image swapping

Image signing example
imgtool sign   --key sign-ecdsa-p256-priv.pem
               --align 4
               --version 1.1
               --slot-size 0x200000
               --header-size 0x400
               --pad-header
               ota_mcuboot_basic.bin
               ota_mcuboot_basic.SIGNED.bin

Note that for the first image flashed manually together with the bootloader additional imgtool options “–pad” and “–confirm” must be used. Otherwise the bootloader would reject the image for missing data in the trailer area.

EVK-MIMXRT685
Hardware requirements

  • Micro USB cable

  • EVK-MIMXRT685 board

  • Personal Computer

Board settings
MCUBoot layout

Region

From

To

Size

MCUboot code

0x80000000

0x8003FFFF

256kB

Primary slot

0x80040000

0x8023FFFF

2048kB

Secondary slot

0x80240000

0x8043FFFF

2048kB

  • MCUBoot header size is set to 1024 bytes

  • Signing algorithm is RSA-2048

  • Write alignment is 4 bytes

  • MCUBoot is configured to use its DIRECT_XIP image handling strategy

  • Flash remapping HW feature is used for zero-overhead image swapping

Image signing example
imgtool sign   --key sign-rsa2048-priv.pem
               --align 4
               --version 1.1
               --slot-size 0x200000
               --header-size 0x400
               --pad-header
               ota_mcuboot_basic.bin
               ota_mcuboot_basic.SIGNED.bin

Note that for the first image flashed manually together with the bootloader additional imgtool options “–pad” and “–confirm” must be used. Otherwise the bootloader would reject the image for missing data in the trailer area.

MIMXRT685-AUD-EVK
Hardware requirements

  • Micro USB cable

  • MIMXRT685-AUD-EVK board

  • Personal Computer

Board settings
MCUBoot layout

Region

From

To

Size

MCUboot code

0x80000000

0x8003FFFF

256kB

Primary slot

0x80040000

0x8023FFFF

2048kB

Secondary slot

0x80240000

0x8043FFFF

2048kB

  • MCUBoot header size is set to 1024 bytes

  • Signing algorithm is ECDSA-P256

  • Write alignment is 4 bytes

  • MCUBoot is configured to use its DIRECT_XIP image handling strategy

  • Flash remapping HW feature is used for zero-overhead image swapping

Image signing example
imgtool sign   --key sign-ecdsa-p256-priv.pem
               --align 4
               --version 1.1
               --slot-size 0x200000
               --header-size 0x400
               --pad-header
               ota_mcuboot_basic.bin
               ota_mcuboot_basic.SIGNED.bin

Note that for the first image flashed manually together with the bootloader additional imgtool options “–pad” and “–confirm” must be used. Otherwise the bootloader would reject the image for missing data in the trailer area.

MIMXRT700-EVK
Hardware requirements

  • MIMXRT700 board

  • Mini/micro USB cable

  • Personal Computer

Board settings

Make sure the board is setup to boot from flash.

MCUBoot layout

In all cases, the MCUBOOT bootloader reserves 256kB at the beginning of the external flash followed by 2MB slots for application.

Region

From

To

Size

MCUboot code

0x28000000

0x2803FFFF

256kB

Primary slot

0x28040000

0x2823FFFF

2048kB

Secondary slot

0x28240000

0x2843FFFF

2048kB

  • MCUBoot header size is set to 1024 bytes

  • Signing algorithm is ECDSA-P256

  • Write alignment is 4 bytes

  • MCUBoot is configured to use its DIRECT_XIP image handling strategy together with FlexSPI flash remapping

  • To manually enter serial recovery mode, keep the user button 1 (SW5) pressed during reset, then release it

Image signing example
imgtool sign   --key sign-ecdsa-p256-priv.pem
               --align 4
               --version 1.1
               --slot-size 0x200000
               --header-size 0x400
               --pad-header
               ota_mcuboot_basic.bin
               ota_mcuboot_basic.SIGNED.bin

Note that for the first image flashed manually together with the bootloader additional imgtool options --pad and --confirm must be used. Otherwise the bootloader would reject the image for missing data in the trailer area.

RD-RW612-BGA
Hardware requirements

  • Mini/micro USB cable

  • Personal Computer

Board settings

Make sure the board is setup to boot from flash.

MCUBoot memory layout

In all cases, the MCUBOOT bootloader reserves 256kB at the beginning of the external flash followed by 2MB slots for application. The resulting layout for the monolithic application will be as follows:

Region

From

To

Size

MCUboot code

0x08000000

0x0803FFFF

256kB

Primary slot

0x08040000

0x0821FFFF

2048kB

Secondary slot

0x08240000

0x0841FFFF

2048kB

  • MCUBoot header size is set to 1024 bytes

  • Signing algorithm is ECDSA-P256

  • Write alignment is 4 bytes

  • MCUBoot is configured to use its DIRECT_XIP image handling strategy together with FlexSPI flash remapping

  • For testing purposes, the image authentication may be disabled in sblconfig.h by uncommenting the CONFIG_BOOT_OTA_TEST definition so that the following is defined:

    #define MCUBOOT_NO_SIGN #define CONFIG_BOOT_HASH_NO_SIGN #define CONFIG_BOOT_DIGEST_TYPE_SHA256

Image signing example
imgtool sign   --key sign-ecdsa-p256-priv.pem
               --align 4
               --version 1.1
               --slot-size 0x200000
               --header-size 0x400
               --pad-header
               ota_mcuboot_basic.bin
               ota_mcuboot_basic.SIGNED.bin

Note that for the first image flashed manually together with the bootloader additional imgtool options --pad and --confirm must be used. Otherwise the bootloader would reject the image for missing data in the trailer area.

Custom configuration - Encrypted XIP

Region

From

To

Size

MCUboot code

0x08000000

0x0803FFFF

256kB

Primary slot

0x08040000

0x0821FFFF

2048kB

Secondary slot

0x08240000

0x0841FFFF

2048kB

Encryption metadata

0x08440000

0x08440FFF

4kB

This custom build generates a project with predefined configuration to utilize Encrypted XIP mode. For more information please see Encrypted XIP and MCUboot.

  • MCUBoot header size is set to 1024 bytes

  • Signing algorithm is ECDSA-P256

  • Write alignment is 4 bytes

  • MCUBoot is configured for Encrypted XIP mode using modified MCUBOOT_OVERWRITE_ONLY image update strategy

  • MCUboot uses ECDH-P256 to secure AES key for image encryption

  • Primary slot is encrypted by IPED module to utilize encrypted XIP

Image signing example:

imgtool sign --key sign-ecdsa-p256-priv.pem
             --align 4
             --version 1.1
             --slot-size 0x200000
             --header-size 0x400
             --max-sectors 59
             --pad-header
             -E enc-ec256-pub.pem
             ota_mcuboot_basic.bin
             ota_mcuboot_basic.SIGNED.bin

Project building example:

The project is built using west tool. For more information please see MCUXpresso SDK documentation.

Bootloader:

west build -p always examples/ota_examples/mcuboot_opensource --toolchain iar -t guiproject --config flash_debug -b rdrw612bga -DCONF_FILE="examples/ota_examples/_custom_cfg/rw61x/mcuboot_opensource.conf" -d builds/rw612_mcuboot

OTA application:

west build -p always examples/ota_examples/ota_mcuboot_basic --toolchain iar -t guiproject --config flash_debug -b rdrw612bga -DCONF_FILE="examples/ota_examples/_custom_cfg/rw61x/ota_mcuboot_basic.conf" -d builds/rw612_ota_mcuboot_basic
FRDM-RW612
Hardware requirements

  • Mini/micro USB cable

  • Personal Computer

Board settings

Make sure the board is setup to boot from flash.

Default MCUBoot memory layout

In all cases, the MCUBOOT bootloader reserves 256kB at the beginning of the external flash followed by 2MB slots for application. The resulting layout for the monolithic application will be as follows:

Region

From

To

Size

MCUboot code

0x08000000

0x0803FFFF

256kB

Primary slot

0x08040000

0x0821FFFF

2048kB

Secondary slot

0x08240000

0x0841FFFF

2048kB

  • MCUBoot header size is set to 1024 bytes

  • Signing algorithm is ECDSA-P256

  • Write alignment is 4 bytes

  • MCUBoot is configured to use its DIRECT_XIP image handling strategy together with FlexSPI flash remapping

  • For testing purposes, the image authentication may be disabled in sblconfig.h by uncommenting the CONFIG_BOOT_OTA_TEST definition so that the following is defined:

    #define MCUBOOT_NO_SIGN #define CONFIG_BOOT_HASH_NO_SIGN #define CONFIG_BOOT_DIGEST_TYPE_SHA256

Image signing example
imgtool sign   --key sign-ecdsa-p256-priv.pem
               --align 4
               --version 1.1
               --slot-size 0x200000
               --header-size 0x400
               --pad-header
               ota_mcuboot_basic.bin
               ota_mcuboot_basic.SIGNED.bin

Note that for the first image flashed manually together with the bootloader additional imgtool options --pad and --confirm must be used. Otherwise the bootloader would reject the image for missing data in the trailer area.

Custom configuration - Encrypted XIP

Region

From

To

Size

MCUboot code

0x08000000

0x0803FFFF

256kB

Primary slot

0x08040000

0x0821FFFF

2048kB

Secondary slot

0x08240000

0x0841FFFF

2048kB

Encryption metadata

0x08440000

0x08440FFF

4kB

This custom build generates a project with predefined configuration to utilize Encrypted XIP mode. For more information please see Encrypted XIP and MCUboot.

  • MCUBoot header size is set to 1024 bytes

  • Signing algorithm is ECDSA-P256

  • Write alignment is 4 bytes

  • MCUBoot is configured for Encrypted XIP mode using modified MCUBOOT_OVERWRITE_ONLY image update strategy

  • MCUboot uses ECDH-P256 to secure AES key for image encryption

  • Primary slot is encrypted by IPED module to utilize encrypted XIP

Image signing example:

imgtool sign --key sign-ecdsa-p256-priv.pem
             --align 4
             --version 1.1
             --slot-size 0x200000
             --header-size 0x400
             --max-sectors 59
             --pad-header
             -E enc-ec256-pub.pem
             ota_mcuboot_basic.bin
             ota_mcuboot_basic.SIGNED.bin

Project building example:

The project is built using west tool. For more information please see MCUXpresso SDK documentation.

Bootloader:

west build -p always examples/ota_examples/mcuboot_opensource --toolchain iar -t guiproject --config flash_debug -b frdmrw612 -DCONF_FILE="examples/ota_examples/_custom_cfg/rw61x/mcuboot_opensource.conf" -d builds/rw612_mcuboot

OTA application:

west build -p always examples/ota_examples/ota_mcuboot_basic --toolchain iar -t guiproject --config flash_debug -b frdmrw612 -DCONF_FILE="examples/ota_examples/_custom_cfg/rw61x/ota_mcuboot_basic.conf" -d builds/rw612_ota_mcuboot_basic
FRDM-MCXN947
Hardware requirements

  • Micro USB cable

  • FRDM-MCXN947 board

  • Personal Computer

Board settings
Default MCUBoot memory layout - bootloader located in IFR region

Region

From

To

Size

Primary slot

0x00000000

0x000FFFFF

1024kB

Secondary slot

0x00100000

0x001FFFFF

1024kB

—————-

————

————

——–

MCUboot code

0x01008000

0x0100FFFF

32kB

  • MCUBoot resides in the Bank_1 IFR_0 region to utilize flash remap feature

  • MCUBoot header size is set to 1024 bytes

  • Signing algorithm is ECDSA-P256 (TinyCrypt)

  • Write alignment is 16 bytes

  • MCUBoot is configured to use its DIRECT_XIP image handling strategy

  • Flash swapping HW feature is used for zero-overhead image swapping

  • To manually enter serial recovery mode, keep the SW2 button pressed during reset, then release it

Image signing example:

imgtool sign --key sign-ecdsa-p256-priv.pem
             --align 16
             --version 1.1
             --slot-size 0x100000
             --header-size 0x400
             --pad-header
             ota_mcuboot_basic.bin
             ota_mcuboot_basic.SIGNED.bin

Note that for the first image flashed manually together with the bootloader additional imgtool options --pad and --confirm must be used. Otherwise the bootloader would reject the image for missing data in the trailer area.

If the toolchain used for build has problems with writing the bootloader to the IFR flash region, an alternative can be to use NXP blhost utility or MCUXpresso Secure Provisioning Tool.

IMPORTANT: The CMPA region must be configured so that ROM loader boots from the IFR region. This is done by setting the BOOT_CFG.BOOT_SRC field to 0b10. This value directs the ROM loader to start execution from the IFR region where MCUboot is located. Default CMPA setup with this particular field set is attached to this example in cmpa.bin binary file. To flash this configuration together with MCUboot binary the following blhost commands can be used. Note that the board must be in the ISP mode to use the following commands:

#Erase IFR0 Bank 1 region
blhost -u 0x1FC9,0x014F -- flash-erase-region 0x01008000 32768 0

#Flash MCUboot
blhost -u 0x1FC9,0x014F -- write-memory 0x01008000 mcuboot_opensource.bin

#Flash CMPA
blhost -u 0x1FC9,0x014F -- write-memory 0x01004000 cmpa.bin
Custom configuration - Encrypted XIP

Region

From

To

Size

MCUboot code

0x00000000

0x0003FFFF

256kB

Primary slot

0x00040000

0x0011FFFF

896kB

Secondary slot

0x00120000

0x001FFFFF

896kB

This custom build generates a project with predefined configuration to utilize Encrypted XIP mode. For more information please see Encrypted XIP and MCUboot.

Note: Default layout setup using the bootloader in IFR region limits usage of some features such as hardware accelerated mbedTLS (due size of IFR region) or encrypted XIP (due limitation of ROM). This custom configuration moves the bootloader to main flash array.

  • MCUBoot header size is set to 1024 bytes

  • Signing algorithm is ECDSA-P256

  • Write alignment is 16 bytes

  • MCUBoot is configured for Encrypted XIP mode using modified MCUBOOT_OVERWRITE_ONLY image update strategy

  • MCUboot uses ECDH-P256 to secure AES key for image encryption

  • Primary slot is encrypted by NPX module to utilize encrypted XIP

Image signing example:

imgtool sign --key sign-ecdsa-p256-priv.pem
             --align 16
             --version 1.1
             --slot-size 0xE0000
             --header-size 0x400
             --max-sectors 111
             --pad-header
             -E enc-ec256-pub.pem
             ota_mcuboot_basic.bin
             ota_mcuboot_basic.SIGNED.bin

Project building example:

The project is built using west tool. For more information please see MCUXpresso SDK documentation.

Bootloader:

west build -p always examples/ota_examples/mcuboot_opensource -b frdmmcxn947 --config debug --toolchain armgcc -Dcore_id=cm33_core0 -DCONF_FILE="examples/ota_examples/_custom_cfg/mcxn/mcuboot_opensource.conf"

OTA application:

west build -p always examples/ota_examples/ota_mcuboot_basic -b frdmmcxn947 --config debug --toolchain armgcc -Dcore_id=cm33_core0 -DCONF_FILE="examples/ota_examples/_custom_cfg/mcxn/ota_mcuboot_basic.conf"
FRDM-MCXN947T
Hardware requirements

  • Micro USB cable

  • FRDM-MCXN947T board

  • Personal Computer

Board settings
Default MCUBoot memory layout - bootloader located in IFR region

Region

From

To

Size

Primary slot

0x00000000

0x000FFFFF

1024kB

Secondary slot

0x00100000

0x001FFFFF

1024kB

—————-

————

————

——–

MCUboot code

0x01008000

0x0100FFFF

32kB

  • MCUBoot resides in the Bank_1 IFR_0 region to utilize flash remap feature

  • MCUBoot header size is set to 1024 bytes

  • Signing algorithm is ECDSA-P256 (TinyCrypt)

  • Write alignment is 16 bytes

  • MCUBoot is configured to use its DIRECT_XIP image handling strategy

  • Flash swapping HW feature is used for zero-overhead image swapping

  • To manually enter serial recovery mode, keep the SW2 button pressed during reset, then release it

Image signing example:

imgtool sign --key sign-ecdsa-p256-priv.pem
             --align 16
             --version 1.1
             --slot-size 0x100000
             --header-size 0x400
             --pad-header
             ota_mcuboot_basic.bin
             ota_mcuboot_basic.SIGNED.bin

Note that for the first image flashed manually together with the bootloader additional imgtool options --pad and --confirm must be used. Otherwise the bootloader would reject the image for missing data in the trailer area.

If the toolchain used for build has problems with writing the bootloader to the IFR flash region, an alternative can be to use NXP blhost utility or MCUXpresso Secure Provisioning Tool.

IMPORTANT: The CMPA region must be configured so that ROM loader boots from the IFR region. This is done by setting the BOOT_CFG.BOOT_SRC field to 0b10. This value directs the ROM loader to start execution from the IFR region where MCUboot is located. Default CMPA setup with this particular field set is attached to this example in cmpa.bin binary file. To flash this configuration together with MCUboot binary the following blhost commands can be used. Note that the board must be in the ISP mode to use the following commands:

#Erase IFR0 Bank 1 region
blhost -u 0x1FC9,0x014F -- flash-erase-region 0x01008000 32768 0

#Flash MCUboot
blhost -u 0x1FC9,0x014F -- write-memory 0x01008000 mcuboot_opensource.bin

#Flash CMPA
blhost -u 0x1FC9,0x014F -- write-memory 0x01004000 cmpa.bin
Custom configuration - Encrypted XIP

Region

From

To

Size

MCUboot code

0x00000000

0x0003FFFF

256kB

Primary slot

0x00040000

0x0011FFFF

896kB

Secondary slot

0x00120000

0x001FFFFF

896kB

This custom build generates a project with predefined configuration to utilize Encrypted XIP mode. For more information please see Encrypted XIP and MCUboot.

Note: Default layout setup using the bootloader in IFR region limits usage of some features such as hardware accelerated mbedTLS (due size of IFR region) or encrypted XIP (due limitation of ROM). This custom configuration moves the bootloader to main flash array.

  • MCUBoot header size is set to 1024 bytes

  • Signing algorithm is ECDSA-P256

  • Write alignment is 16 bytes

  • MCUBoot is configured for Encrypted XIP mode using modified MCUBOOT_OVERWRITE_ONLY image update strategy

  • MCUboot uses ECDH-P256 to secure AES key for image encryption

  • Primary slot is encrypted by NPX module to utilize encrypted XIP

Image signing example:

imgtool sign --key sign-ecdsa-p256-priv.pem
             --align 16
             --version 1.1
             --slot-size 0xE0000
             --header-size 0x400
             --max-sectors 111
             --pad-header
             -E enc-ec256-pub.pem
             ota_mcuboot_basic.bin
             ota_mcuboot_basic.SIGNED.bin

Project building example:

The project is built using west tool. For more information please see MCUXpresso SDK documentation.

Bootloader:

west build -p always examples/ota_examples/mcuboot_opensource -b frdmmcxn947t --config debug --toolchain armgcc -Dcore_id=cm33_core0 -DCONF_FILE="examples/ota_examples/_custom_cfg/mcxn/mcuboot_opensource.conf"

OTA application:

west build -p always examples/ota_examples/ota_mcuboot_basic -b frdmmcxn947t --config debug --toolchain armgcc -Dcore_id=cm33_core0 -DCONF_FILE="examples/ota_examples/_custom_cfg/mcxn/ota_mcuboot_basic.conf"
MCX-N5XX-EVK
Hardware requirements

  • Micro USB cable

  • MCX-N5XX-EVK board

  • Personal Computer

Board settings
Default layout setup - bootloader located in IFR region

Region

From

To

Size

Primary slot

0x00000000

0x000FFFFF

1024kB

Secondary slot

0x00100000

0x001FFFFF

1024kB

—————-

————

————

——–

MCUboot code

0x01008000

0x0100FFFF

32kB

  • MCUBoot resides in the Bank_1 IFR_0 region to utilize flash remap feature

  • MCUBoot header size is set to 1024 bytes

  • Signing algorithm is ECDSA-P256 (TinyCrypt)

  • Write alignment is 16 bytes

  • MCUBoot is configured to use its DIRECT_XIP image handling strategy

  • Flash swapping HW feature is used for zero-overhead image swapping

  • To manually enter serial recovery mode, keep the SW2 button pressed during reset, then release it

Image signing example:

imgtool sign --key sign-ecdsa-p256-priv.pem
             --align 16
             --version 1.1
             --slot-size 0x100000
             --header-size 0x400
             --pad-header
             ota_mcuboot_basic.bin
             ota_mcuboot_basic.SIGNED.bin

Note that for the first image flashed manually together with the bootloader additional imgtool options --pad and --confirm must be used. Otherwise the bootloader would reject the image for missing data in the trailer area.

If the toolchain used for build has problems with writing the bootloader to the IFR flash region, an alternative can be to use NXP blhost utility or MCUXpresso Secure Provisioning Tool.

IMPORTANT: The CMPA region must be configured so that ROM loader boots from the IFR region. This is done by setting the BOOT_CFG.BOOT_SRC field to 0b10. This value directs the ROM loader to start execution from the IFR region where MCUboot is located. Default CMPA setup with this particular field set is attached to this example in cmpa.bin binary file. To flash this configuration together with MCUboot binary the following blhost commands can be used. Note that the board must be in the ISP mode to use the following commands:

#Erase IFR0 Bank 1 region
blhost -u 0x1FC9,0x014F -- flash-erase-region 0x01008000 32768 0

#Flash MCUboot
blhost -u 0x1FC9,0x014F -- write-memory 0x01008000 mcuboot_opensource.bin

#Flash CMPA
blhost -u 0x1FC9,0x014F -- write-memory 0x01004000 cmpa.bin
Custom configuration - Encrypted XIP

Region

From

To

Size

MCUboot code

0x00000000

0x0003FFFF

256kB

Primary slot

0x00040000

0x0011FFFF

896kB

Secondary slot

0x00120000

0x001FFFFF

896kB

This custom build generates a project with predefined configuration to utilize Encrypted XIP mode. For more information please see Encrypted XIP and MCUboot.

Note: Default layout setup using the bootloader in IFR region limits usage of some features such as hardware accelerated mbedTLS (due size of IFR region) or encrypted XIP (due limitation of ROM). This custom configuration moves the bootloader to main flash array.

  • MCUBoot header size is set to 1024 bytes

  • Signing algorithm is ECDSA-P256

  • Write alignment is 16 bytes

  • MCUBoot is configured for Encrypted XIP mode using modified MCUBOOT_OVERWRITE_ONLY image update strategy

  • MCUboot uses ECDH-P256 to secure AES key for image encryption

  • Primary slot is encrypted by NPX module to utilize encrypted XIP

Image signing example:

imgtool sign --key sign-ecdsa-p256-priv.pem
             --align 16
             --version 1.1
             --slot-size 0xE0000
             --header-size 0x400
             --max-sectors 111
             --pad-header
             -E enc-ec256-pub.pem
             ota_mcuboot_basic.bin
             ota_mcuboot_basic.SIGNED.bin

Project building example:

The project is built using west tool. For more information please see MCUXpresso SDK documentation.

Bootloader:

west build -p always examples/ota_examples/mcuboot_opensource -b mcxn5xxevk --config debug --toolchain armgcc -Dcore_id=cm33_core0 -DCONF_FILE="examples/ota_examples/_custom_cfg/mcxn/mcuboot_opensource.conf"

OTA application:

west build -p always examples/ota_examples/ota_mcuboot_basic -b mcxn5xxevk --config debug --toolchain armgcc -Dcore_id=cm33_core0 -DCONF_FILE="examples/ota_examples/_custom_cfg/mcxn/ota_mcuboot_basic.conf"
MCX-N9XX-EVK
Hardware requirements

  • Micro USB cable

  • MCX-N9XX-EVK board

  • Personal Computer

Board settings
Default MCUBoot memory layout - bootloader located in IFR region

Region

From

To

Size

Primary slot

0x00000000

0x000FFFFF

1024kB

Secondary slot

0x00100000

0x001FFFFF

1024kB

—————-

————

————

——–

MCUboot code

0x01008000

0x0100FFFF

32kB

  • MCUBoot resides in the Bank_1 IFR_0 region to utilize flash remap feature

  • MCUBoot header size is set to 1024 bytes

  • Signing algorithm is ECDSA-P256 (TinyCrypt)

  • Write alignment is 16 bytes

  • MCUBoot is configured to use its DIRECT_XIP image handling strategy

  • Flash swapping HW feature is used for zero-overhead image swapping

  • To manually enter serial recovery mode, keep the SW2 button pressed during reset, then release it

Image signing example:

imgtool sign --key sign-ecdsa-p256-priv.pem
             --align 16
             --version 1.1
             --slot-size 0x100000
             --header-size 0x400
             --pad-header
             ota_mcuboot_basic.bin
             ota_mcuboot_basic.SIGNED.bin

Note that for the first image flashed manually together with the bootloader additional imgtool options --pad and --confirm must be used. Otherwise the bootloader would reject the image for missing data in the trailer area.

If the toolchain used for build has problems with writing the bootloader to the IFR flash region, an alternative can be to use NXP blhost utility or MCUXpresso Secure Provisioning Tool.

IMPORTANT: The CMPA region must be configured so that ROM loader boots from the IFR region. This is done by setting the BOOT_CFG.BOOT_SRC field to 0b10. This value directs the ROM loader to start execution from the IFR region where MCUboot is located. Default CMPA setup with this particular field set is attached to this example in cmpa.bin binary file. To flash this configuration together with MCUboot binary the following blhost commands can be used. Note that the board must be in the ISP mode to use the following commands:

#Erase IFR0 Bank 1 region
blhost -u 0x1FC9,0x014F -- flash-erase-region 0x01008000 32768 0

#Flash MCUboot
blhost -u 0x1FC9,0x014F -- write-memory 0x01008000 mcuboot_opensource.bin

#Flash CMPA
blhost -u 0x1FC9,0x014F -- write-memory 0x01004000 cmpa.bin
Custom configuration - Encrypted XIP

Region

From

To

Size

MCUboot code

0x00000000

0x0003FFFF

256kB

Primary slot

0x00040000

0x0011FFFF

896kB

Secondary slot

0x00120000

0x001FFFFF

896kB

This custom build generates a project with predefined configuration to utilize Encrypted XIP mode. For more information please see Encrypted XIP and MCUboot.

Note: Default layout setup using the bootloader in IFR region limits usage of some features such as hardware accelerated mbedTLS (due size of IFR region) or encrypted XIP (due limitation of ROM). This custom configuration moves the bootloader to main flash array.

  • MCUBoot header size is set to 1024 bytes

  • Signing algorithm is ECDSA-P256

  • Write alignment is 16 bytes

  • MCUBoot is configured for Encrypted XIP mode using modified MCUBOOT_OVERWRITE_ONLY image update strategy

  • MCUboot uses ECDH-P256 to secure AES key for image encryption

  • Primary slot is encrypted by NPX module to utilize encrypted XIP

Image signing example:

imgtool sign --key sign-ecdsa-p256-priv.pem
             --align 16
             --version 1.1
             --slot-size 0xE0000
             --header-size 0x400
             --max-sectors 111
             --pad-header
             -E enc-ec256-pub.pem
             ota_mcuboot_basic.bin
             ota_mcuboot_basic.SIGNED.bin

Project building example:

The project is built using west tool. For more information please see MCUXpresso SDK documentation.

Bootloader:

west build -p always examples/ota_examples/mcuboot_opensource -b mcxn9xxevk --config debug --toolchain armgcc -Dcore_id=cm33_core0 -DCONF_FILE="examples/ota_examples/_custom_cfg/mcxn/mcuboot_opensource.conf"

OTA application:

west build -p always examples/ota_examples/ota_mcuboot_basic -b mcxn9xxevk --config debug --toolchain armgcc -Dcore_id=cm33_core0 -DCONF_FILE="examples/ota_examples/_custom_cfg/mcxn/ota_mcuboot_basic.conf"
FRDM-MCXA153
Hardware requirements

  • FRDM-MCXA153 board

  • USB-C cable

  • Personal Computer

Board settings
MCUBoot layout

Region

From

To

Size

MCUboot code

0x00000000

0x00007FFF

32kB

Primary slot

0x00008000

0x0001FFFF

96kB

  • MCUBoot header size is set to 512 bytes

  • Signing algorithm is ECDSA-P256

  • Write alignment is 16 bytes

  • Used SINGLE_IMAGE image strategy due to limited flash size

Image signing example
imgtool sign   --key sign-ecdsa-p256-priv.pem
               --align 16
               --version 1.1
               --slot-size 0x18000
               --header-size 0x200
               --pad-header
               ota_mcuboot_basic.bin
               ota_mcuboot_basic.SIGNED.bin

If you experience problems with flash erase, check correct configuration of ACL_SEC_x fields in CMPA region.

FRDM-MCXA156
Hardware requirements

  • FRDM-MCXA156 board

  • USB-C cable

  • Personal Computer

Board settings
MCUBoot layout

Region

From

To

Size

MCUboot code

0x00000000

0x0000FFFF

64kB

Primary slot

0x00010000

0x0007FFFF

448kB

Secondary slot

0x00080000

0x000EFFFF

448kB

  • MCUBoot header size is set to 512 bytes

  • Signing algorithm is ECDSA-P256

  • Write alignment is 16 bytes

  • Uses image swapping by SWAP_USING_MOVE

Image signing example
imgtool sign   --key sign-ecdsa-p256-priv.pem
               --align 16
               --version 1.1
               --slot-size 0x70000
               --header-size 0x200
               --pad-header
               --max-sectors 64
               ota_mcuboot_basic.bin
               ota_mcuboot_basic.SIGNED.bin

If you experience problems with flash erase, check correct configuration of ACL_SEC_x fields in CMPA region.

FRDM-MCXA346
Hardware requirements

  • FRDM-MCXA346 board

  • USB-C cable

  • Personal Computer

Board settings
MCUBoot layout

Region

From

To

Size

MCUboot code

0x00000000

0x0000FFFF

64kB

Primary slot

0x00010000

0x0007FFFF

448kB

Secondary slot

0x00080000

0x000EFFFF

448kB

  • MCUBoot header size is set to 512 bytes

  • Signing algorithm is ECDSA-P256

  • Write alignment is 16 bytes

  • Uses image swapping by SWAP_USING_MOVE

Image signing example
imgtool sign   --key sign-ecdsa-p256-priv.pem
               --align 16
               --version 1.1
               --slot-size 0x70000
               --header-size 0x200
               --pad-header
               --max-sectors 64
               ota_mcuboot_basic.bin
               ota_mcuboot_basic.SIGNED.bin

If you experience problems with flash erase, check correct configuration of ACL_SEC_x fields in CMPA region.

FRDM-MCXA266
Hardware requirements

  • FRDM-MCXA266 board

  • USB-C cable

  • Personal Computer

Board settings
MCUBoot layout

Region

From

To

Size

MCUboot code

0x00000000

0x0000BFFF

48kB

Primary slot

0x0000C000

0x0007DFFF

456kB

Secondary slot

0x0007E000

0x000EFFFF

456kB

  • MCUBoot header size is set to 512 bytes

  • Signing algorithm is ECDSA-P256

  • Write alignment is 16 bytes

  • Uses image swapping by SWAP_USING_MOVE

Image signing example
imgtool sign   --key sign-ecdsa-p256-priv.pem
               --align 16
               --version 1.1
               --slot-size 0x70000
               --header-size 0x200
               --pad-header
               --max-sectors 64
               ota_mcuboot_basic.bin
               ota_mcuboot_basic.SIGNED.bin

If you experience problems with flash erase, check correct configuration of ACL_SEC_x fields in CMPA region.

FRDM-MCXA366
Hardware requirements

  • FRDM-MCXA366 board

  • USB-C cable

  • Personal Computer

Board settings
MCUBoot layout

Region

From

To

Size

MCUboot code

0x00000000

0x0000BFFF

48kB

Primary slot

0x0000C000

0x0007DFFF

456kB

Secondary slot

0x0007E000

0x000EFFFF

456kB

  • MCUBoot header size is set to 512 bytes

  • Signing algorithm is ECDSA-P256

  • Write alignment is 16 bytes

  • Uses image swapping by SWAP_USING_MOVE

  • To manually enter serial recovery mode, keep the SW2 button pressed during reset, then release it

Image signing example
imgtool sign   --key sign-ecdsa-p256-priv.pem
               --align 16
               --version 1.1
               --slot-size 0x70000
               --header-size 0x200
               --pad-header
               --max-sectors 64
               ota_mcuboot_basic.bin
               ota_mcuboot_basic.SIGNED.bin

If you experience problems with flash erase, check correct configuration of ACL_SEC_x fields in CMPA region.

KW47-EVK
Hardware requirements

  • KW47-EVK Board

  • USB-C cable

  • Personal Computer

Board settings
MCUBoot layout

Region

From

To

Size

MCUboot code

0x00000000

0x0003FFFF

256kB

Primary slot

0x00040000

0x0011FFFF

896kB

Secondary slot

0x00120000

0x001FFFFF

896kB

  • MCUBoot header size is set to 512 bytes

  • Signing algorithm is ECDSA-P256

  • Write alignment is 16 bytes

  • Uses image swapping by SWAP_USING_MOVE

  • To manually enter serial recovery mode, keep the SW2 button pressed during reset, then release it

Image signing example
imgtool sign --key sign-ecdsa-p256-priv.pem
             --align 16
             --version 1.1
             --slot-size 0xE0000
             --header-size 0x400
             --max-sectors 111
             --pad-header
             -E enc-ec256-pub.pem
             ota_mcuboot_basic.bin
             ota_mcuboot_basic.SIGNED.bin
MCX-W72-EVK
Hardware requirements

  • MCX-W72-EVK Board

  • USB-C cable

  • Personal Computer

Board settings
MCUBoot layout

Region

From

To

Size

MCUboot code

0x00000000

0x0003FFFF

256kB

Primary slot

0x00040000

0x0011FFFF

896kB

Secondary slot

0x00120000

0x001FFFFF

896kB

  • MCUBoot header size is set to 512 bytes

  • Signing algorithm is ECDSA-P256

  • Write alignment is 16 bytes

  • Uses image swapping by SWAP_USING_MOVE

  • To manually enter serial recovery mode, keep the SW2 button pressed during reset, then release it

Image signing example
imgtool sign --key sign-ecdsa-p256-priv.pem
             --align 16
             --version 1.1
             --slot-size 0xE0000
             --header-size 0x400
             --max-sectors 111
             --pad-header
             -E enc-ec256-pub.pem
             ota_mcuboot_basic.bin
             ota_mcuboot_basic.SIGNED.bin
FRDM-MCXE31B
Hardware requirements

  • FRDM-MCXE31B board

  • USB-C cable

  • Personal Computer

Board settings
MCUBoot layout

Region

From

To

Size

MCUboot code

0x00401400

0x004C0000

763kB

Primary slot

0x00500000

0x005C0000

768kB

Secondary slot

0x00600000

0x006C0000

768kB

  • MCUBoot header size is set to 1024 bytes

  • Signing algorithm is ECDSA-P256

  • Write alignment is 8 bytes

  • Uses image swapping by SWAP_USING_MOVE

  • The swapping algorithm requires one extra sector in primary slot plus one sector for the image trailer therefore the effective application image size is reduced by two sectors (768kB - 16kB)

Image signing example
imgtool sign   --key sign-ecdsa-p256-priv.pem
               --align 8
               --version 1.1
               --slot-size 0xC0000
               --header-size 0x400
               --pad-header
               --max-sectors 100
               ota_mcuboot_basic.bin
               ota_mcuboot_basic.SIGNED.bin
How to enable PSA support with HW crypto acceleration

It is possible to use PSA instead of purely SW based TinyCrypt implementation. However, current PSA port (25.12 release) is not compatible with enabled D-cache so the performance is degraded by this. To switch to PSA use the alternative files in psa_alt_files directory located in the following repository path:

<repo-root-dir>\examples\_boards\frdmmcxe31b\ota_examples\mcuboot_opensource

Also make sure you have the HSE firmware installed on the chip. This is described in the readme of ele_hseb_demo example.

FRDM-IMXRT1186
Hardware requirements

  • Type-C USB cable

  • FRDM-IMXRT1186 board

  • Personal Computer

Board settings

No special setup required.

MCUBoot layout

Region

From

To

Size

MCUboot code

0x04000000

0x0403FFFF

256kB

Primary slot

0x04040000

0x0423FFFF

2048kB

Secondary slot

0x04240000

0x0443FFFF

2048kB

  • MCUBoot header size is set to 1024 bytes

  • Signing algorithm is ECDSA-P256

  • Write alignment is 4 bytes

  • MCUBoot is configured to use SWAP_MOVE image handling strategy

Image signing example
imgtool sign   --key sign-ecdsa-p256-priv.pem
               --align 4
               --version 1.1
               --slot-size 0x200000
               --header-size 0x400
               --pad-header
               ota_mcuboot_basic.bin
               ota_mcuboot_basic.SIGNED.bin
FRDM-MCXE247
Hardware requirements

  • FRDM-MCXE247 board

  • USB-C cable

  • Personal Computer

Board settings
MCUBoot layout

Region

From

To

Size

MCUboot code

0x00000000

0x00010000

64kB

Primary slot

0x00010000

0x000C8000

736kB

Secondary slot

0x000C8000

0x00018000

736kB

  • MCUBoot header size is set to 1024 bytes

  • Signing algorithm is ECDSA-P256

  • Write alignment is 8 bytes

  • Uses image swapping by SWAP_USING_MOVE

Image signing example
imgtool sign   --key sign-ecdsa-p256-priv.pem
               --align 8
               --version 1.1
               --slot-size 0xb8000
               --header-size 0x400
               --pad-header
               --max-sectors 200
               ota_mcuboot_basic.bin
               ota_mcuboot_basic.SIGNED.bin
FRDM-MCXC162
Hardware requirements

  • FRDM-MCXC162 Board

  • USB-C cable

  • Personal Computer

Board settings
MCUBoot layout

Region

From

To

Size

MCUboot code

0x00000000

0x00007FFF

32kB

Primary slot

0x00008000

0x0000FFFF

32kB

  • MCUBoot header size is set to 512 bytes

  • Signing algorithm is ECDSA-P256

  • Write alignment is 16 bytes

  • Uses SINGLE_APPLICATION_SLOT image strategy due to limited flash size

  • To manually enter serial recovery mode, keep the SW2 button pressed during reset, then release it

Image signing example
imgtool sign --key sign-ecdsa-p256-priv.pem
             --align 16
             --version 1.1
             --slot-size 0x8000
             --header-size 0x200
             --max-sectors 4
             --pad-header
             ota_mcuboot_basic.bin
             ota_mcuboot_basic.SIGNED.bin
FRDM-MCXN236
Hardware requirements

  • Micro USB cable

  • FRDM-MCXN236 board

  • Personal Computer

Board settings
Default MCUBoot memory layout - bootloader located in IFR region

Region

From

To

Size

Primary slot

0x00000000

0x0007FFFF

512kB

Secondary slot

0x00080000

0x000FFFFF

512kB

—————-

————

————

——-

MCUboot code

0x01008000

0x0100FFFF

32kB

  • MCUBoot resides in the Bank_1 IFR_0 region to utilize flash remap feature

  • MCUBoot header size is set to 1024 bytes

  • Signing algorithm is ECDSA-P256 (TinyCrypt)

  • Write alignment is 16 bytes

  • MCUBoot is configured to use its DIRECT_XIP image handling strategy

  • Flash swapping HW feature is used for zero-overhead image swapping

  • To manually enter serial recovery mode, keep the SW2 button pressed during reset, then release it

Image signing example:

imgtool sign --key sign-ecdsa-p256-priv.pem
             --align 16
             --version 1.1
             --slot-size 0x80000
             --header-size 0x400
             --pad-header
             ota_mcuboot_basic.bin
             ota_mcuboot_basic.SIGNED.bin

Note that for the first image flashed manually together with the bootloader additional imgtool options --pad and --confirm must be used. Otherwise the bootloader would reject the image for missing data in the trailer area.

If the toolchain used for build has problems with writing the bootloader to the IFR flash region, an alternative can be to use NXP blhost utility or MCUXpresso Secure Provisioning Tool.

IMPORTANT: The CMPA region must be configured so that ROM loader boots from the IFR region. This is done by setting the BOOT_CFG.BOOT_SRC field to 0b10. This value directs the ROM loader to start execution from the IFR region where MCUboot is located. Default CMPA setup with this particular field set is attached to this example in cmpa.bin binary file. To flash this configuration together with MCUboot binary the following blhost commands can be used. Note that the board must be in the ISP mode to use the following commands:

#Erase IFR0 Bank 1 region
blhost -u 0x1FC9,0x0158 -- flash-erase-region 0x01008000 32768 0

#Flash MCUboot
blhost -u 0x1FC9,0x0158 -- write-memory 0x01008000 mcuboot_opensource.bin

#Flash CMPA
blhost -u 0x1FC9,0x0158 -- write-memory 0x01004000 cmpa.bin

To flash signed application using blhost you can use the following:

#Erase first application slot
blhost -u 0x1fc9,0x0158 -- flash-erase-region 0 0x80000 0

#Flash signed application (must be signed with --pad --confirm flags)
blhost -u 0x1FC9,0x0158 -- write-memory 0 ota_mcuboot_basic.N236.SIGNED.PADDED.bin
Alternative MCUBoot memory layout - bootloader located in the main memory

It is also possible to have the bootloader occupy the main memory. This allows for larger memory footprint compared to IFR region (32kB). However the flash remapping (swapping) feature becomes difficult to use in this configuration. For more details about this mode see MCUboot example for MCXN947 board where both the default IFR scheme and this alternative one are implemented.

FRDM-MCXL255
Hardware requirements

  • FRDM-MCXL255 board

  • USB-C cable

  • Personal Computer

Board settings
MCUBoot layout

Region

From

To

Size

MCUboot code

0x00000000

0x0000FFFF

64kB

Primary slot

0x00010000

0x00037FFF

160kB

Secondary slot

0x00038000

0x0005FFFF

160kB

  • MCUBoot header size is set to 512 bytes

  • Signing algorithm is ECDSA-P256

  • Write alignment is 16 bytes

  • Uses image swapping by SWAP_USING_MOVE

If you experience problems with flash erase, check correct configuration of ACL_SEC_x fields in CMPA region. Also see notes on flash access control in main.c source file.

Image signing example
imgtool sign   --key sign-ecdsa-p256-priv.pem
               --align 16
               --version 1.1
               --slot-size 0x28000
               --header-size 0x200
               --pad-header
               --max-sectors 32
               ota_mcuboot_basic.bin
               ota_mcuboot_basic.SIGNED.bin
Contents