Fixing the "known issue" Partitioning limitation with MCUboot swap move

RE: Fixing the "known issue" Partitioning limitation with MCUboot swap move

smith_tristan — Wed, 04 Feb 2026 17:54:40 GMT

Hi Dominik-NS , thank you so much for your help with all of this. Just wanted to share where we ended up, in case anyone else is on the same path:

We ended up adding a script to our build pipeline that calculates our flash usage of the maximum firmware-upgradeable image given the trailer size, etc.

As discussed above, the west build reports flash usage of the primary partition, but staying below 100% alone doesn't ensure firmware upgradeability - because of the necessary space for the trailer and image swap page.

So our new script takes that extra space into account, and analyzes files from the build/ directory in order to tell us the percentage used of the maximum firmware-upgradeable image size.

Here is our final "Build Artifacts" diagram for “Swap Using Move Without Scratch” based on NCS v2.6.x:

And here are the key calculations we use in our script for the app image:

Maximum Image Size Calculations

Block Size: 4 Bytes (nRF5340 write block size)

Page Size: 4096 Bytes (nRF5340 page erase/write size)

BOOT_MAX_IMG_SECTORS: This is the max number of "sectors" necessary for mcuboot to manage our image slots. Recommended to include some padding. If unnecessarily large, will use unnecessary RAM and slow the bootloader down (more time to zero out the RAM).

BOOT_MAX_IMG_SECTORS >= ceil [ ( largest image slot size ) / ( page size ) ]

Swap Status Region Size: Part of the trailer. Depends on BOOT_MAX_IMG_SECTORS and which swap method you are using. For swap with move, we need 3 states - each in a discrete write block. mcuboot/docs/design.md at 268968f8e4a834ea3825d98439e4c321de0c6a78 · mcu-tools/mcuboot

Swap Status Region Size = BOOT_MAX_IMG_SECTORS * Block Size * s

s (number of states for swap move without scratch) = 3

Trailer Size: Part of the slot, this is the part of the slot that MCUBoot uses to keep track of the upgrade swap. Rounded up to the nearest page, where Page Size is 4096 bytes (determined by nRF5340 hardware).

Raw Trailer Size = ( Swap Status Region ) + 80 bytes

Raw Trailer Size = ( BOOT_MAX_IMG_SECTORS * Block Size ) * 3 + 80

Trailer Size = round up to Page Size ( Raw Trailer Size )

Maximum Upgradeable Image Size: Primary slot size (internal flash) for a firmware upgradeable image. Per below, +1 Page because we need a page as temporary scratch for the swap. See here: https://docs.nordicsemi.com/bundle/ncs-latest/page/mcuboot/design.html#swap_using_move_without_using_scratch

Maximum Image Size = ( N - 1 ) * Sector Size - Trailer Size

Sector Size = Page Size = 4096

Trailer Size = nearest page[ BOOT_MAX_IMG_SECTORS * Block Size * s + 80 ]

N = floor( Primary Slot Size / Page Size ) = number of full pages in primary slot

Maximum Image Size = ( N - 1 ) * Page Size - Trailer Size

Primary Slot Flash Usage = 100 * Image Size / Maximum Image Size

This can also be rearranged/described as:

Necessary Primary Slot Size for a Given App Image:

Primary Slot Size >= App Image Size + Trailer Size + 1 Move Page (Swap Sector Page)

And if you're curious, here's an example of our script's output at the end of a build:

RE: Fixing the "known issue" Partitioning limitation with MCUboot swap move

Dominik-NS — Fri, 01 Aug 2025 12:39:32 GMT

First, lets add here reference to MCUboot design doc, explaining the trailer:
https://github.com/mcu-tools/mcuboot/blame/268968f8e4a834ea3825d98439e4c321de0c6a78/docs/design.md#L493

Q1) Swap means that image in slot1 will some time in the future end up in slot0; and may be reverted if only uploaded for test. So any image has to fit into both slots.

If you have slot1 bigger than slot0, you may be able to upload thing that will never fit into image1, or will fit, but mcuboot will never be able to revert it, because it will not be able to write the trailer part.

Think of this like this: it something is too big to fit into either slot, due to trailer and swap info that would appear in that slot, that is the same for the other slot; because in the end that thing will end up in the slot it is too big for.

