cart-reader-1.0

A cartridge reader built into the console's normal gateware, so the Chromatic
still boots and plays games. Open the USB serial port at the magic rate and it
hands over the cart bus; disconnect and it hands it back. No reflashing, no
button combo, no power cycle.

Based on fredemmott's cart reader, riding on top of the UVC/dual-resolution
release. This is the gateware fgbweb
loads for you automatically.

Which file do I want?

The .fs. It loads into the FPGA's SRAM and is gone the moment you power
off, so there's nothing to undo. That's what fgbweb uses.

Take the .flash only if you specifically want this to be your console's
flashed firmware. It's a full 1 MB config flash image: it survives power-off
and can brick the console until you reflash it. Write the whole .flash image, never
just the bitstream — a partial write leaves stale metadata behind.

Verify it

sha256sum -c SHA256SUMS
python esp32t/tools/pack.py verify --image chromatic-cart-reader-1.0.flash

On the device, fpgaflash verify should report bitstream_crc32 = 0x149ba7ce.

Tested on hardware

• Boots and plays a game with the reader built in
• Dumps Zelda: Oracle of Ages at CRC32 3800A387 — matches the
  known-good image
• Works through both openFPGALoader and fgbweb's WebUSB loader
• Takes the cart bus and gives it back cleanly, over repeated sessions

Built with gw_sh 1.9.12.03. All clocks meet timing. It's a tight fit — 95% of
CLS, 639 to spare, so there isn't much room left for anything else. That makes loading this on demand over SRAM when needed a good way to go.

Known issue

cart_audio powers up asserted and stays that way until the first AUDIO write.
Upstream that's harmless because the game core isn't there; here it is, so the
pin sits low while a game runs. Almost no cartridges use audio-in and we haven't
seen a problem, but check this first if a game acts up.

AUDIO-as-write-enable is wired but untested. The ModRetro cartridge uses WR.

Where it came from

Commit 78fdc9ae, on top of v18.8-uvc-dualres.2 (29fa647). The bitstream
writes 0x78fdc9ae into USERCODE, so a running console can tell you which
commit it's from.

Heads up: openFPGALoader reads USERCODE back wrong on this chip. On GW5A,
JTAG instruction 0x0a is WRITE_USERCODE, not the checksum register, so its
checksum step overwrites the value. You'll see the bitstream's checksum instead
of the commit. That's a bug in the tool, not in this file.

GPL-3.0, same as the base.