rebbarb/docs/exi_protocol_real.md

The real GC↔BBA EXI protocol (verified 2026-10-03)

Read directly from the two drivers that will actually talk to this device:

• libogc — libdb/uIP/bba.c (devkitPro/libogc)
• Swiss — cube/patches/bba/bba.c (emukidid/swiss-gc)

Swiss is the one that matters; it pokes the EXI hardware registers directly rather than going through libogc's EXI API.

Two address spaces, selected by bit 7 of byte 0

COMMAND space — 6-bit register, ONE 4-byte read/write transfer
    read   [  reg&0x3F, 00, 00, xx ]   response is byte 3
    write  [0x40|reg&0x3F, 00, 00, data]

REGISTER space — 16-bit register, 4-byte header THEN a separate data phase
    read   [0x80, reg>>8, reg&0xFF, 0x00]  + N bytes read
    write  [0xC0, reg>>8, reg&0xFF, 0x00]  + N bytes written

byte 0 bit 7 = register space, bit 6 = write.

Swiss source:

uint8_t bba_cmd_in8(uint8_t reg)
    { return exi_imm_read_write((reg & 0x3F) << 24, 4); }
void    bba_cmd_out8(uint8_t reg, uint8_t val)
    { exi_imm_read_write(0x40 << 24 | (reg & 0x3F) << 24 | val, 4); }

uint8_t bba_in8(uint16_t reg)
    { exi_imm_read_write(0x80 << 24 | reg << 8, 4); return exi_imm_read(1); }
void    bba_out8(uint16_t reg, uint8_t val)
    { exi_imm_read_write(0xC0 << 24 | reg << 8, 4); exi_imm_write(val << 24, 1); }

void bba_ins(uint16_t reg, void *val, uint32_t len)
    { exi_imm_read_write(0x80 << 24 | reg << 8, 4); exi_dma_read(val, len, false); }

All the BBA registers this project cares about — NCRA (0x00), IR (0x09), RWP (0x16), RRP (0x18), PAR (0x20), NWAYS (0x31) — are accessed through bba_in8/bba_out8/bba_ins/bba_outs, i.e. the register space.

Three consequences for the gateware

1. There is no length field. The data phase runs for as long as the GC clocks it, ending at CS. The register path must stream until CS exactly as the SPRAM path (≥0x100) already does. The current 2-bit length field caps register reads at 4 bytes, which is wrong — bba_ins reads arbitrary lengths, and with DMA.

2. The trailing 0x00 byte is the prefetch window. The address is complete after byte 2 of a 4-byte header, leaving one whole byte — ~8 bit-times, ≈296 ns at 27 MHz — before the data phase starts. The command space is even more generous: the register is known after byte 0, giving ~24 bit-times before the response is needed in byte 3. The protocol was designed to give the device time to fetch.

3. EXI DMA reads are used. bba_ins does exi_dma_read. DMA reads are fine; it is the GC's DMA-write engine that has the 1-bit-shift bug Swiss avoids.

Why the current implementation is not just wrong but dangerous

exi_bba/bba_register_file.py implements a 2-byte header with the address split across both bytes and a 2-bit length in the low bits of byte 1. Feeding it Swiss's traffic:

Swiss intends	sends	current decoder sees
read NWAYS (0x31)	80 00 31 00	write 0x31 to NCRA — bit 0 = RESET
read IR (0x09)	80 00 09 00	write 0x09 to NCRA — bit 0 = RESET
write NCRA	C0 00 00 00	write 0x00 to addr 0x1000

Every register read Swiss performs would reset the device.

The device-ID query is the sole case where the two formats agree (00 00 decodes to address 0 either way), which is why enumeration worked on hardware while nothing else could have.

Relationship to the response-latency problem

First on-console run (2026-10-03, EXI index 5) returned the device ID 22 bit-times late — 00 00 00 10 is a bit-exact match for 04 02 02 00 shifted by 22. ~815 ns, which is about what the CDC chain costs (rx AsyncFIFO capture→exi, register-file FSM decode, tx AsyncFIFO exi→capture, SPI engine) at a 24 MHz exi clock.

The design doc demands data "ready on MISO from the very first clock edge of the data phase". That looked impossible until the real format turned up: the protocol hands the device a turnaround byte, and the current header format spends it on a length field. Adopting the real format therefore does double duty — it is required for compatibility anyway, and it recovers ~296 ns (register space) or ~593 ns (command space) of the ~815 ns deficit.

The remainder still needs latency work: the lightweight ping-pong TX CDC (already documented as the capture-timing lever), FSM trimming before the first push, and possibly serving hot registers from a capture-domain shadow so the response path crosses no clock domain at all.