Q2) Trailer is added from the end of slot (or partition has been dedicated for it).

[quote userid="81660" url="~/f/nordic-q-a/116900/fixing-the-known-issue-partitioning-limitation-with-mcuboot-swap-move/542938"]Can you tell me if it is accurate?[/quote]

No it is not. The trailer is written "backwards" from the end of partition.

You have positioned the trailer in your images, it is placed at the end of partition/slot not app image.

If you try to sign your image, using imgtool, to be already confirmed or set for test, the size of binary will be extended to full image slot, because it adds the trailer then.

Lets say you have slot size of 256k; if you generate hello world, that takes ~34k, it will take ~34-35k signed, but if you sign if to be already confirmed, the signed image will take exactly 256k, because it fills all the space between image and the trailer that has to be placed at the end of image. The trailer comes from the end of partition, it is written "backwards'.

If you have swap move, what happens is that MCUboot shifts up slot0 first, by one page, to release slot0 page for swap from slot1. So you need this extra one page in primary slot. Then it starts to write log from the back of the slot, after the trailer (again, backwards). The trailer does not have to take entire page and can cut into last page taken by application image (after the shift), because the image will not probably take entire page. If trailer is bigger then the space left in that last page, then trailer will need separate page and the space in last page, used by application image, will not be used.

Swap-move does not use scratch page. What it does is moves image by one page, in slot0, which gives it ability to immediately place first page from slot1 into first page of slot0, as the first page has already been moved, basically it looks like this:
1) in slot0 move page i to page i + 1, where i is N, N -1, ... 1, 0; this lives you with image in pages 1, to N + 1 of slot0
2) page i from slot1 is taken and placed in page i of slot0
3) page i + 1 is taken and placed in page i of slot1
4) ++i; goto 2) till the larger image is completely moved.
Of course there is erase of page between each copy and entry to trailer log is added to indicate how far operation went, to be able to recover in case device resets.
Note that you will have at least one and at most two copies of move page at any point.

If you have secondary slot bigger than primary, you may and up uploading something you will not be able to swap. Or once you have it swapped, you will not be able to revert it.

Q3)

[quote userid="81660" url="~/f/nordic-q-a/116900/fixing-the-known-issue-partitioning-limitation-with-mcuboot-swap-move/542938"]What do you mean by "256 logs take up to 3072"? What logs are you referring to?[/quote]

By log I mean, what is correct name, "Swap status" https://github.com/mcu-tools/mcuboot/blame/268968f8e4a834ea3825d98439e4c321de0c6a78/docs/design.md#L1057 . MCUboot writes here each step it has completed to know where to start in case device reboots or something happens that interrupts the swap.
256 is 3 states * 4 write block, which is 3072 size of max swap status, trailer would take additional 80 bytes. But you if you define 256 pages of 4095 and have slot of 256k, then 3/4 of your swap status will never be written, so the additional 80 byte just merge into it.

Q4)

[quote userid="81660" url="~/f/nordic-q-a/116900/fixing-the-known-issue-partitioning-limitation-with-mcuboot-swap-move/542938"]Does CONFIG_BOOT_MAX_IMG_SECTORS affect the "Trailer Move Page / Swap Status Area" Size?[/quote]

Yes.

The CONFIG_BOOT_MAX_IMG_SECTORS determines size of allocated structures for storing information on layout of a device (aka pages) and how much will the "Swap status" cut into the image from the end of slot. You can basically see this as "biggest size of slot(partition) divided by size of device page".

[quote userid="81660" url="~/f/nordic-q-a/116900/fixing-the-known-issue-partitioning-limitation-with-mcuboot-swap-move/542938"]If the actual used sectors is smaller than the max image sectors, will the Trailer and Trailer Move Page / Swap Status Area be smaller as well?[/quote]

MCUboot will use all CONFIG_BOOT_MAX_IMG_SECTORS in RAM, when discovering device layout, but when writing swap status it may only take several, for example if you swap two images of ~40k (between slot0 and slot1), the swap status will only write ~10 * 4 * 3 bytes of status , because only 10 pages are moved. But you have to have enough space to cover entire slot.

[quote userid="81660" url="~/f/nordic-q-a/116900/fixing-the-known-issue-partitioning-limitation-with-mcuboot-swap-move/542938"]Basically, how do we determine the size of the "Trailer Move Page / Swap Status Area" ?[/quote]

