ARMmbed / ARMmbed/DAPLink

UF2 considerations

Open
#1,095 16 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.