Partitioning device memory

Partitioning device memory is a crucial aspect of managing how a device’s storage is utilized, especially when dealing with firmware updates and bootloader configurations. By default, the Partition Manager in the system dynamically generates a partition map, which is suitable for most applications that do not use Device Firmware Updates (DFU). For scenarios involving DFU, read the following sections.

Static partition requirement for DFU

If you want to perform DFU, you must define a static partition map 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.

Note

For detailed information about the memory layout used for the build, see the partition configuration in the partitions.yml file, located in the build folder directory, or run ninja partition_manager_report. You must enable the Partition Manager to make the partitions.yml file and the partition_manager_report target available.

The partitions.yml file is present also if the Partition Manager generates the partition map dynamically. You can use this file as a base for your static partition map.

The memory partitions that must be defined in the static partition map depend on the selected bootloader chain. For details, see Flash memory partitions.

Flash memory partitions

Each bootloader handles flash memory partitioning differently.

After building the application, you can print a report of how the flash partitioning has been handled for a bootloader, or combination of bootloaders, by using Partition placement reports.

nRF Secure Immutable Bootloader partitions

See Flash memory layout for implementation-specific information about this bootloader.

MCUboot partitions

For most applications, MCUboot requires two image slots:

  • The primary slot, containing the application that will be booted.

  • The secondary slot, where a new application can be stored before it is activated.

It is possible to use only the primary slot for MCUboot by using the CONFIG_SINGLE_APPLICATION_SLOT option. This is particularly useful in memory-constrained devices to avoid providing space for two images.

See the Image Slots section in the MCUboot documentation for more information.

The nRF Connect SDK variant of MCUboot uses the Partition Manager to configure the flash memory partitions for these image slots. In the default configuration, defined in bootloader/mcuboot/boot/zephyr/pm.yml, the partition manager dynamically sets up the partitions as required for MCUboot. For example, the partition layout for zephyr/samples/hello_world using MCUboot on the nrf52840dk board would look like the following:

 (0x100000 - 1024.0kB):
+-----------------------------------------+
| 0x0: mcuboot (0xc000)                   |
+---0xc000: mcuboot_primary (0x7a000)-----+
| 0xc000: mcuboot_pad (0x200)             |
+---0xc200: mcuboot_primary_app (0x79e00)-+
| 0xc200: app (0x79e00)                   |
| 0x86000: mcuboot_secondary (0x7a000)    |
+-----------------------------------------+

You can also store secondary slot images in external flash memory when using MCUboot. See Using external flash memory partitions for more information.

Using external flash memory partitions

When using MCUboot, you can store the storage partition for the secondary slot in the external flash memory, using a driver for the external flash memory that supports the following features:

  • Single-byte read and write.

  • Writing data from the internal flash memory to the external flash memory.

To enable external flash with MCUboot, complete the following steps:

  1. Follow the instructions in External flash memory partitions, which enables external flash use in the nRF5340 DK’s DTS file.

  2. Enable the CONFIG_PM_EXTERNAL_FLASH_MCUBOOT_SECONDARY Kconfig option. (Depending on the build configuration, this option will be set to y automatically.)

  3. Update the CONFIG_BOOT_MAX_IMG_SECTORS MCUboot Kconfig option accordingly for child images. 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.

    (The image sector size is the same as the flash erase-block-size across all nRF Connect SDK integrated memory.)

Note

The Partition Manager will only support run-time access to flash partitions defined in regions placed on external flash devices that have drivers compiled in. The Partition Manager cannot determine which partitions will be used at runtime, but only those that have drivers enabled, and those are included into the partition map. Lack of partition access will cause MCUboot to fail at runtime. For more details on configuring and enabling access to external flash devices, see External flash memory partitions.

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 tests/modules/mcuboot/external_flash for reference. This test passes both devicetree overlay files and Kconfig fragments to the MCUboot child image through its child_image folder. See also Image-specific variables for more details on how to pass configuration files to a child image.

Troubleshooting

MCUboot could fail, reporting the following error:

*** Booting Zephyr OS build v3.1.99-ncs1-... ***
I: Starting bootloader
W: Failed reading sectors; BOOT_MAX_IMG_SECTORS=512 - too small?
W: Cannot upgrade: not a compatible amount of sectors
I: Bootloader chainload address offset: 0x10000
I: Jumping to the first image slot

This error could be caused by the following issues:

  • The external flash driver for the application image partitions used by MCUboot is not enabled or an incorrect Kconfig option has been given to the DEFAULT_DRIVER_KCONFIG of the partition manager external region definition. See External flash memory partitions for details.

  • An out-of-tree external flash driver is not selecting CONFIG_PM_EXTERNAL_FLASH_HAS_DRIVER, resulting in partitions for images located in the external flash memory being not accessible. See External flash memory partitions for details.

  • Insufficient value set for the CONFIG_BOOT_MAX_IMG_SECTORS Kconfig option, as MCUboot typically increases slot sizes when external flash is enabled. See MCUboot’s Kconfig options used in Zephyr for details.

The compilation could fail, reporting a linker error similar to following:

undefined reference to '__device_dts_ord_<digits>

This error could be caused by the following issues: