.. _partition_layout: 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 .. list-table:: Partition resizing flags :widths: 25 25 :header-rows: 1 * - 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 :ref:`flash_split_xip`. 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 + 4K`` * **No 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: 1. **Partition size adjustment**: Ensure secondary slot is 4K larger than primary 2. **Remove scratch partition**: The scratch partition is no longer needed 3. **Update configuration**: Change from ``SWAP_SCRATCH`` to ``SWAP_USING_OFFSET`` 4. **Flash 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=0`` to remove the unused scratch partition * **Swap-with-offset disabled**: Set ``ATM_MCUBOOT_SWAP_WITH_OFFSET=0`` to 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: Storage and Factory Data ************************ **Subpages:** .. toctree:: ../../openair/subsys/settings/README.rst