Self-update writes the new build to SD, then boots known-good /boot.dol

Previous version launched the image it had just received, which is the one
thing that cannot be made safe: a broken build hangs the console and the
checks can only catch a truncated or non-DOL image, never a plausible but
broken one.

The flow is now receive -> write to SD -> boot /boot.dol:
  - netboot_sd_write() mounts the card (auto-detecting SD2SP2, then SD Gecko
    slot B, then slot A), writes the image to the path the host asked for,
    and READS IT BACK AND COMPARES.  A half-written .dol that still parses is
    exactly the failure this design exists to avoid, and the card is the one
    component here with no other integrity check.
  - netboot_boot_file() then loads /boot.dol -- a known-good Swiss -- and
    launches that instead.

So the only image this ever jumps into is one that was already known good.  A
broken test build costs nothing: Swiss comes up and can load anything,
including the previous build.  If the SD write or verify fails, nothing is
launched at all and the menu is still there.

The destination path travels in the DONE frame rather than being baked in, so
the host decides where the build lands (send-dol.py --dest, default
/gc_bba_test.dol).

libfat is unmounted before the jump: leaving the card mounted hands the next
image a filesystem libfat still thinks it owns, on an EXI channel it is about
to reinitialise.

Note the SD Gecko in memory-card slot A shares EXI channel 0 with the BBA
(channel 0, device 2).  libogc arbitrates, but SD2SP2 is on its own channel
and avoids the question -- hence the detection order.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

gc_bba_test/README.md

@@ -75,44 +75,53 @@ Builds clean (no warnings) with devkitPPC 16.1.0 / GCC 16 in the devcontainer:
 
 ## Self-update over the BBA (Z button)
 
-Press **Z** in the test app to pull a new `.dol` over the adapter and relaunch
-into it, instead of copying to the SD card and rebooting.
-
-On the host, with the interface facing the GameCube:
+Press **Z**, then on the host:
 
 ```bash
-sudo ./scripts/send-dol.py enp3s0 gc_bba_test/gc_bba_test.dol
+sudo ./scripts/send-dol.py <iface> gc_bba_test/gc_bba_test.dol
 ```
 
-It needs `CAP_NET_RAW`, hence `sudo`. The GC's MAC is discovered from its first
-ACK, so nothing needs configuring on either side — no IP address, no DHCP.
+The flow is deliberately **receive → write to SD → boot Swiss**:
 
-**It is deliberately not IP.** Frames carry a private ethertype (`0x88B5`,
-IEEE 802 local experimental 1) and a 12-byte header, so there is no ARP, no IP
-stack, no checksums and no libogc network driver competing for the EXI
-channel. It reuses exactly the two paths the test suite already proves on
-hardware: `bba_tx_bytes()` for TX, and the SPRAM ring at RRP for RX. That also
-makes it a useful soak test of the data path — a few hundred round trips per
-update.
+1. The new build arrives over the adapter into a staging buffer.
+2. It is written to the SD card (default `/gc_bba_test.dol`, override with
+   `--dest`) and **read back and compared**.
+3. The app then boots **`/boot.dol`** — your known-good Swiss.
 
-**The transfer is stop-and-wait, and that is load-bearing.** The gateware does
-not consume RRP, so `RXFrameAssembler` can overwrite ring pages the GC has not
-read yet — there is no overflow protection. One block in flight means the ring
-never holds more than one unread frame. Do **not** turn this into a sliding
-window without adding RBFI-style protection first.
+**The received image is never launched.** The only thing this ever jumps into
+is Swiss, which was already known good. So a broken test build costs nothing:
+Swiss comes up, and you load whatever you like from there, including the
+previous build. That is what makes the update recoverable without a power
+cycle or digging the SD card out.
 
