UF2 considerations
- Dominant language
- C
- Stars
- 2.8k
- Forks
- 1.1k
- Avg merge
- 3d 12h
- Merged PRs (30d)
- 1
Description
I'm looking at adding UF2 on top of the Universal Hex out-of-order blocks implementation:
- https://github.com/ARMmbed/DAPLink/pull/1092
I've rebased this branch, which has a basic UF2 implementation already working:
- https://github.com/ARMmbed/DAPLink/compare/develop...mbrossard:DAPLink:feature/uf2
There are a few things we need to consider before finishing the implementation.
Everything here is up for discussion, this is just my initial proposal.
## Won't Implement
Some things that I'll l likely **not** implement at this point:
- [File containers](https://github.com/microsoft/uf2/blob/d03b585ed780ed51bb0d1e6e8cf233aacb408305/README.md#file-containers)
- This requires knowledge in DAPLink about the target filesystem, so it's generic enough for all boards
- Any particular board that might want to implement this could probably add hook into `write_uf2()` and include it in their port
- [CURRENT.TXT](https://github.com/microsoft/uf2/blob/d03b585ed780ed51bb0d1e6e8cf233aacb408305/README.md#files-exposed-by-bootloaders)
- No special reason, simply trying to reduce scope for now
- If implemented it should probably be with a compile-time flag selectable per port
- [MD5 checksum](https://github.com/microsoft/uf2/blob/d03b585ed780ed51bb0d1e6e8cf233aacb408305/README.md#md5-checksum)
- `target_flash_program_page()` can already verify data written if automation is enabled
- But this is more useful to avoid writing data to flash (reduces flashing time). So, this is only useful when page-by-page erase and programming is enabled, as otherwise it does a full chip erase when it receives the first valid data block.
## Could implement
Some things that are not implemented yet but can consider adding.
- Tracking that all individual blocks have been received
- This requires a buffer with a bit per block, so for a device with 256 KB and 256 bytes per block, it'd need 1 KB of RAM. Unsure if this is viable for all DAPLink ports
- Alternatively this feature could be turned off by default, and enabled via compile-time flag
- UF2 files with multiple targets could also require an arbitrary number of flag buffers, although we could only track the blocks relevant for the current target
- https://github.com/microsoft/uf2/issues/91
- vfs_manager tracks the UF2 file size, so and if fewer blocks than expected arrive it will throw an error
- However, this does not protect from the OS sending the same block more than once (perhaps it creates a temporary file, or metadata file)
## Open questions
1) Should [UF2.TXT](https://github.com/microsoft/uf2/blob/d03b585ed780ed51bb0d1e6e8cf233aacb408305/README.md#files-exposed-by-bootloaders) file be created in the MSC drive?
- If implemented we might want to add it as a compile-time flag as well
2) UF2 FamilyID corresponds to a generic MCU family or specific MCU variants, but it doesn't quite match the Mbed/DAPLink Board ID
- 2.1) We could try to allocate a range of FamilyID values where the top 2 most significant bytes represent "this is DAPLink family" and the 2 least significant bytes match the Board ID
- 2.2) We could use [extension tags](https://github.com/microsoft/uf2/blob/d03b585ed780ed51bb0d1e6e8cf233aacb408305/README.md#extension-tags). The existing "device type identifier" could work, but we could create a DAPLink specific one to include the Board ID.
- 2.3) Should we also expand `target_family_descriptor` to include the [UF2 family IDs](https://github.com/microsoft/uf2/blob/master/utils/uf2families.json) for supported families?
Contributor guide
Research direction
Start by reviewing the linked Universal Hex pull request and the existing UF2 branch, then trace write_uf2(), vfs_manager, target_flash_program_page(), and target_family_descriptor. Compare the open questions with the UF2 specification and supported DAPLink ports; done criteria are not defined because this issue is still a design discussion.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- c
- Domain
- embedded-iot
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 20/100