Roflin
4fd337fb24
The launcher committed in b438960 would have hung the console, and reviewing
it against Dennis's suggestion to test with Swiss's boot.dol is what surfaced
it -- Swiss is known-good, so a hang could only have been the launcher, but I
would not have been able to tell that from "the transfer is broken".
Two distinct defects, both from the same oversight -- a DOL's sections load
from 0x80003100 upward, which is exactly where this program is running:
1. The copier was an ordinary C function in .text, so it overwrote its OWN
instructions partway through the copy.
2. The image was staged in a memalign'd buffer, which the destination sections
can overwrite while it is still being read from.
Fixes:
- netboot_stub.S: the copy/zero/cache-flush/jump sequence in position
independent assembly, copied into reserved memory and executed THERE. It
has no globals, no literal pool, no TOC references and no calls, because
any of those would read from the address it was LINKED at rather than the
one it is RUNNING at. It also does the dcbf/icbi pass the C version was
doing through DCFlushRange -- without it the CPU executes stale icache
lines at the entry point.
- netboot_reserve(): carves the top of MEM1 and hands it to
SYS_SetArena1Hi() so neither libogc nor malloc allocates there. Called
FIRST in main(), before the framebuffer.
- netboot_launch(): verifies every text/data section AND bss against the
reserved region and refuses (-3) if any would land on it, instead of
corrupting the staged image or the copier mid-flight. Also hands the new
image a stack inside the reserved tail.
The app now tells you on screen to send Swiss's boot.dol first, and the README
explains why: the launcher and the transfer can each be broken independently
and a hang looks identical, so the first send should be an image whose success
is unmistakable.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
139 lines
6.1 KiB
Markdown
139 lines
6.1 KiB
Markdown
# 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.
|
||
|
||
### Send Swiss's `boot.dol` first
|
||
|
||
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 the copier lives in assembly at the top of MEM1
|
||
|
||
A DOL's sections load from 0x80003100 upward — exactly where this program's own
|
||
`.text` sits. A copier compiled as an ordinary C function would **overwrite its
|
||
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.
|
||
- `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.
|
||
|
||
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.
|