-Failure behaviour, so a bad update never costs a power cycle:
-- 30 s with no frames at all, or 5 s mid-transfer, aborts back to the menu.
-- A duplicate block is re-ACKed rather than ignored, so a lost ACK recovers.
-- `netboot_launch()` refuses an image whose entry point or first text section
-  is not in MEM1, rather than jumping into a mis-parsed header.
+If the SD write or the verify fails, nothing is launched at all — you stay in
+the menu with a working app.
 
-### Send Swiss's `boot.dol` first
+`sudo` is needed for `CAP_NET_RAW`. The GC's MAC is discovered from its first
+ACK, so neither side needs an address configured.
 
-The launcher and the transfer are separate things that can each be broken, and
-a hang looks the same either way. Send a **known-good** image the first time —
-Swiss's `boot.dol` is ideal, because it is unmistakable when it boots. If
-Swiss comes up, both halves work and you can then trust an untested build.
+### Why it is not IP
+
+Frames carry a private ethertype (`0x88B5`, IEEE 802 local experimental 1) and
+a 12-byte header: no ARP, no IP stack, no checksums, and no libogc network
+driver competing for the EXI channel. It reuses exactly the two paths the test
+suite already proves on hardware — `bba_tx_bytes()` for TX and the SPRAM ring
+at RRP for RX — so each update doubles as a few hundred round trips of soak
+testing through that path.
+
+### Stop-and-wait is load-bearing
+
+The gateware does not consume RRP, so `RXFrameAssembler` can overwrite ring
+pages the GC has not read yet — there is no overflow protection. One block in
+flight means the ring never holds more than one unread frame. Do **not** turn
+this into a sliding window without adding RBFI-style protection first.
+
+### SD interfaces
+
+`netboot_sd_write()` auto-detects, trying SD2SP2, then SD Gecko slot B, then
+slot A. Note the SD Gecko in **slot A shares EXI channel 0 with the BBA**
+(channel 0, device 2); libogc arbitrates, but SD2SP2 sits on its own channel
+and avoids the question.
 
 ### Why the copier lives in assembly at the top of MEM1
 
@@ -121,18 +130,22 @@ A DOL's sections load from 0x80003100 upward — exactly where this program's ow
 own instructions partway through the copy** and hang. So:
 
 - `netboot_reserve()` carves the top of MEM1 and hands it to
-  `SYS_SetArena1Hi()`, so neither libogc nor `malloc` will touch it. The image
-  is staged there, never in heap memory.
-- `netboot_stub.S` is copied into that region and executed *there*, clear of
-  everything the image writes. It must stay strictly position independent: no
-  globals, no literal pool, no TOC references, no calls — otherwise it reads
-  from the address it was *linked* at instead of the one it is *running* at.
+  `SYS_SetArena1Hi()`, so neither libogc nor `malloc` will touch it.
+- `netboot_stub.S` is copied into that region and executed *there*. It must
+  stay strictly position independent: no globals, no literal pool, no TOC
+  references, no calls — otherwise it reads from the address it was *linked*
+  at instead of the one it is *running* at.
 - `netboot_launch()` checks every section (and BSS) against the reserved
-  region and **refuses** if any would land on it, rather than corrupting the
-  image or the copier mid-flight.
+  region and **refuses** if any would land on it.
 
-The remaining risk is the jump itself: once sections are copied and interrupts
-are off, a bad image hangs the console and needs a power cycle. The header and
-overlap checks are what stand between a truncated transfer and that — they
-cannot validate a *plausible* but broken image, which is why the first send
-should be Swiss.
+### Failure behaviour
+
+- 30 s with no frames, or 5 s mid-transfer, aborts back to the menu.
+- A duplicate block is re-ACKed rather than ignored, so a lost ACK recovers.
+- `netboot_receive()` re-asserts the NCRA SR bit first: an earlier test may
+  have left receive disabled, and it would otherwise wait forever for frames
+  the gateware is not storing.
+- A failed SD write or verify launches nothing.
+- The residual risk is confined to booting `/boot.dol`. If that is a healthy
+  Swiss, this is the safe part; if it is missing or corrupt, you get a message
+  and stay in the menu — the new build is already on the card either way.