Partition Layout
Overview
Zephyr provides a flexible scheme to define non-volatile memory partitions for application and subsystem use. The partitions define image and data storage. Partitions defined in a board’s final device tree use Atmosic-provided DTSI files, overlays and headers. Some partitions are configurable through DTS flags passed during the application build process. When dealing with multiple images to run on a given board, all images must have the same partition layout view. The DTS flags must be passed to each build to ensure that the layout is consistent for all images.
The following DTS flags can resize pre-defined partitions
DTS Flag |
Description |
|---|---|
ATM_SPE_SIZE |
Set Secure Application partition size |
ATM_FACTORY_SIZE |
Set Factory Data partition size |
ATM_STORAGE_SIZE |
Set Settings database partition size |
FLASH_SIZE |
Total flash size (stacked or external) |
ATM_MCUBOOT_SIZE |
MCUboot partition size |
ATM_MCUBOOT_SCRATCH_SIZE |
MCUboot scratch partition size |
ATM_FAST_CODE_SIZE |
Fast code partition size (flash XIP with split images mode only) |
Example of passing DTS flags to west command
west build ... -DDTS_EXTRA_CPPFLAGS="-DFLASH_SIZE=0x100000;-DATM_MCUBOOT_SCRATCH_SIZE=0" ...
For XIP (Execute In Place) configurations, the ATM_APP_FLASH_XIP flag enables flash XIP with split images mode
west build ... -DDTS_EXTRA_CPPFLAGS="-DATM_APP_FLASH_XIP;-DFLASH_SIZE=0x300000" ...
During the application build process a non-volatile storage layout summary is auto generated in the build folder. This file layout_info file graphically shows memory partitioning in RRAM and Flash regions and is generated based on the partition_info.map file.
Standard Layout Example
Following layout example is generated during application build using ATM34/e SOC + MCUboot + staging partition and MCUboot scratch partition in external flash
TOTAL_RRAM EXT_FLASH
*────────────────────* 0x90000 *────────────────────* 0x276000
│░░░░░░░░░░░░░░░░░░░░│ │░░░░░░░░░░░░░░░░░░░░│
│░░░░SEC SIDELOAD░░░░│(0x00100 0K) │░░░EXT FLASH OTA░░░░│(0x72000 456K)
│░░░░░░░░KEYS░░░░░░░░│ │░░░░░░STAGING░░░░░░░│
│░░░░░░░░░░░░░░░░░░░░│ │░░░░░░░░░░░░░░░░░░░░│
├────────────────────┤ 0x8ff00 ├────────────────────┤ 0x204000
│░░░░░░░░░░░░░░░░░░░░│ │░░░░░░░░░░░░░░░░░░░░│
│░░░░░SEC CNTRS░░░░░░│(0x00010 0K) │░░░░░EXT FLASH░░░░░░│(0x04000 16K)
│░░░░░░░░░░░░░░░░░░░░│ │░░MCUBOOT SCRATCH░░░│
├────────────────────┤ 0x8fef0 │░░░░░░░░░░░░░░░░░░░░│
│░░░░░░░░░░░░░░░░░░░░│ *────────────────────* 0x200000
│░░░░░░SEC JRNL░░░░░░│(0x006f0 1K)
│░░░░░░░░░░░░░░░░░░░░│
├────────────────────┤ 0x8f800
│░░░░░░░░░░░░░░░░░░░░│
│░░░░STORAGE DATA░░░░│(0x00800 2K)
│░░░░░░░░░░░░░░░░░░░░│
├--------------------┤ 0x8e800
│░░░░░░░░░░░░░░░░░░░░│
│░░░░FACTORY DATA░░░░│(0x00800 2K)
│░░░░░░░░░░░░░░░░░░░░│
├--------------------┤ 0x8e000
│░░░░░░░░░░░░░░░░░░░░│
│░░░SLOT0 TRAILER░░░░│(0x01000 4K)
│░░░░░░░░░░░░░░░░░░░░│
├--------------------┤ 0x8d000
│░░░░░░░░░░░░░░░░░░░░│
│░░░░░░░NS APP░░░░░░░│(0x6b000 428K)
│░░░░░░░░░░░░░░░░░░░░│
├--------------------┤ 0x22000
│░░░░░░░░░░░░░░░░░░░░│
│░░░░░░░░SPE░░░░░░░░░│(0x06000 24K)
│░░░░░░░░░░░░░░░░░░░░│
├--------------------┤ 0x1c000
│░░░░░░░░░░░░░░░░░░░░│
│░░░░░░MCUBOOT░░░░░░░│(0x0c000 48K)
│░░░░░░░░░░░░░░░░░░░░│
*────────────────────* 0x10000
Flash XIP with Split Images Layout Examples
When using flash XIP with split images mode (ATM_APP_FLASH_XIP), the partition layout changes to support
a split image configuration where security, power, and performance critical code continues to execute
in on-chip RRAM and the remaining user application logic executes from external flash memory.
Flash XIP with Split Images and MCUboot Configuration
The following example shows ATM34/e SOC with MCUboot + flash XIP with split images configuration
TOTAL_RRAM EXT_FLASH
*____________________* 0x90000 *____________________* 0x300000
| | | |
| SEC SIDELOAD |(0x00100 0K) | EXT FLASH NSPE |(0x45000 276K)
| KEYS | | STAGING |
| | | |
|____________________| 0x8ff00 |____________________| 0x2bb000
| | | |
| SEC CNTRS |(0x00010 0K) | EXT FLASH OTA |(0x72000 456K)
| | | STAGING |
|____________________| 0x8fef0 | |
| | |____________________| 0x249000
| SEC JRNL |(0x006f0 1K) | |
| | | EXT FLASH |(0x04000 16K)
|____________________| 0x8f800 | MCUBOOT SCRATCH |
| | | |
| STORAGE DATA |(0x00800 2K) |____________________| 0x245000
| | | |
|--------------------| 0x8e800 | NS APP |(0x45000 276K)
| | | |
| FACTORY DATA |(0x00800 2K) *____________________* 0x200000
| |
|--------------------| 0x8e000
| |
| SLOT0 TRAILER |(0x01000 4K)
| |
|--------------------| 0x8d000
| |
| FAST CODE |(0x6b000 428K)
| |
|--------------------| 0x22000
| |
| SPE |(0x06000 24K)
| |
|--------------------| 0x1c000
| |
| MCUBOOT |(0x0c000 48K)
| |
*____________________* 0x10000
Flash XIP with Split Images without MCUboot Configuration
The following example shows ATM34/e SOC with flash XIP with split images but no MCUboot configuration. In this mode, the application runs directly without bootloader support
TOTAL_RRAM EXT_FLASH
*____________________* 0x90000 *____________________* 0x300000
| | | |
| SEC SIDELOAD |(0x00100 0K) | NS APP |(0x100000 1024K)
| KEYS | | |
| | *____________________* 0x200000
|____________________| 0x8ff00
| |
| SEC CNTRS |(0x00010 0K)
| |
|____________________| 0x8fef0
| |
| SEC JRNL |(0x006f0 1K)
| |
|____________________| 0x8f800
| |
| STORAGE DATA |(0x00800 2K)
| |
|--------------------| 0x8f000
| |
| FACTORY DATA |(0x00800 2K)
| |
|--------------------| 0x8e800
| |
| FAST CODE |(0x78800 482K)
| |
|--------------------| 0x16000
| |
| SPE |(0x06000 24K)
| |
*____________________* 0x10000
In flash XIP with split images mode, the application is split between RRAM and external flash:
RRAM: Contains SPE, fast code (performance-critical code), and data partitions
External Flash: Contains the user application code
Fast Code: Includes Zephyr kernel, subsystems, C-runtime, HAL drivers and BLE link controller stacks
MCUboot Support: When enabled, provides multi-image upgrade with staging partitions and scratch partition in external flash
For detailed information on flash XIP with split images configuration, multi-image support, building, and version dependencies, refer to Flash XIP with Split Images.
MCUboot Swap Mechanisms
Starting with Zephyr 4.3, MCUboot supports multiple swap mechanisms for firmware updates. Atmosic platforms now default to the more efficient swap-with-offset mechanism.
Swap-with-Offset (Default)
The swap-with-offset mechanism is the default and recommended approach for MCUboot firmware updates on Atmosic platforms:
Key Features:
No scratch partition required: Eliminates the need for a dedicated scratch partition, saving flash space
Reduced flash wear: Significantly reduces the number of flash erase/write cycles during updates
Faster updates: More efficient swap algorithm reduces update time
Secondary slot sizing: Secondary slot must be one sector (4K) larger than the primary slot
Configuration:
To use swap-with-offset (default behavior), configure your sysbuild with:
SB_CONFIG_MCUBOOT_MODE_SWAP_USING_OFFSET=y
Partition Layout:
In swap-with-offset mode, the partition layout automatically adjusts:
Primary slot (slot0): Contains the currently running firmware
Secondary slot (slot1): Contains the update firmware, sized as
primary_size + 4KNo scratch partition: The extra 4K in the secondary slot serves as working space
Legacy Swap-with-Scratch
The legacy swap-with-scratch mechanism is still supported for backward compatibility:
Configuration:
To use the legacy swap-with-scratch mechanism:
SB_CONFIG_MCUBOOT_MODE_SWAP_SCRATCH=y
Partition Layout:
In swap-with-scratch mode:
Primary slot (slot0): Contains the currently running firmware
Secondary slot (slot1): Contains the update firmware, same size as primary
Scratch partition: Dedicated scratch space for swap operations
Migration from Legacy to Swap-with-Offset:
When migrating from swap-with-scratch to swap-with-offset:
Partition size adjustment: Ensure secondary slot is 4K larger than primary
Remove scratch partition: The scratch partition is no longer needed
Update configuration: Change from
SWAP_SCRATCHtoSWAP_USING_OFFSETFlash layout: Reclaim space previously used by scratch partition
Overwrite Only Mode
The overwrite-only mode provides the simplest upgrade mechanism, directly overwriting the primary slot with the secondary slot contents:
Key Features:
Simplest code path: Uses a straightforward overwrite mechanism without swap complexity
No revert capability: Once an update is applied, the previous firmware is permanently replaced
No scratch partition required: Eliminates the need for a dedicated scratch partition
Smaller MCUboot footprint: Reduced code size compared to swap modes
Primary slot only storage: The secondary slot contents are copied to primary and then erased
RRAM-only configurations: Recommended for configurations without external flash (DFU_IN_FLASH not defined)
Configuration:
To enable overwrite-only mode, configure your sysbuild with:
SB_CONFIG_MCUBOOT_MODE_OVERWRITE_ONLY=y
Example configuration:
extra_args:
- SB_CONFIG_BOOTLOADER_MCUBOOT=y
- SB_CONFIG_BOOT_SIGNATURE_TYPE_ECDSA_P256=y
- SB_CONFIG_MCUBOOT_MODE_OVERWRITE_ONLY=y
- SB_ATM_DTS_EXTRA_CPPFLAGS="-DATM_MCUBOOT_SWAP_WITH_OFFSET=0;-DATM_MCUBOOT_SCRATCH_SIZE=0"
Partition Layout:
In overwrite-only mode:
Primary slot (slot0): Contains the currently running firmware
Secondary slot (slot1): Contains the update firmware (same size as primary)
No scratch partition: Set
ATM_MCUBOOT_SCRATCH_SIZE=0to remove the unused scratch partitionSwap-with-offset disabled: Set
ATM_MCUBOOT_SWAP_WITH_OFFSET=0to disable the default swap-with-offset behavior
Use Cases:
Space-constrained devices: When flash space is limited and revert is not required
RRAM-only configurations: When external flash is not available for DFU
Simple deployment: When rollback capability is not needed
Flash XIP with overwrite: Can be combined with flash XIP mode for split-image configurations
Flash XIP with Overwrite Example:
For flash XIP with split images using overwrite mode:
extra_args:
- SB_CONFIG_BOOTLOADER_MCUBOOT=y
- SB_CONFIG_BOOT_SIGNATURE_TYPE_ECDSA_P256=y
- SB_CONFIG_MCUBOOT_MODE_OVERWRITE_ONLY=y
- SB_ATM_DTS_EXTRA_CPPFLAGS="-DATM_APP_FLASH_XIP;-DATM_MCUBOOT_SCRATCH_SIZE=0"
- mcuboot_CONFIG_UPDATEABLE_IMAGE_NUMBER=2
- mcuboot_CONFIG_MCUBOOT_VERIFY_IMG_ADDRESS=n
Downgrade Prevention:
Overwrite-only mode supports downgrade prevention via MCUBOOT_BOOTLOADER_NO_DOWNGRADE. When enabled, the overwrite will not occur unless the version in the secondary slot is higher than the version in the primary slot.
Limitations:
No rollback: Cannot revert to a previous version if the new firmware has issues
Requires reliable updates: Firmware updates must be thoroughly tested before deployment
No A/B testing: Cannot switch between two firmware versions for validation
GLOSSARY
ATMWSTK: Atmosic Bluetooth Stack (only for certain platform)
EXT_FLASH: External/Stack flash memory
EXT FLASH NSPE STAGING: Staging area for NSPE image updates (flash XIP with split images + MCUboot mode)
EXT FLASH OTA STAGING: Staging area for OTA image updates (flash XIP with split images + MCUboot mode)
FACTORY DATA: Application specific data partition using NVS. This data partition is read-only and write protected
FAST CODE: Performance-critical code partition in RRAM (flash XIP with split images mode only). Contains Zephyr kernel, subsystems, C-runtime, HAL drivers and BLE link controller stacks
MCUBOOT: MCUboot bootloader
MCUBOOT SCRATCH: Legacy scratch partition storage used by MCUboot swap-with-scratch mode. Can be located in RRAM (ATM33 only) or in external Flash (all products). Not required for swap-with-offset mode (Zephyr 4.3+ default)
NS APP: Non Secure Application code space (TrustZone). In flash XIP with split images mode, this runs from external flash
OTA STAGING: Storage for downloaded image (merged/signed SPE and NS APP binary) Staging area can be located in RRAM (ATM33 only) or in external flash (all products)
SEC JRNL: Secure journal.
SEC CNTRS: Secure counters.
SEC SIDELOAD KEYS: Area to store unique device specific side loaded keys
SLOT0/1/2/3: MCUboot image slots for multi-image upgrade support (flash XIP with split images mode)
SPE: Secure Application code space (TrustZone). Always runs from RRAM for security
SLOT0 TRAILER: Image trailer reservation used by MCUBOOT. Trailer covers Secure as well as non Secure application code space
STORAGE DATA: Partition used to hold Zephyr settings read/write database
Storage and Factory Data
Subpages: