# re-bba-rb — on-console test suite (GameCube)

A `.dol` you run from Swiss that drives the adapter in Serial Port 1 and
reports pass/fail per test on the TV.

## Build

Needs devkitPro's `gamecube-dev` group (devkitPPC + libogc). The devcontainer
installs it — if `DEVKITPPC` is unset, **rebuild the container**, since the
toolchain is added in `.devcontainer/Dockerfile`.

```bash
make            # -> gc_bba_test.dol
```

Copy the `.dol` to your SD card (SD Gecko / SD2SP2) and launch it from Swiss.

## Controls

| Button | |
|---|---|
| D-pad up/down | move |
| A | open a suite / rerun the selected test |
| X | run the selected suite |
| START | run everything |
| Y | clear all results |
| B | back |

## What it tests

| Suite | Proves |
|---|---|
| Identity | device enumerates: `04 02 02 00`, HIPR, NWAYS |
| Registers | PAR0–5, IMR writable and read back; IR is write-1-clear |
| Reset/control | NCRA RESET self-clears, SR holds |
| EXI integrity | 200 reads with no bit errors; which EXI clock indices work |
| Ethernet | MAC readback, 60-byte ARP transmit (TI), frame receive (RWP/RI) |
| SPRAM/DMA | ring descriptor is well-formed; reads ≥ 0x100 stream until CS |

## Things that will bite you

**The device ID is a ONE-SHOT.** Address 0 returns `04 02 02 00` only until
the first NCRA reset clears `id_phase` in the gateware; after that it reads
back NCRA. That is correct — it matches the GC's own init order — but it means
the Identity test can only pass once per *console power cycle*. Run it before
the Reset suite. On a re-run the app reports SKIP with an explanation rather
than a misleading failure.

**TI is not proof of transmission.** It only means `TXFrameDrain` handed the
frame to the W5100. A frame can set TI and never reach the wire. The TX test
says so; to confirm the wire, capture on a PC or watch the RX test pick up a
reply.

**The RX test needs traffic.** It waits ~2 s for any frame. On an isolated
link with nothing talking it will fail legitimately — give the PC an address on
the same subnet (the ARP the TX test sends is aimed at `10.0.0.50`, so
`sudo ip addr add 10.0.0.50/24 dev <nic>` makes the PC answer it and both tests
pass together).

**Never over-clock a register read.** Asking for N bytes and clocking more
leaves stale prefetched bytes queued and desynchronises the *next* transaction
— a deterministic every-Nth-read corruption that looks like a signal-integrity
fault. `bba_read()` clocks exactly `len`; don't "round up" for convenience.

**TXDATA takes one byte per transaction.** The register file's effective
address auto-increments per data byte, so a 4-byte write to 0x48 would spill
into 0x49–0x4B. `bba_tx_bytes()` does it correctly.

## Build status

Builds clean (no warnings) with devkitPPC 16.1.0 / GCC 16 in the devcontainer:
`gc_bba_test.dol`, ~172 KB, entry `0x80003100`.

`.gitignore` excludes the build products — run `make` to produce the `.dol`.

## 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:

```bash
sudo ./scripts/send-dol.py enp3s0 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.

**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.

**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.

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.

The one unavoidable 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 check above is what stands between a truncated transfer and that.