Update gba/README for two-variant build + tester payload.

Author: RobertDaleSmith

gba/README.md

@@ -1,61 +1,80 @@
-# joypad-gba
+# joypad-tester / gba
+
+GBA multiboot payloads that ship inside [joypad-tester](..). Two ROMs
+build from this one source tree:
+
+- **`joypad_mb.gba`** — Doridian-style joybus controller + animated
+  cartoon eyes overlay. Consumed by
+  [joypad-os](https://github.com/joypad-ai/joypad-os) via submodule for
+  its GBA-as-controller mode.
+- **`tester_mb.gba`** — Doridian-style joybus controller + an on-GBA
+  console showing live button state, with an idle screensaver that
+  bounces the joypad logo (color-cycling on each wall hit) à la the
+  GameCube tester. Embedded into joypad-tester's GameCube/Wii host so
+  testers see visual feedback on the GBA, and runnable standalone from
+  a flash cart as a pure button-tester ROM.
+
+The `build/` tree ships pre-built artifacts so consumers using this
+folder as a submodule (e.g. joypad-os) don't need devkitARM unless
+they're modifying the source:
 
-GBA multiboot payload that doubles as a USB controller (via the GameCube↔GBA
-link cable) and renders animated cartoon eyes on the GBA screen.
+```
+build/joypad/joypad_mb.gba       # eyes ROM (raw multiboot binary)
+build/joypad/joypad_payload.c    #          (C array for embedding)
+build/tester/tester_mb.gba       # tester ROM (raw multiboot binary)
+build/tester/tester_payload.c    #            (C array for embedding)
+```
 
-Designed to be embedded into firmware that drives the GameCube side of a
-joybus link — e.g. RP2040-based controller adapters — but the payload itself
-is host-agnostic. Anyone with a working joybus multiboot uploader can use it.
+Each `*_payload.c` exports the same symbol names:
 
-The `build/` directory ships pre-built artifacts so consumers using this
-repo as a submodule don't need devkitARM unless they're modifying the source:
+```c
+extern const uint8_t  joypad_payload[];
+extern const uint32_t joypad_payload_len;
+```
 
-- **`build/joypad_payload.c`** — the payload as a C array (`joypad_payload[]`
-  + `joypad_payload_len`) ready to compile into a host project
-- **`build/joypad_mb.gba`** — the raw multiboot binary, suitable for dumping
-  onto a flashcart or piping through any joyboot uploader
+so a host can drop either file in and the embedding code doesn't have
+to change. Pick the variant that fits your product.
 
 ## Lineage
 
-The joybus handshake + main loop in `source/main.c` (the `0x30303030`
-exchange, `ResetHalt`, `REG_JSTAT` polls, SVC `0x26` BIOS reset on
-`JOYCNT.RST`) is taken verbatim from **Doridian's
+The joybus handshake + main loop in `source/main.c` and
+`source/main_tester.c` (the `0x30303030` exchange, status-bit polls,
+SVC `0x26` BIOS reset on `JOYCNT.RST`) is taken from **Doridian's
 [Joybus-PIO](https://github.com/Doridian/Joybus-PIO)** `gba/source/main.c`
 (2023). That sequence is load-bearing for the cable's level-shifter MCU;
-modifying it breaks the host's view of input. The animated-eyes overlay
-runs in the VBlank slot on top of it.
+modifying it breaks the host's view of input. The eyes overlay and the
+tester console run on top of it.
 
 Chain of credit:
 
 - **[gbatek](https://problemkaputt.de/gbatek.htm)** (Martin Korth) —
-  authoritative GBA hardware reference (SIO / Joybus / BIOS reset semantics)
-- **[libgbacom](https://github.com/Sage-of-Mirrors/libgbacom)** (Sage-of-Mirrors,
-  ported from VisualBoyAdvance) — original reverse-engineering of the
-  joyboot stream cipher
+  authoritative GBA hardware reference (SIO / Joybus / BIOS reset
+  semantics)
+- **[libgbacom](https://github.com/Sage-of-Mirrors/libgbacom)**
+  (Sage-of-Mirrors, ported from VisualBoyAdvance) — original
+  reverse-engineering of the joyboot stream cipher
 - **[gc-gba-link-cable-demo](https://github.com/FIX94/gc-gba-link-cable-demo)**
   (FIX94) — canonical GameCube-side reference for booting a GBA over the
   link cable
 - **[Joybus-PIO](https://github.com/Doridian/Joybus-PIO)** (Doridian) —
   RP2040-PIO implementation of the GameCube side, plus the GBA-side
-  controller payload this repo forks
-- **This repo** — animated-eyes overlay (port of joypad-os's `eyes_anim`),
-  per-emotion FG/pupil palette, dpad-as-self-centering-analog gaze,
-  ACTIVE → wander → sleep cycle
+  controller payload these variants build on
+- **This subtree** — eyes overlay (port of joypad-os's `eyes_anim`),
+  Mode-4 page-flipped screensaver matching the joypad-tester GC
+  variant's logo + colour cycle, two-build Makefile, robust joybus
+  reset handling (polls `JOYCNT.RST` inside the VBlank busy-wait so
+  host cmd 0xFF triggers `SystemCall(0x26)` within microseconds)
 
 ## Embedding
 
-Drop `build/joypad_payload.c` into your host firmware's source list. It
-exports:
-
-```c
-extern const uint8_t  joypad_payload[];
-extern const uint32_t joypad_payload_len;
-```
-
-Then feed those bytes to your joybus multiboot uploader. See
+Drop the appropriate `build/<variant>/<variant>_payload.c` into your
+host firmware's source list, then feed `joypad_payload[]` /
+`joypad_payload_len` to your joybus multiboot uploader. See
 [joypad-os](https://github.com/joypad-ai/joypad-os)'s
-`src/native/host/gc/gba_multiboot.c` for a reference uploader implementation
-(Kawasedo handshake, stream cipher, polled WRITE/READ).
+`src/native/host/gc/gba_multiboot.c` or this repo's
+[`../gamecube/ppc/gba.c`](../gamecube/ppc/gba.c) for reference uploader
+implementations (Kawasedo handshake, stream cipher, polled WRITE/READ,
+unconditional handshake-complete write).
 
 ## Building (only if you change source)
 
@@ -70,36 +89,38 @@ sudo dkp-pacman -S gba-dev
 # https://devkitpro.org/wiki/devkitPro_pacman
 
 export DEVKITPRO=/opt/devkitpro
-make
-```
-
-Outputs:
 
-```
-build/joypad_mb.gba       # multiboot ROM
-build/joypad_payload.c    # same bytes as a C array
+make            # build both variants
+make joypad     # build only the eyes ROM
+make tester     # build only the tester ROM
+make clean      # nuke build/
 ```
 
-Both are committed in this repo; rebuild and commit them whenever you change
-the source.
+Outputs land in `build/joypad/` and `build/tester/`. Both `*_mb.gba`
+and `*_payload.c` are committed; rebuild and commit them whenever you
+change source.
 
 ## Layout
 
 ```
 .
-├── Makefile             # devkitARM build → build/joypad_mb.gba + .c
+├── Makefile                       # two-variant build → build/<variant>/
 ├── source/
-│   ├── main.c           # entry point, IRQ wiring, joybus handshake (Doridian)
-│   ├── display.c/.h     # Mode-4 framebuffer + DMA present
-│   ├── eyes_anim.c/.h   # cylinder-eye renderer + emotion state machine
+│   ├── main.c                     # eyes variant entry (joybus + eyes_anim)
+│   ├── main_tester.c              # tester variant entry (joybus + console
+│   │                              # + Mode-4 page-flipped screensaver)
+│   ├── display.c/.h               # Mode-4 framebuffer for the eyes variant
+│   ├── eyes_anim.c/.h             # cylinder-eye renderer + emotion state
+│   │                              # machine
 │   └── platform/
-│       └── platform.h   # stub for shared eyes_anim platform API
+│       └── platform.h             # stub for shared eyes_anim platform API
 ├── tools/
-│   └── bin2c.py         # binary .gba → C array converter
-└── build/               # committed pre-built payload artifacts
-    ├── joypad_mb.gba
-    └── joypad_payload.c
+│   └── bin2c.py                   # binary .gba → C array converter
+└── build/                         # committed pre-built payload artifacts
+    ├── joypad/
+    │   ├── joypad_mb.gba
+    │   └── joypad_payload.c
+    └── tester/
+        ├── tester_mb.gba
+        └── tester_payload.c
 ```
-
-The flat layout (no `gba/` subdir like Doridian's repo, since this whole
-repo *is* the GBA payload) keeps embedding paths short.