CONFIG_BOOT_MAX_IMG_SECTORS is how many sectors MCUboot will be able to move in a biggest slot (still should be the same). It has to be able to cover the biggest slot/partition that is involved in image update.

Here is how the swap status looks like: https://github.com/mcu-tools/mcuboot/blame/268968f8e4a834ea3825d98439e4c321de0c6a78/docs/design.md#L493

If you set CONFIG_BOOT_MAX_IMG_SECTORS=2048, you will have swap status of at most 24k, if you have page of 4k, that is able to handle 8MiB of slot.

RE: Fixing the "known issue" Partitioning limitation with MCUboot swap move

smith_tristan — Sun, 20 Jul 2025 17:03:36 GMT

It seems like my last response was visually clipped, so I'm copying it here at the top level as well...

Dominik-NS

Hi Dominik, thanks again for all your responses. I think I understand a little bit better, but I still have a couple questions.

Q1)

Previously you said: "Please check your PM_MCUBOOT_SECONDARY_SIZE, because it seems that this is significantly shorter. The trailer equation will only work with the secondary slot, because here the trailer can touch the last page of binary, something it can not do in primary slot."

I am still trying to interpret this suggestion. My thought is:

Primary Image Slot can take a maximum signed image of 966656 ← 974848 - 2 * 4096

Secondary Image Slot Size however is 974848. Which is much larger than the Primary Image Slot max image size.

So is your concern that we could have a secondary image too large to be swapped into the primary slot safely?

ie, the Secondary Slot is totally full and does not account for the 2 extra pages needed in the Primary Slot?

Q2)

I've come up with this diagram to help me understand how this all goes together, and each piece that has to go into each slot.

Can you tell me if it is accurate?

Q3)

Previously you said: "Generally 256 is ok if size of slot is < 1MiB. As you can see this has to round up to a page anyway, and 256 logs take up to 3072 so plenty more space to fit the rest of trailer."

What do you mean by "256 logs take up to 3072"? What logs are you referring to?

Q4)

Looking at the diagram I shared,

Does CONFIG_BOOT_MAX_IMG_SECTORS affect the "Trailer Move Page / Swap Status Area" Size?

For example, if our CONFIG_BOOT_MAX_IMG_SECTORS=2048, will the extra space required in the Primary Slot be (2048 * 4 * 3 + 80) + the page for the Image Move?

Basically, how do we determine the size of the "Trailer Move Page / Swap Status Area" ?

If the actual used sectors is smaller than the max image sectors, will the Trailer and Trailer Move Page / Swap Status Area be smaller as well?

RE: Fixing the "known issue" Partitioning limitation with MCUboot swap move

variant — Sun, 15 Jun 2025 18:16:37 GMT

It's been a while since Dominik's reply. We appreciate the reply. One of our local experts has been away for a month. We still intend to reply if we have further questions once he returns.

RE: Fixing the "known issue" Partitioning limitation with MCUboot swap move

Dominik-NS — Wed, 02 Apr 2025 18:10:25 GMT

1) Primary Slot Size: has to contain the image + trailer + 1 page for move page
Yes, trailer is rounded to N pages, where page is 4096 bytes (min for hardware)

2) BOOT_MAX_IMG_SECTORS must be larger than: ( Largest Image Slot Size ) / Erase Page Size
Yes. Because BOOT_MAX_IMG_SECTORS determines size of swap log size. You are swapping BOOT_MAX_IMG_SECTORS at most, which is slot size/page size

3) Erase Page Size = 4kBytes for the NRF5340
Yes,; when external mem is used, the bigger size is used, but it can not be less than physical limitation of any of memories (4k is min for nrf53/nrf52)

4) Trailer Size (bytes) = ( BOOT_MAX_IMG_SECTORS * Block Size ) * 3 + 80

Block size == Write block size (4 bytes); yes, but rounded up to pages. MCUboot has to copy/erase by pages.

5) We start with a primary image slot size = 974848 bytes (0xEE000)

6) BOOT_MAX_IMG_SECTORS >= 238 = 974848 / 4096

7) Given that the trailer is 4096 bytes, this gives us a useable space of 966656 bytes.

should

