Fold bootloader documentation into the main doc/ index

Adds doc/10_usb_bootloader.md as the primary reference for the UF2
bootloader (memory layout, key-based boot entry, build/flash steps,
hardware test findings, known limitations), following the existing
numbered-doc convention. Updates doc/INDEX.md, doc/09_known_limitations.md
(bootloader is no longer "not supported", just scoped), and
doc/08_development.md accordingly.

Removes bootloader/TESTING.md (its findings now live in
doc/10_usb_bootloader.md) and trims bootloader/README.md down to what
belongs with that subproject specifically: upstream attribution/license
and local build/flash commands, plus the OpenOCD manual-flashing
warning since that's implementation-specific detail that would clutter
the higher-level doc.

Updates the top-level README.md (feature table, hardware table,
quickstart, project tree, doc links) to reflect USB flashing as a
supported path alongside SWD.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Julian Appel 2026-08-05 22:49:56 +02:00
parent 3986d2effe
commit 33d9e85992
7 changed files with 153 additions and 201 deletions

View file

@ -3,36 +3,33 @@
Diese Liste beschreibt den aktuellen Implementierungsstand nach den
Robustheitskorrekturen. Sie ist keine Liste bereits umgesetzter Features.
## Bootloader-Ziel bleibt nicht unterstützt
## USB-Bootloader hat einen eingeschränkten Gültigkeitsbereich
Das aktive Ziel `versapad_nobl` reserviert den kompletten Bereich
`0x1FB00..0x1FFFF` für Makros und Config.
Der UF2-Bootloader (`bootloader/`, App-Environment `env:versapad_usb`,
Details in [10_usb_bootloader.md](10_usb_bootloader.md)) ist auf echter
Hardware verifiziert und ergänzt den SWD-Weg, ersetzt ihn aber nicht: der
Bootloader selbst muss weiterhin einmalig per Atmel-ICE/SWD geflasht werden.
Ein USB-Bootloader-Pfad wird im Branch `feature/usb-bootloader` aufgebaut
(`bootloader/`, App-Environment `env:versapad_usb`). Der komplette Weg ist
dort auf echter Hardware verifiziert: Bootloader-Flash, USB-Enumeration,
Tastencheck-Einstieg (kein physischer Reset-Taster auf diesem Board, siehe
`bootloader/README.md`, "Hardware-Bootloader-Einstieg"), App-Firmware per
`.uf2` über `env:versapad_usb --target upload` schreiben, automatischer
Rücksprung in die neue App. Details und ein gefundener/behobener
Hard-Fault-Bug beim Sprung Bootloader→App (fehlende `__DSB()`/`__ISB()` vor
dem `bx`) stehen in `bootloader/README.md`, "Hardwaretest".
`env:versapad_usb`s Linkerskript
(`variants/versapad/linker_scripts/gcc/flash_with_bootloader.ld`) reserviert
inzwischen denselben NVM-Bereich wie `flash_without_bootloader.ld`.
Verbleibende Einschränkungen:
Trotzdem noch kein Merge-fertiges Produktionsziel: Der `.bin``.uf2`-Weg
(`uf2conv.py`, `upload_uf2.py`, Repo-Root) sucht das `VERSABOOT`-Laufwerk
bisher nur über die Windows-API, keine macOS/Linux-Unterstützung. Die
Bootloader-USB-PID (`0x0043`) ist zwar kollisionsfrei verifiziert, aber kein
offiziell registrierter Wert unter Adafruits VID `0x239A`.
- `uf2conv.py`/`upload_uf2.py` (Repo-Root) suchen das `VERSABOOT`-Laufwerk
nur über die Windows-API, keine macOS/Linux-Unterstützung.
- Die Bootloader-USB-PID (`0x0043`) ist kollisionsfrei verifiziert, aber kein
offiziell registrierter Wert unter Adafruits VID `0x239A`.
- Kein Software-Trigger, um aus der laufenden App heraus in den
Bootloader-Modus zu wechseln — nur der physische Weg (Kabel ziehen, Taste
halten, wieder einstecken).
- Bootloader-Flash-Auslastung ~90 % (7364 von 8192 Byte), wenig Puffer für
Änderungen am Bootloader selbst.
Die aktive Boarddatei benennt die MCU als `samd21g17d`, setzt für den
Sowohl `boards/versapad_nobl.json` (SWD-Ziel) als auch `boards/versapad.json`
(USB-Bootloader-Ziel) benennen die MCU als `samd21g17d`, setzen für den
Arduino-Core aber weiterhin das Kompatibilitätsmakro `__SAMD21G18A__`. Der
PlatformIO-Build meldet korrekt 128 KiB physischen Flash, 16 KiB RAM und
129.792 Byte nutzbaren Firmwarebereich. Vor device-spezifischen
Core-Änderungen sollte die historische Makro-Abweichung trotzdem geprüft
werden.
129.792 Byte (`versapad_nobl`) beziehungsweise 121.600 Byte
(`versapad`, abzüglich 8 KiB Bootloader) nutzbaren Firmwarebereich. Vor
device-spezifischen Core-Änderungen sollte die historische Makro-Abweichung
trotzdem geprüft werden.
## Event-Queue hat eine feste Kapazität