Clarification about `blockNo` and `numBlocks`

[microbit-carlos]

From the File format description:

• blockNo: Sequential block number; starts at 0
• numBlocks : Total number of blocks in file

And the File containers section concurs in that this should be the block number and count for the entire file:

The fields blockNo and numBlocks refer to the entire UF2 file, not the current file.

But, then the Family ID description suggest that multiple UF2 can be concatenated, and each file will have a different total of numBlocks and duplicated blockNo values:

If the familyID doesn't match, the bootloader should disregard the entire block, including blockNo and numBlocks fields. [...] This also allows for several files with different familyID to be simply concatenated together, and the whole resulting file to be copied to the device with only one actually being written to flash.

And we also have this unmerged PR for joining UF2 files, which does change the blockNo and numBlocks, but it keeps a different count for each Family ID. So joining 3 UF2 files for 2 families, will end up with two different numBlocks (the same family are merged, the other family kept separated):

• add --join option #81
• https://github.com/microsoft/uf2/pull/81/files#diff-2c62a0beb64519fa879c3e146eaaf0efbca0a2d9aca8489247e0ebe603c4ab62R64

So we seem to have to contradictory definitions, unless the definition is meant to be:

• When the file container flag is used blockNo and numBlocks refer to the entire UF2 file
• Otherwise the blockNoandnumBlocksrefer to the blocks for each individualfamilyID`.

[microbit-carlos]

Another related question I have is about the "not main flash" blocks. Are these meant to include the FamilyID and be included in the block count?

Some UF2 bootloader implementations, like the ATSAMDx1, include an extra 100 blocks to define the "maximum number of blocks", which I assume was done to take into account these metadata blocks as well?

• https://github.com/microsoft/uf2-samdx1/blob/a3395d547b0bbe92676214be68e5cec1a2dbba1b/inc/uf2.h#L230

As there could be an arbitrary number of "not main flash" blocks, for implementation trying to track which blocks it has received, it would make sense if the "not main flash" blocks are treated like blocks for a different family (which could have a different block count) and be ignored from the block counting as well.

Of course, for this kind of implementation the reset should be applied after a timeout since the last UF2 block was received, instead of a reset as soon as we reach a block count. The block count can still be used to determine if there are missing blocks for this FamilyID that were expected but not received.

[mmoskal]

IIRC the idea for the not-main-flash blocks is to eg embed source code or other such info that is to be ignored by the MCU. FamilyID was introduced later. But it would totally make sense to define a FamilyID eg for embedded MakeCode source.

Your last two points on the definition are correct.

[microbit-carlos]

But it would totally make sense to define a FamilyID eg for embedded MakeCode source.

Does MakeCode currently include a FamilyID for the not-in-flash blocks?
If they start including a different blockNo and numBlocks, is it possible that might break some of the UF2 bootloaders?

Your last two points on the definition are correct.

Should we update the README? Happy to do a PR, but I wonder if this would be considered a breaking change by the implementation in some bootloaders.

[mmoskal]

MakeCode doesn't use a different familyID for not-in-flash blocks. It probably should.

AFAIK all UF2 bootloaders (except for the oldest versions of my SAMD21 bootloader that no one uses anymore) completely ignore blocks with a different familyID, that is they also do not consider them towards block counts (just checked a bunch of them).

The only one I found that supports multiple familyID unfortunately doesn't do the trick with sticking to a single familyID after it's detected - it's the NRF52840 from Adafruit that supports different familyIDs for App, Bootloader, Softdevice etc. In that case it probably doesn't matter though.

PR is most welcome!