Q2) However, because of the MCUBOOT pad, should we actually start with 974336 bytes as the primary image slot size? That is address space of 0x10200 to 0xFE000.

No.The pad is just shifting application image by the size required for image header, but header is part of the image that is being moved around. This thing is for compiler/linker to figure out where code actually should start. After you build application the 0x200 bytes are added in front of by imgtool when image is signed. There is another chunk of data added at the end in form of TLV that store info like signature. The real size that is swapped between slots is what you see as app_update.bin (or zephyr.signed.bin), not the thing that build reports in the end.

Q3) Also, why is there not a general recommended BOOT_MAX_IMG_SECTORS configuration for any nRF5340 project? Would 256 always be the recommended number of sectors?

Generally 256 is ok if size of slot is < 1MiB. As you can see this has to round up to a page anyway, and 256 logs take up to 3072 so plenty more space to fit the rest of trailer. The space gets shorter when using encryption (because keys are also dropped there), in which case you may wan to cut the the BOOT_MAX_IMG_SECTORS to actual size, to not take another page.

The best way to test your setup is build your app, check size difference between signed and unsigned. Then add, to the end of binary, enough bytes to fill the slot, save the header (0x200), the difference checked above and - 2* 4096 in pages. Now when you sign what you have you should have signed binary of size of slot - 2* 4096 bytes; that thing should correctly upload to device and swap into primary slot.

RE: Fixing the "known issue" Partitioning limitation with MCUboot swap move

smith_tristan — Tue, 01 Apr 2025 22:22:01 GMT

Hi Dominik-NS - I work with variant , trying to catch up on this thread...

Q1) What do you mean when you say: "Please check your PM_MCUBOOT_SECONDARY_SIZE, because it seems that this is significantly shorter."? Shorter than what?

In partitions.yml, I see mcuboot_secondary: size: 0xee000 (974848 bytes).

Just to make sure I'm understanding correctly:

1) Primary Slot Size: has to contain the image + trailer + 1 page for move page

2) BOOT_MAX_IMG_SECTORS must be larger than: ( Largest Image Slot Size ) / Erase Page Size

3) Erase Page Size = 4kBytes for the NRF5340

4) Trailer Size (bytes) = ( BOOT_MAX_IMG_SECTORS * Block Size ) * 3 + 80

So for the nRF5340:

5) We start with a primary image slot size = 974848 bytes (0xEE000)

6) BOOT_MAX_IMG_SECTORS >= 238 = 974848 / 4096

7) Given that the trailer is 4096 bytes, this gives us a useable space of 966656 bytes.

Q2) However, because of the MCUBOOT pad, should we actually start with 974336 bytes as the primary image slot size? That is address space of 0x10200 to 0xFE000.

Q3) Also, why is there not a general recommended BOOT_MAX_IMG_SECTORS configuration for any nRF5340 project? Would 256 always be the recommended number of sectors?

Thank you!

Tristan

RE: Fixing the "known issue" Partitioning limitation with MCUboot swap move

Dominik-NS — Fri, 21 Mar 2025 16:11:26 GMT

I think we are mistaking binary with mcuboot image, these are different things:

the top one is binary, that is the thing build logs size form; the bottom one is image, that is uploaded to the device.
Once your image is signed there is additional information added to it, and build log does not show that info.
For experiment I have appended my binary with enough data to fill, after signing, entire slot - 2 * 4096 bytes, and that worked fine. But I have been using equal slot sizes, that is why I have to subtract on slot for move area and one for trailer rounded up to one slot.
In primary slot trailer may not be written in the same page as the swapped in image is.

In secondary slot trailer may be written to the same page as uploaded, because there is no "move" page between trailer and image.
The move page needs to be erased independently, so it can not be either part of image nor trailer.
But that image will be swapped to the primary slot, and at that point that slot has to be able to

It seems that you have CONFIG_BOOT_MAX_IMG_SECTORS=256, the nrf5340 has a 4096B page and 4B write block, 974848 primary slot.

The 974848 takes 238 slots, so 238 * 3 * 4 + 80 = 2936 ~= 4096
So primary slot can take max 974848 - 2 * 4096 = 966656

Please check your PM_MCUBOOT_SECONDARY_SIZE, because it seems that this is significantly shorter. The trailer equation will only work with the secondary slot, because here the trailer can touch the last page of binary, something it can not do in primary slot.

