For most microcontroller products with room for two images, use MCUboot’s swap mode with revert, which on new designs means swap-using-offset. It costs a second slot the size of your image and a copy at boot, and it returns the device to the old image if the new one never confirms itself. Overwrite-only uses the same two slots but keeps no copy of the old image, so a bad release cannot fall back on its own. Direct-XIP, the true A/B layout, skips the copy at the price of building every release twice, once for each slot. A single slot saves flash only when something else can receive the update, and the device is out of service while it does.
What each update layout does
Every layout answers one question that the IETF’s firmware update architecture, RFC 9019, puts plainly. When a new image turns out to be invalid, “either the bootloader must be able to select different, valid firmware or it must be able to obtain new, valid firmware.” Two-slot layouts select. Single-slot layouts obtain.
The same document explains why microcontrollers make this awkward. Code usually runs in place from flash and is linked for one address, so “either the bootloader needs to copy the newly downloaded application firmware image into the location of the old application firmware image and vice versa or multiple versions of the firmware need to be prepared for different locations.” Copying is swap and overwrite. Preparing a version per location is direct-XIP.
Swap with revert
MCUboot divides an image area into a primary slot and a secondary slot, and normally runs an image only from the primary slot. The running firmware downloads a new image into the secondary slot; Zephyr’s documentation describes it being written “into an unoccupied code partition, usually named slot1_partition” (Zephyr OTA). At the next reset, MCUboot checks the image and exchanges the two slots sector by sector.
The swap is a test. The new image runs, and if it marks itself OK the swap becomes permanent. If it does not, MCUboot swaps the old image back at the next boot. In Zephyr, the update agent chooses between the two when it requests the upgrade, using the MCUboot API:
/* After the new image is fully written and checked */
boot_request_upgrade(BOOT_UPGRADE_TEST); /* revert unless confirmed */
/* boot_request_upgrade(BOOT_UPGRADE_PERMANENT); no way back */
Use the test request for field updates. A permanent request gives up the revert before the new image has run once.
MCUboot offers three swap algorithms:
- Swap using offset uses one spare sector in the secondary slot. MCUboot’s Zephyr configuration says “Most devices should be using swap using offset mode”, and that it “offers faster swap times with less flash endurance usage than swap using move”.
- Swap using move shifts the primary slot up one sector first. The design document now prefers offset “except when building for existing products already using the latter.”
- Swap using scratch passes sectors through a separate scratch area. The Kconfig calls it “the most conservative swap mode”, one that “can work even on devices with heterogeneous flash page layout”, while the design document warns it “may be removed in the coming future.”
Overwrite-only
The bootloader copies the new image over the old one and erases the request. MCUboot’s Kconfig describes the option bluntly: it will “overwrite the primary slot with the upgrade image instead of swapping them. This prevents the fallback recovery, but uses a much simpler code path.” Trusted Firmware-M (TF-M) uses MCUboot as its secure bootloader by default, and its secure boot documentation says “The default behaviour is the overwrite-based image upgrade.”
Direct-XIP: the true A/B layout
Both slots are equal. The bootloader runs an image from whichever slot holds the highest valid version, without moving it. Each image must therefore “be built to be executed from the corresponding slot”, and the update client must know which slot is active and send the matching build. An optional revert mechanism erases a new image that never confirmed itself and boots the other slot.
RAM-load
Also equal slots, but the newest image is copied into RAM and run there. MCUboot’s design document says this mode “can be useful when there is no internal flash in the SoC, but there is a big enough internal RAM to hold the images.”
Single slot, with a loader or serial recovery
MCUboot’s single-slot option means, in its Kconfig’s words, that “uploading a new application overwrites the one that previously occupied the area.” Its firmware loader option keeps one application slot and puts “a non-upgradeable firmware loaded image (e.g. for loading firmware via Bluetooth)” in the second area. RFC 9019 describes the same pattern as a recovery image that can “perform the firmware update process again using firmware updates over serial, USB, or even wireless connectivity like Bluetooth Smart.”
ESP-IDF’s two OTA slots
Espressif’s framework has its own bootloader and its own A/B scheme. ESP-IDF OTA needs “at least two OTA app slot partitions” and an OTA data partition. The running app writes the new image to the slot not selected for boot; once the image is verified, the OTA data partition is updated to boot it next. Nothing is copied at boot.
How much flash each layout costs
Swap, overwrite and direct-XIP all need a second slot at least as large as the largest image you will ever ship. Overwrite saves bootloader code and complexity, not slot space. Only a single-slot design, or a secondary slot moved to external flash, gives the application more than half of what remains after the bootloader and storage.
The overhead inside each slot
A slot never holds an image of exactly its own size. MCUboot keeps an image trailer at the end of each slot with the swap status and flags, and the swap algorithms need room to move sectors. The design document gives the rules:
| Method | Extra space it needs | Largest image |
|---|---|---|
| Swap using offset | One sector in the secondary slot; most efficient when the secondary slot is exactly one sector larger | Primary slot sectors minus the trailer, rounded up to whole sectors |
| Swap using move | One sector in the primary slot, plus the swap status area | One sector less than the primary slot, minus the trailer |
| Swap using scratch | A scratch area at least as large as the largest sector swapped | Slot size minus the trailer |
| Overwrite-only | None beyond the trailer | Slot size minus the trailer |
| Direct-XIP | None beyond the trailer, but each slot holds its own build | Slot size minus the trailer |
Offset and move also require that “All slot’s sectors should be of the same size.” A chip whose flash comes in a few large, uneven sectors pushes you toward scratch or overwrite, and toward a careful look at the reference manual before you pick the part. The microcontroller selection article covers that check.
Worked numbers for a 1 MB part
Example (fictional). Loamwick’s LW-1 probe has 1,024 KB of internal flash: a 48 KB MCUboot partition, two 448 KB image slots, 32 KB of settings and 48 KB of logs. The flash budget calculator, allowing 4 KB for the image header and trailer, puts the largest image at 444 KB. The 412 KB application fills 92.8% of its slot. Planning for 25% growth gives a 515 KB image, 71 KB too big.
Switching from swap to overwrite would not help: the secondary slot still has to hold a whole new image. Two changes would. A single application slot with a Bluetooth LE loader frees the second slot, but the loader takes space and the probe stops measuring while it updates. Moving the secondary slot to an external flash chip, as Loamwick plans for Rev E, lets the primary slot grow toward the 896 KB that is left after the bootloader and storage.
External flash and encryption
A secondary slot on an external chip works with the swap and overwrite modes, because the image is copied into internal flash before it runs. Direct-XIP runs images from either slot, so both slots must sit in flash the chip can execute from. RAM-load, by MCUboot’s own description, suits images kept on an external storage device.
External flash raises a second question: whether images should be encrypted while they sit off-chip. MCUboot’s encrypted image support is meant for images in transit or “written to external storage, eg a SPI flash being used for the secondary slot.” The image is decrypted on its way into the primary slot, and in swap mode the old image is re-encrypted on its way out. The design document adds that “Image encryption is not supported when the direct-xip upgrade strategy is selected.”
What happens when power fails at each step
An update has five moments when a power cut matters: during the download, while the upgrade is being requested, during the copy at boot, during the first run of the new image, and after it confirms. RFC 9019 sets the bar: “Devices must not fail when a disruption, such as a power failure or network interruption, occurs during the update process.” Here is how each layout meets it.
| Step | Swap with revert | Overwrite-only | Direct-XIP with revert | ESP-IDF, rollback enabled |
|---|---|---|---|---|
| Download into the inactive slot | Running image untouched; an incomplete image fails validation | Same | Same | Same |
| Request the upgrade | Small trailer write | Small trailer write | No separate request: the highest valid version is chosen | OTA data partition, kept in two sectors |
| Copy at boot | Interrupted swap resumes from its status | Fail-safe per TF-M; request cleared only after the copy | Nothing to copy | Nothing to copy |
| First run, before confirming | Reset swaps the old image back | Reset boots the new image again | Reset erases the new image, boots the old | Reset marks the new app aborted, boots the old |
| After confirming | New image is the good one | Same | Same | Same |
During the download
In every layout, the running image is untouched while the new one downloads, so a power cut costs a download, not a device. When the device asks for an upgrade from an image that is not valid, MCUboot’s procedure is to “Erase invalid image”, persist the failure in the image trailers and boot the primary slot. Direct-XIP does the same: if the newest image is invalid, “MCUboot erases its memory slot and starts to validate the other image.”
The update agent should still behave as if the bootloader were not there. Write the image, read it back, check its hash and signature, and only then request the upgrade; ESP-IDF follows the same order, updating the OTA data partition only “once the image is verified.” Keep a record of how far the download got so a cut costs only the missing part, and erase the inactive slot as part of starting a new download, not as part of finishing one. An agent that requests the upgrade before the image is complete leaves the bootloader to catch its mistake on every device in the fleet.
During the copy at boot
This is where swap earns its complexity. MCUboot’s first step at every boot is to inspect the swap status region and ask whether “an interrupted swap” is “being resumed”. If it is, the bootloader finishes the partial swap before doing anything else. Its reset recovery section explains that the two images “may be discontiguous in flash” after a reset mid-swap, and the image trailers record how to put them back together.
Overwrite has a simpler story. TF-M’s documentation says the header and trailer of the new image in the secondary slot are erased only after the primary slot “has been successfully overwritten”, and calls the operation “fail-safe and resistant to power-cut failures”. What it cannot do is go back.
ESP-IDF avoids the copy. Its documentation calls application updates a “Safe update mode”, designed so that “even if the power is cut off during the update, the chip will remain operational and capable of booting the current application.” The OTA data partition “is two flash sectors (0x2000 bytes) in size, to prevent problems if there is a power failure while it is being written.” The same page lists the bootloader, partition table and data partitions under an “Unsafe update mode.”
Batteries and brownouts
A swap that resumes after every reset can still trap a device whose battery cannot finish it. Writing flash costs energy; RFC 9019 notes that “radio communication and writing the firmware image to flash” make an update “an energy-intensive task for a device.” Have the update agent check the battery before it requests the upgrade and reboots, and refuse to start a swap it cannot finish.
The bootloader itself is the one image you should plan never to update in the field. RFC 9019 assumes “the bootloader itself, or a minimal part of it, will not be updated since a failed update of the bootloader poses a reliability risk.”
What happens when the new image is bad
Layouts differ most when the new image is valid but broken: correctly signed, yet crashing at start-up or failing to reach the network. Signature checks stop forged and corrupted images in every mode. Only a revert mechanism stops a genuine release that does not work.
Invalid images
An image that fails its integrity or signature check never runs. MCUboot checks an image “immediately before it gets copied into the primary slot”, and in direct-XIP it validates the newest image before booting it. ESP-IDF verifies a new image before it updates the OTA data partition. In each case the old image keeps running.
Valid images that fail
Here the layouts split:
- Swap with revert. The design document says that if the device “crashes immediately upon booting a new (bad) image, MCUboot will revert to the old (working) image at the next device reset”. The application confirms itself after a self-test; in Zephyr that call is
boot_write_img_confirmed(). - Overwrite-only. There is no old image. A release that crashes at start-up crashes at every start-up, and the only way out is another update the broken image cannot receive. You need a separate recovery path, such as MCUboot’s serial recovery or a loader image, and a working way to reach it in the field.
- Direct-XIP with revert. The Kconfig help says that when a reboot happens without the image being confirmed, “the bootloader considers the image faulty and erases it. After this it will attempt to boot the previous image.” Revert is a separate option,
MCUBOOT_DIRECT_XIP_REVERT; without it, direct-XIP keeps booting the newest valid image. - ESP-IDF. App rollback is also an option,
CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE, and the documentation says it is not enabled by default. With it, “a new application has only one attempt to boot successfully”: the app confirms withesp_ota_mark_app_valid_cancel_rollback(), and if it resets first, the bootloader marks it aborted and boots the previous app.
Two of these four protections are off unless you turn them on. Check the bootloader configuration in your release build, not in the sample you started from.
ESP-IDF’s one boot attempt
ESP-IDF’s rollback is strict, and that changes how you write the self-test. Its documentation warns that “If a power loss or an unexpected crash occurs at the time of the first boot of a new application, it will roll back the application”, and recommends performing “the self-test procedure as quickly as possible, to prevent rollback due to power loss.” A slow self-test on a battery device turns brownouts into reverts of good releases.
Two more details matter. “Only OTA partitions can be rolled back. Factory partition is not rolled back.” And anti-rollback is a separate option, CONFIG_BOOTLOADER_APP_ANTI_ROLLBACK, which compares a security version in the image with one in the chip’s eFuse. Used together with app rollback, “rollback is possible only on the security version which is equal or higher than the version in the chip.”
When the image should confirm itself
Revert only works if the image confirms itself at the right moment. Confirm straight after boot and a release that hangs ten minutes later stays installed. Confirm only after a long delay and an unrelated reset in that window throws away a good release. A sound default is to confirm after a self-test that reads the sensors, reaches the network and contacts the update service.
Going back after confirmation
After an image confirms, it is the good one, and going back means shipping another update. In direct-XIP the bootloader always prefers the highest version, so an older build placed in the inactive slot will not be chosen; the old code has to be rebuilt with a higher version number. Downgrade prevention adds a further rule. In MCUboot, version-based prevention “is only available when the overwrite-based image update strategy is used”, while the hardware security counter works with every mode. The trade-off is covered in rollback versus anti-rollback.
Downtime and flash wear
Swap modes take the device offline for a copy of the whole image at boot, and a revert repeats it. Overwrite copies once. Direct-XIP and ESP-IDF copy nothing, so a reboot is the whole outage. Wear follows the same order, with one exception: the swap-using-scratch area.
How long the copy takes
The design document notes that the bootloader “tries to copy only used sectors (based on largest image installed on any of the slots)”, so time scales with the image, not the slot. A useful estimate is the number of sectors the image occupies, multiplied by the time to erase and program one sector, multiplied by the passes the method makes. Take the erase and program times from your part’s datasheet, then measure.
For Loamwick’s fictional 412 KB image on 4 KB sectors, that is 103 sectors. An offset swap erases and rewrites each of them once in each slot, so about 206 sector erases and 206 sector writes, and a revert does it all again. Overwrite does roughly half that work, once, and direct-XIP none of it.
To measure, toggle a pin when the bootloader starts and again when the application reaches its main loop, and capture both with a logic analyzer across a real update. Do it for the update and for a forced revert. The site’s Bluetooth LE update time calculator uses 15 seconds for verify, swap and reboot as a default input; replace it with your measured figure.
Boot time also includes validation. If you set MCUBOOT_VALIDATE_PRIMARY_SLOT, MCUboot checks the primary image on every boot, not only after an upgrade, which adds a hash and signature check to each start.
How many erase cycles each update costs
MCUboot’s design document counts erases per swap:
| Method | Erase cycles per swap | Note |
|---|---|---|
| Swap using offset | One on each slot | Kconfig: less endurance usage than swap using move |
| Swap using move | Two on the primary slot, one on the secondary | Receiving the image adds one on the secondary, which levels wear between slots |
| Swap using scratch | The scratch area once per scratch-sized chunk of image | Wear concentrates on the scratch sectors |
| Overwrite-only | Primary slot once | Plus clearing the new image’s header and trailer |
| Direct-XIP | None at boot | Only the download erases the inactive slot |
A revert in a swap mode is a second swap with the same counts. Scratch is the case to calculate. The design document’s formula is the erase cycles divided by the ratio of image size to scratch size. Its worked example assumes 10,000 erase cycles, a 150 KB image and a 4 KB scratch area, which allows about 267 upgrades; a 16 KB scratch area raises that to about 1,067. Count development and bench updates as well as field releases.
For the slot sectors themselves, the swap-offset count is small. Each update erases the secondary slot once to receive the image and once during the swap, and the primary slot once. At MCUboot’s example figure of 10,000 cycles, that is thousands of updates before the slots reach their rated endurance, so for offset and move, wear rarely decides the layout.
What each layout costs in builds and releases
The bootloader layout reaches into the release pipeline. Swap and overwrite need one image per release, linked for the primary slot. Direct-XIP needs two, and that doubles everything that depends on the image.
| Concern | Swap with revert | Overwrite-only | Direct-XIP |
|---|---|---|---|
| Builds per release | One | One | Two, one per slot |
| Update agent must know the active slot | No | No | Yes |
| Delta patches | One per source version | One per source version | One per source version per slot |
| Version-based downgrade prevention | No; use the security counter | Yes | No; use the security counter |
| Encrypted images in external flash | Supported | Supported | Not supported |
| Bootloader code | The most complex path | “Substantially simpler” than swap | Kconfig: “simpler code path and smaller code size” |
| Fallback after a bad release | Automatic revert | None without a recovery path | Automatic, if revert is enabled |
Doubled builds are manageable with CI, but each one must be signed, tested and kept. If you plan delta updates, the patch count doubles too, which the delta firmware updates article works through. Direct-XIP also makes “what version is running” a two-part question: version and slot. Put both in every status report.
Two images on one chip: secure firmware and radio cores
Some connected microcontrollers run more than one image: a secure image and an application image, or an application core and a network core with its own radio firmware. Each image needs its own pair of slots, so every flash cost above applies once per image. The layout choice and the update order have to account for both.
MCUboot handles this directly. Its design document says that with multiple executable images, “Every image can be updated independently therefore the flash is partitioned further to arrange two slots for each image.” TF-M’s reference layout shows the pattern: a primary and a secondary slot for the secure image, and another pair for the non-secure image.
Independence has a limit. The design document notes that “if an image needs to be reverted it might be necessary to revert another one too (e.g. due to API incompatibilities)”, and MCUboot can record dependencies between images and refuse an update whose dependency is not met. Dependencies are described in TLV entries in the image’s protected area, after the end of the image. If your application calls into a secure image or talks to a radio core through a versioned interface, declare that dependency, and test the case where one image reverts and the other does not.
Three questions to settle early for a multi-image product:
- Does each image get its own slots, and do they all fit with the growth you expect?
- Which image updates first, and what does each image do if it finds the other one older than expected?
- If the application image reverts, must the other image revert too, and does your configuration enforce it?
Choosing a layout
Start from swap-using-offset with revert and move away from it only for a reason you can name. Most of the reasons are flash size, flash geometry, boot-time downtime and the downgrade policy.
| If this is true of your product | Consider | Because |
|---|---|---|
| Two images fit in internal flash with uniform sectors | Swap using offset, with revert | Automatic fallback; MCUboot’s Kconfig default where there is no scratch partition, outside the ESP32 family |
| Flash sectors are large or uneven | Swap using scratch, or overwrite with a recovery path | Offset and move need equal sectors; scratch handles mixed layouts but may be removed later |
| You need version-based downgrade prevention and have no hardware counter | Overwrite-only, plus serial recovery or a loader | Version comparison works only with overwrite |
| The boot-time copy is too long, or wear is tight | Direct-XIP with revert | No copy at boot; costs two builds per release |
| No internal flash, enough RAM | RAM-load | Images stay in external storage and run from RAM |
| The image will outgrow half the internal flash | Secondary slot on external flash, or one slot plus a loader | Overwrite does not save slot space |
| ESP32 family on ESP-IDF | Two OTA slots with app rollback enabled | Rollback is off by default |
Two warnings apply to every choice. The bootloader configuration is set at build time and lives in a partition you should not plan to update, so the layout you ship is the layout you keep. And a layout without automatic fallback moves the safety burden onto testing and recovery, which you then have to fund.
Example (fictional). Two products, two answers. Loamwick’s LW-1 probe has uniform 4 KB sectors and a 412 KB image in 1 MB of flash, so it ships MCUboot with swap using offset and revert. The swap lengthens a reboot that happens a few times a year, and the probe sits in a field where a site visit costs a day. Its growth problem is handled on Rev E by moving the secondary slot to external flash, not by giving up the revert.
A second fictional startup builds a Wi-Fi thermostat on an ESP32-family chip with ESP-IDF. It keeps the two OTA slots the framework expects, turns on app rollback, and moves the self-test to the first seconds after boot: Wi-Fi joined, cloud reached, relay driver answering. Because a thermostat that reboots into a revert loop on a cold night is a support call, the team also tests what happens when power is cut during that first boot.
How to test interrupted updates on the bench
Test every layout by cutting power at each of the five moments, many times, and checking that the device always ends on the old image or the new one, never neither. Then test bad images on purpose. Documentation tells you what the bootloader is designed to do; only your board, flash part and update agent tell you what yours does.
The rig
You need a way to remove power on command and a way to read what the device booted:
- A MOSFET or relay in the supply line, switched by a script on a test computer.
- A serial console or debug channel that prints the bootloader’s decision and the running version at each boot.
- A pin the firmware toggles at known points (download started, upgrade requested, application running, image confirmed), so the script can time cuts to those events.
- A bench supply you can ramp down slowly, because a battery sagging through a brownout behaves differently from a clean cut.
The cuts
Cut power at random offsets within each phase, not at one point per phase: several points during the download, during the trailer write that requests the upgrade, early, middle and late in the boot-time copy, during the first run before confirmation, and just after confirmation. Repeat with a reset instead of a power cut, using the reset pin or a forced watchdog, because a reset keeps the supply up and can expose different timing.
The pass rule is the same for every run: the device boots a valid image, reports which one, and accepts the next update. A device that needs a debugger to recover is a failed run, however rare.
The bad images
- An image signed with the wrong key. It must be refused.
- An image built for another hardware revision. The update agent or bootloader must refuse it.
- A valid image that fails its self-test on purpose. It must revert, in layouts that can.
- A valid image that crashes before it can run its self-test. This is the test that shows the difference between swap with revert and overwrite-only.
Example (fictional). Loamwick’s firmware requirements include FW-003: accept signed updates from the gateway and roll back on a failed self-test, verified by pulling power at 10 points in the transfer. Before the field trial, the team extends the test to the swap itself. A script cuts power at 10 offsets during the transfer, 10 during the boot-time swap and 5 during the first run before confirmation, then repeats the 25 runs with resets instead of power cuts. Every run must end with the probe reporting either 1.0.2 or 1.1.0 and accepting the next update. A build that crashes at start-up and an image signed with the old development key are also sent; the first must revert and the second must be refused.
The firmware release checklist keeps the interrupted-update and forced-rollback tests on every release, so a bootloader or agent change cannot quietly break them. The example project shows the same tests in the context of a whole engagement.
What to decide before the layout is frozen
The partition layout is one of the few firmware decisions that cannot be changed by an update once units ship. Settle it while you can still change the board:
- Measure the image you have and estimate its growth, then run the numbers through the flash budget calculator.
- Check the flash geometry in the reference manual: sector sizes in the slot region and the rated erase cycles.
- Pick the mode from the table above, and write down why.
- Decide the fallback: revert, a loader, serial recovery, or a written acceptance that a bad release means a site visit.
- Decide the downgrade policy and whether the security counter or version comparison enforces it.
- Measure boot-time downtime for an update and for a revert on real hardware.
- Run the interruption tests above before the first field unit ships, and keep them in CI.
- Put the configuration in version control with the bootloader build, and check the revert options in the release build.
For the rest of the update chain (signing keys, the update agent, factory programming and staged rollouts), the overview of what it takes to ship firmware you can safely update puts this decision in context. Fumbar, a Denver firm that writes embedded firmware and over-the-air update paths for hardware startups, sets up bootloaders, slot layouts and interruption tests as part of its over-the-air updates work. If you want a second reader before your layout is frozen, a firmware review looks at the flash layout and update plan along with the code.
