From 6c71f5f0576082ced21dbdf4dc1f7d7862d40009 Mon Sep 17 00:00:00 2001 From: Julian Appel Date: Wed, 5 Aug 2026 22:20:23 +0200 Subject: [PATCH] Document an OpenOCD ELF-flash pitfall found during hardware debugging While chasing why the boot-key check stopped working, traced it to openocd's "program verify" silently writing raw file bytes starting at flash 0x0 instead of the ELF's own section addresses, whenever combined with a prior bootloader write in the same OpenOCD invocation -- repeatedly clobbering the just-flashed bootloader with the app's ELF header. Recovered via full chip-erase and reflashing bootloader and app as separate .bin writes with explicit addresses in isolated OpenOCD sessions; both regions verified correct afterward and confirmed working on hardware (key-hold entry and normal app boot). Documented the pitfall and the safe manual-flashing rule so it doesn't get rediscovered the expensive way again. Co-Authored-By: Claude Sonnet 5 --- bootloader/README.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/bootloader/README.md b/bootloader/README.md index 3032296..3090d60 100644 --- a/bootloader/README.md +++ b/bootloader/README.md @@ -88,6 +88,30 @@ pio run -e versapad_usb --target upload Baut die App-Firmware (Repo-Root, nicht `bootloader/`), erzeugt `firmware.uf2` und kopiert es aufs `VERSABOOT`-Laufwerk. Kein Atmel-ICE mehr nötig. +## Achtung bei manuellem SWD-Flashen von Bootloader UND App + +`upload_openocd.py` (App, `env:versapad`) und der Bootloader-Upload (oben) +sind sicher, weil sie jeweils nur ihren eigenen Bereich anfassen. **Beim +manuellen Debuggen über OpenOCD-Kommandozeile aber Vorsicht:** + +`openocd -c "program datei.elf verify"` **ohne explizite Zieladresse** hat +sich in dieser Kombination aus OpenOCD-Version/CMSIS-DAP-Adapter/Target-Skript +als unzuverlässig erwiesen — statt die im ELF hinterlegten Sektionsadressen +(`0x2000` für die App) zu nutzen, landeten die rohen Datei-Bytes teils direkt +ab Flash-Adresse `0x0000` und haben damit den frisch geschriebenen Bootloader +sofort wieder überschrieben (bestätigt am 2026-08-05: Byte 0 an Adresse +`0x0000` war `0x7f`, der Beginn der ELF-Magic `\x7fELF` — die rohe Datei, kein +Firmware-Code). Passierte zuverlässig, wenn Bootloader- und App-Flash im +selben OpenOCD-Aufruf kombiniert wurden. + +**Regel für manuelles SWD-Flashen beider Bereiche:** immer die `.bin`-Datei +verwenden (nie `.elf`) und die Zieladresse **immer explizit angeben** +(`program firmware.bin 0x0 verify` für den Bootloader, +`program firmware.bin 0x2000 verify` für die App), und Bootloader- und +App-Schreibvorgang **in getrennten OpenOCD-Aufrufen**, nicht in einer +gemeinsamen `-c`-Kommandokette. Im Zweifel danach mit `dump_image` in einer +frischen, unabhängigen Sitzung verifizieren. + ## Hardwaretest (2026-08-05) Erster vollständiger Hardwaretest auf einem echten VersaPad-v2-Board über @@ -109,6 +133,15 @@ Atmel-ICE/SWD. Ergebnisse: für genau dieses Bootloader-Pattern vorgeschrieben, hat im vendorten Code gefehlt. Nach dem Fix bootet die App-Firmware zuverlässig, mit und ohne angeschlossenen Debugger. +- **Zweiter Bug beim manuellen Debuggen gefunden:** Beim anschließenden + manuellen SWD-Debugging (Suche nach der Ursache des Tastencheck-Problems, + siehe oben) hat `openocd -c "program app.elf verify"` ohne explizite + Zieladresse wiederholt den Bootloader mit rohen ELF-Datei-Bytes + überschrieben, sobald Bootloader- und App-Flash im selben OpenOCD-Aufruf + kombiniert wurden — siehe "Achtung bei manuellem SWD-Flashen" oben. Nach + einem vollständigen Chip-Erase und getrennten `.bin`-Flashes mit expliziten + Adressen liefen beide Bereiche wieder zuverlässig, Tastencheck und + App-Start bestätigt funktionsfähig. - **Kompletter USB-Flashweg getestet:** `pio run -e versapad_usb --target upload` (App-Firmware, Repo-Root) baut `firmware.bin`, wandelt es über [`../uf2conv.py`](../uf2conv.py) in `firmware.uf2` und kopiert es über