RE: Fixing the "known issue" Partitioning limitation with MCUboot swap move

variant — Wed, 19 Mar 2025 20:39:30 GMT

Thanks for the reply Vidar Berg . And I apologize Dominik-NS that I didn't realize you were replying as a Nordic rep. Your reply was very detailed, but I wasn't sure it was sanctioned by Nordic. 🙂
Attached is the build/mcuboot/zephyr/.config file that Vidar suggested I post.

Thanks again.

devzone.nordicsemi.com/.../.config_5F00_for_5F00_mcuboot.txt

RE: Fixing the "known issue" Partitioning limitation with MCUboot swap move

Vidar Berg — Mon, 17 Mar 2025 11:03:00 GMT

Sorry, I assumed the questions got answered by Dominik-NS comments above. He is a Nordicer who is working on MCUBoot. Could you upload the configuration file (build/mcuboot/zephyr/.config) for your bootloader so I can have a look at the configuration?

RE: Fixing the "known issue" Partitioning limitation with MCUboot swap move

variant — Fri, 14 Mar 2025 19:41:31 GMT

Is there going to be any reply from Nordic?

RE: Fixing the "known issue" Partitioning limitation with MCUboot swap move

Dominik-NS — Thu, 09 Jan 2025 10:58:17 GMT

One more update.

As it may be tempting to set the BOOT_MAX_IMG_SECTORS to (image_slot_size_in_bytes - erase_page_size_in_bytes) / erase_page_size_in_bytes, it would not be correct.
The BOOT_MAX_IMG_SECTORS needs to be set to highest of image_slot_size_in_bytes / erase_page_size_in_bytes of two values, assuming two slots may have different sizes, as it has to hold information on layout for both slots, as we will erase any page in the slot range.

