docs(sd): record Spike 3 hardware verification and findings

Mark Spike 3 resolved (genuine 32 GB SDHC mounts, round-trips clean on the
shared SPI2 bus; the 133 GB SDXC's CMD59 rejection was the sole fault).
Capture the FatFS f_rename caveat and the ≤32 GB card-compatibility note in
ADR-007, the resolution in the postmortem, and the verified writeup in the
firmware README.
This commit is contained in:
Julien Calixte
2026-07-11 11:14:31 +02:00
parent b899286639
commit 5335751323
3 changed files with 91 additions and 14 deletions

View File

@@ -355,6 +355,18 @@ derived key.
atomic-rename writes (see
[v0.1 technical → `persistence`](v0.1-mvp-technical.md#module-breakdown)
and [file layout](v0.1-mvp-technical.md#file-layout)).
- **FatFS caveat (Spike 3, verified 2026-07-11):** FatFS's `f_rename` returns
`FR_EXIST` on an existing destination — it does **not** replace like POSIX
`rename(2)`. So the atomic save must `f_unlink` the target before renaming the
`*.tmp` over it, and pair that with **boot recovery**: a lingering `*.tmp` at
startup means the last save didn't finish → promote it (it is the newest
complete, fsync'd copy). See the
[Spike 3 postmortem](postmortems/2026-07-05-spike3-sd-cmd59.md#resolution-2026-07-11).
- **SD-card compatibility:** use a genuine card, ideally **≤32 GB (SDHC/FAT32)**.
Large or counterfeit SDXC cards may reject `CMD59` (SPI-mode CRC) and fail to
mount; we keep CRC required rather than run the user's writing over an
unchecked bus. The device reports a swap-the-card message instead of a hex
code.
---