So in reality, after the BOOT_MAX_IMG_SECTORS has been established, the trailer itself, can be calculated as
(((BOOT_MAX_IMG_SECTORS * write_block_size) * 3 + 80.

But aside from the above value, the image will also loose one additional page for the "move" page.

RE: Fixing the "known issue" Partitioning limitation with MCUboot swap move

Dominik-NS — Thu, 09 Jan 2025 10:39:47 GMT

Hi,

The BOOT_MAX_IMG_SECTORS is actually mentioned in NCSDK-20567, as CONFIG_BOOT_MAX_IMG_SECTORS, and how it weights against (image_slot_size_in_bytes - erase_page_size_in_bytes) / erase_page_size_in_bytes. Unfortunately I did calculations from the point of hardware to software impact and so there was no clear indication how the BOOT_MAX_IMG_SECTORS impacts calculations, as a software configuration item.

The BOOT_MAX_IMG_SECTORS does indeed impact size of footer. It is mainly used, in MCUboot, to calculate log size and to allocate array of sectors (erase units on device) (as explained in NCSDK-20567)

Internal details are below, if interested.

The first usage is done here boot_status_internal_off (note that this is unfortunate name for a partial offset, not full offset from the end of slot):
https://github.com/nrfconnect/sdk-mcuboot/blob/b82206c15fff357c151c24bf97c99c4348d14a46/boot/bootutil/src/swap_move.c#L221 (for MOVE algorithm, SCRATCH has own function for that) - basically the function is called given write-block-size of a device (elem_sz) and calculates log for 3 states (BOOT_STATUS_MOVE_STATE_COUNT) per page/sector moved (BOOT_MAX_IMG_SECTORS).
Above can also be seen in swap_read_status_bytes https://github.com/nrfconnect/sdk-mcuboot/blob/b82206c15fff357c151c24bf97c99c4348d14a46/boot/bootutil/src/swap_move.c#L204 when calculating maximum expected log entries, without footer "header" (that is why it is "partial").

The other usage is in allocating table for sector information; the array is used to store information on offset and size of each sector that covers slot - this happens, because MCUboot has been designed with devices with non-uniform sector layout, like stm32, where each sector can have different size, https://github.com/nrfconnect/sdk-mcuboot/blob/b82206c15fff357c151c24bf97c99c4348d14a46/boot/bootutil/src/loader.c#L96.
The BOOT_MAX_IMG_SECTORS needs to be provided by user, because it is not always possible to get that info from DTS, for example spi devices do not have such info and so far non-uniform devices have no such definition.

Regards,
Dominik

RE: Fixing the "known issue" Partitioning limitation with MCUboot swap move

variant — Wed, 08 Jan 2025 12:57:29 GMT

Hi Vidar, is there any update on your last reply? Can you at least confirm for sure that the value for BOOT_MAX_IMG_SECTORS does indeed affect the max size of the updateable image.

RE: Fixing the "known issue" Partitioning limitation with MCUboot swap move

Vidar Berg — Thu, 12 Dec 2024 14:20:03 GMT

Hi,

Yes, this does not appear to be correct, unfortunately. I'm awaiting feedback from the developers on this. The value of BOOT_MAX_IMG_SECTORS * 4096 must be bigger than or equal to the size of the mcuboot slot, and since the BOOT_MAX_IMG_SECTORS value affects the image trailer size, it seems like it should have been included in the calculation as you said.

RE: Fixing the "known issue" Partitioning limitation with MCUboot swap move

variant — Wed, 11 Dec 2024 15:23:25 GMT

Hi Vidar,

Ok, so for the equation in NCSDK-20567 to calculate max app size:
mcuboot_primary_size - 80 - (mcuboot_primary_size/ 4096) * 12 -4096

you said the mcuboot_primary_size is PM_MCUBOOT_PRIMARY_SIZE.

1. For my case,
PM_MCUBOOT_PRIMARY_SIZE is 0xee000, or 974848.

The max app size equation in NCSDK-20567 results in 967816

Our build log "Memory region" for FLASH lists "Region Size" as 974336.

If hypothetically my actual app size were 967816 as being the "Used Size" in the build log, the build log would report "%age Used" as 967816 / 974336 = 99.33%. I know that 99.33% can't be correct because we hit the max size issue at 96% as reported by the build log. What am I doing wrong in this example?

I don't think the NCSDK-20567's "Some additional margin is suggested" would account for the discrepancy.

2. According to image trailer,

If the image trailer size depends on BOOT_MAX_IMG_SECTORS, then why doesn't the equation in NCSDK-20567 include that value in the equation? More specifically, does BOOT_MAX_IMG_SECTORS have any impact on the max app size that can be FW updated?

Thanks in advance!

RE: Fixing the "known issue" Partitioning limitation with MCUboot swap move

variant — Mon, 09 Dec 2024 02:27:09 GMT

Thanks Vidar for the very detailed and clear reply.
I will have a follow-up question on your answer shortly. I haven't had a chance to research something yet, but I wanted to get the thank you sent now.

RE: Fixing the "known issue" Partitioning limitation with MCUboot swap move

Vidar Berg — Wed, 04 Dec 2024 14:44:11 GMT

Hi,

The size of the primary slot is defined by the PM_MCUBOOT_PRIMARY_SIZE symbol in pm_config.h which is generated by the partition manager during the build.

Fixing this issue is still in our backlog. I’ve requested that we prioritize addressing it so you can receive a build time error if the image will exceed the maximum size for the secondary slot. As you may know, the reason the FW image can't fill the whole partition is that we need to leave room for the image trailer at the end.

[quote user=""]1. In the Workaround description, there is a formula to calculate the approximate size limitation. What CONFIG item is referred to for mcuboot_primary_size? I am not able to figure out how to use that equation to result in a value of approximately 95% of the "Region Size" for the application image indicated in the build log.[/quote]

The percentage will vary depending on the size of the partition. Larger partitions can have utilization above 95%

[quote user=""]2. Why is "additional" margin suggested? Can that margin be quantified?[/quote]

This was to account for any changes in the image trailer size. For example, the image trailer becomes larger if encryption is enabled. The best way to verify that there is enough room for the image trailer with your configuration is to test the DFU of the image locally before distributing the update. If the image is too large, the bootloader will fail to copy the update to the primary slot. It is also important that you are using the same static partition layout across FW versions (Configuring static partitions)

[quote user=""]4. When the fix is available, do you think the fix can be patched by us to an earlier NCS version, such as NCS 2.6?[/quote]

The planned fix is to calculate the actual space available for the firmware image at build time and provide the user with an error if the image is too large for DFU.

Best regards,

Vidar