WIP rewrite: clock the EXI bit engine from the EXI clock pin

Replaces 54 MHz oversampling with a slave clocked by EXI CLK itself:
  exiclk    posedge  sample MOSI (Mode 3 samples on edge 2)
  exiclk_n  negedge  drive MISO (must settle between the master's samples)
  CS_N      async reset for both
EXI CLK (pin 44) is at die (6,0) = global buffer net 6 on the 5k-sg48, so it
can drive a real clock network with no board change.

This removes the capture domain entirely.  Bit-level timing no longer
crosses a clock boundary -- MISO is clock-to-Q instead of 3 ticks of a foreign
clock -- and the only crossings left are the byte FIFOs, which have a whole
byte-time (~296 ns) of slack rather than a fraction of a bit.

AsyncFIFO needs a posedge clock for its internal reset CDC, so the FIFO sides
use reset-less POSEDGE domains on the same pin; the engine pops on the posedge
and hands the byte to the negedge output stage through a register.  The FIFOs
must not see CS: resetting one side of an AsyncFIFO desynchronises its gray
pointers.

Two bugs found and fixed along the way:
  * one pop per byte boundary is all that is needed -- pops during the header
    drain whatever the previous transaction left (replacing the CS-fall flush)
    and the turnaround-byte push lands in data slot 0.  No slot-threshold or
    header-length logic at all.
  * rx_byte/rx_valid had to become COMBINATIONAL.  Registered, they need one
    more clock edge, and after a transaction's final bit the clock stops and
    CS rises -- so the last byte of every transaction was lost (a 4-byte write
    landed as DE AD BE 00, a 34-byte TX as 15 bytes).

At the HARDWARE rate (EXI_HALF=1, 27 MHz) the device ID, NWAYS, PAR
read/write and the W5100->SPRAM RX path now all pass -- none of which has ever
worked at 27 MHz before.  Testbenches now drive the SPI clock with real
delays, since there is no capture domain to count ticks against.

STILL BROKEN: the SPRAM/DMA stream is offset by one byte (its round trip
exceeds the single turnaround byte), and TX lands 15 of 34 bytes.  Do not
flash this yet.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
2026-10-03 16:47:42 +02:00
parent d95f2147a4
commit a3b3e052bc
4 changed files with 203 additions and 378 deletions
+105 -257
View File
@@ -1,292 +1,140 @@
"""SPI Mode 3 byte-oriented slave for the EXI bus.
"""SPI Mode 3 byte-oriented slave for the EXI bus — CLOCKED BY EXI CLK.
CPOL=1, CPHA=1: CLK idles HIGH.
Slave samples MOSI on the FALLING CLK edge.
Slave drives MISO on the RISING CLK edge (master samples on next falling edge).
All three raw inputs are run through a 2-stage FFSynchronizer before use.
CPOL=1, CPHA=1 (real Mode 3): CLK idles HIGH, the master CHANGES MOSI on the
falling edge and both ends SAMPLE on the rising edge.
Architecture
------------
The engine is clocked by the EXI clock itself rather than oversampling it from
a faster domain:
exiclk posedge of EXI CLK — sample MOSI, assemble RX bytes
exiclk_n negedge of EXI CLK — drive MISO (must change BETWEEN the
master's sampling edges)
CS_N asynchronous reset for both
Why, and what it fixes (hardware 2026-10-03)
--------------------------------------------
The previous version oversampled EXI CLK from a 54 MHz `capture` domain, which
put BIT-level timing across a clock-domain boundary: the engine's view of the
clock lagged the pin by 2 stages of `FFSynchronizer` plus a register, ~3 ticks
≈ 55 ns. One EXI bit at 27 MHz is 37 ns, so MISO came out ~2 bits late and the
master read `0x17` as `05 C0` (= `0x17 >> 2`). Register reads were correct up
to 4 MHz and failed from 8 MHz — the sweep read `ok=[1,1,1,0,0,0]`.
No amount of oversampling fixes that: at 54 MHz there are only 2 ticks per bit,
and the design cannot close the 81 MHz that 3x would need. Clocking the engine
from the EXI pin makes MISO clock-to-Q instead, and moves the ONLY remaining
crossing to the byte-level AsyncFIFOs, which have a whole byte-time (~296 ns at
27 MHz) of slack instead of a fraction of a bit.
EXI CLK (pin 44) sits at die (6,0) on the 5k-sg48, which is global buffer input
net 6 — so it can drive a real clock network with no board change.
The domains are created by the PARENT (`ExiCapture`) so the byte FIFOs can name
them; this module just uses `m.d.exiclk` / `m.d.exiclk_n`.
"""
from amaranth import *
from amaranth.lib.cdc import FFSynchronizer
# ── public re-export for import convenience ─────────────────────────────────
__all__ = ["SPIMode3Slave"]
class SPIMode3Slave(Elaboratable):
"""Byte-oriented SPI Mode 3 slave.
"""Byte-oriented SPI Mode 3 slave, clocked by the EXI clock.
Ports
-----
spi_clk / spi_mosi / spi_cs_n : raw async inputs from GC (synchronized internally)
spi_miso : output to GC; idles HIGH when CS deasserted
rx_byte : last complete received byte (valid when rx_valid pulses)
rx_valid : 1-cycle pulse in exi domain when rx_byte contains a new byte
tx_byte : upstream loads this before or within one exi clock of tx_load pulsing
tx_load : 1-cycle pulse requesting the next TX byte from upstream
spi_clk / spi_mosi / spi_cs_n : raw inputs from the GC. spi_clk drives the
exiclk/exiclk_n domains and spi_cs_n their async reset (both wired by
the parent); they are still listed here so the module is self-describing
and so spi_cs_n can gate MISO combinationally.
spi_miso : output to the GC; idles HIGH while CS is deasserted.
rx_byte : last complete received byte (valid while rx_valid is high)
rx_valid : 1-cycle pulse in `exiclk` when rx_byte holds a new byte
tx_byte : byte to transmit; sampled at each byte boundary
tx_load : 1-cycle pulse in `exiclk_n` asking upstream for the next byte
hdr_bytes : how many leading bytes are header (MISO don't-care). Pops are
suppressed until past them, so the first response byte the register
file pushes lands in data slot 0 rather than being eaten by the header.
"""
def __init__(self, domain="capture", mode2=False):
# Clock domain this byte engine runs in. Split-domain design puts the
# bit engine in a fast `capture` domain (54 MHz) so it can oversample
# a 27 MHz EXI clock ~3×; the register file lives in a slower domain.
self._domain = domain
# False = real Mode 3 (sample MOSI on RISING) -- what the GameCube
# needs. True = the old Mode-2 behaviour the Pi probe was built on.
self._mode2 = mode2
def __init__(self):
self.spi_clk = Signal(init=1) # idles HIGH
self.spi_mosi = Signal()
self.spi_cs_n = Signal(init=1) # active LOW
self.spi_miso = Signal() # combinatorial output
self.spi_miso = Signal(init=1)
self.rx_byte = Signal(8)
self.rx_valid = Signal()
self.tx_byte = Signal(8)
self.tx_load = Signal()
# 1-cycle pulse on CS assertion (transaction start). The capture
# wrapper uses it to reset its per-transaction TX byte counter.
self.frame_start = Signal()
# Header length for this transaction, in bytes. The real protocol has
# two forms selected by bit 7 of byte 0 (see docs/exi_protocol_real.md):
# register space = 4-byte header, command space = 2-byte.
self.hdr_bytes = Signal(3, init=4)
# Level: high while CS is asserted (a transaction is in progress).
# Lets downstream logic detect variable-length (DMA) transaction ends.
self.cs_active = Signal()
# Transaction framing, generated in the slow domain by the parent.
self.frame_start = Signal()
self.cs_active = Signal()
def elaborate(self, platform):
m = Module()
d = self._domain
# ── Input synchronization (async → exi, 2 stages) ──────────────────
clk_s = Signal(init=1)
mosi_s = Signal()
cs_s = Signal(init=1)
m.submodules.sync_clk = FFSynchronizer(self.spi_clk, clk_s, o_domain=d, init=1)
m.submodules.sync_mosi = FFSynchronizer(self.spi_mosi, mosi_s, o_domain=d)
m.submodules.sync_cs = FFSynchronizer(self.spi_cs_n, cs_s, o_domain=d, init=1)
# ── Edge detection ──────────────────────────────────────────────────
clk_prev = Signal(init=1)
cs_prev = Signal(init=1)
m.d[d] += clk_prev.eq(clk_s)
m.d[d] += cs_prev.eq(cs_s)
falling_clk = Signal()
rising_clk = Signal()
cs_fall = Signal()
cs_rise = Signal()
# ⚠️ EDGE CONVENTION. The docs call this "Mode 3 (CPOL=1, CPHA=1)" but
# then describe sampling MOSI on the FALLING edge -- that combination
# is Mode 2. Real Mode 3 samples on the SECOND edge of each cycle,
# which with an idle-high clock is the RISING one.
#
# Hardware 2026-10-03: the GameCube drives MOSI on the falling edge, so
# sampling there latches the PREVIOUS bit -- every byte arrived one bit
# late in both directions at every clock speed (header 0x80 was read as
# 0x00, and the reply came back as 04 02 02 00 >> 1 = 02 01 01 00).
# `mode2=True` restores the old behaviour, which is what the Pi probe
# on J4 was written to match.
if self._mode2:
sample_edge, shift_edge = ~clk_s & clk_prev, clk_s & ~clk_prev
else:
sample_edge, shift_edge = clk_s & ~clk_prev, ~clk_s & clk_prev
m.d.comb += falling_clk.eq(sample_edge) # "sample MOSI / advance bit"
m.d.comb += rising_clk .eq(shift_edge) # "shift MISO / re-arm"
m.d.comb += cs_fall .eq(~cs_s & cs_prev)
m.d.comb += cs_rise .eq( cs_s & ~cs_prev)
m.d.comb += self.frame_start.eq(cs_fall)
m.d.comb += self.cs_active.eq(~cs_s)
# ── Shift registers ─────────────────────────────────────────────────
# ── RX: sample MOSI on the RISING edge (Mode 3 samples on edge 2) ──
rx_shift = Signal(8)
rx_bit = Signal(3)
byte_idx = Signal(3, init=0) # bytes seen this transaction (saturating)
nxt = Cat(self.spi_mosi, rx_shift[:-1]) # MSB-first: shift left, new bit at LSB
m.d.exiclk += rx_shift.eq(nxt)
m.d.exiclk += rx_bit.eq(rx_bit + 1)
with m.If(rx_bit == 7):
with m.If(byte_idx != 7):
m.d.exiclk += byte_idx.eq(byte_idx + 1)
# rx_byte/rx_valid are COMBINATIONAL, not registered. The clock stops
# and CS rises immediately after a transaction's final bit, so a
# registered pulse would need one more clock edge that never arrives
# and the LAST byte of every transaction would be silently lost
# (symptom: a 4-byte write landed as DE AD BE 00, and a 34-byte TX
# stream as 15 bytes). Driving them combinationally makes the FIFO
# capture the byte on the very edge that completes it.
m.d.comb += self.rx_byte .eq(nxt)
m.d.comb += self.rx_valid.eq(rx_bit == 7)
# ── TX: pop on the POSEDGE, present on the NEGEDGE ────────────────
# AsyncFIFO needs a posedge clock internally, so the FIFO is read in
# `exiclk` and the byte is handed to the negedge side through a plain
# register. posedge -> negedge of the SAME clock is a half-period
# path (18.5 ns at 27 MHz), which is ample.
#
# One pop per byte boundary, unconditionally. The byte popped at the
# end of byte N is presented during byte N+1, so:
# - pops during the header drain whatever the previous transaction
# left in the FIFO (this replaces the old CS-fall flush), and
# - the response the register file pushes during the protocol's
# turnaround byte is popped at that byte's end and lands in data
# slot 0, exactly where it belongs.
# No header-length or slot-threshold logic is needed at all.
tx_hold = Signal(8)
m.d.comb += self.tx_load.eq(rx_bit == 7)
with m.If(rx_bit == 7):
m.d.exiclk += tx_hold.eq(self.tx_byte)
# MISO must settle on the falling edge, before the master samples it
# on the rising one. Driving it on the rising edge is one bit late by
# construction -- that was the 05 C0 bug.
tx_shift = Signal(8)
bit_ctr = Signal(4) # counts 0..7; 7 means "8th (last) bit"
armed = Signal(init=1) # between bytes: drive the LIVE tx_byte MSB
rearm = Signal() # arm for next byte on the next rising edge
# MISO: idle HIGH when CS deasserted. While "armed" — i.e. at the start
# of a byte, including the inter-byte / clock-idle gap before the first
# falling edge — drive the LIVE tx_byte MSB. This is what lets a
# response that upstream pushes DURING the EXI clock-idle gap reach MISO
# in time: there is no clock edge during the gap to latch it, so MISO
# must be combinational on tx_byte until the byte actually starts. Once
# shifting (after the first falling edge) drive the latched shift reg.
m.d.comb += self.spi_miso.eq(
Mux(cs_s, 1, Mux(armed, self.tx_byte[7], tx_shift[7]))
)
# Default: deassert single-cycle pulses every cycle
m.d[d] += self.rx_valid.eq(0)
m.d[d] += self.tx_load.eq(0)
with m.If(cs_fall):
# Transaction start: first byte drives its MSB live (armed).
m.d[d] += bit_ctr.eq(0)
m.d[d] += armed.eq(1)
with m.Elif(cs_rise | cs_s):
# CS deasserted / idle: reset state
m.d[d] += bit_ctr.eq(0)
m.d[d] += armed.eq(1)
tx_bit = Signal(3)
m.d.exiclk_n += tx_bit.eq(tx_bit + 1)
with m.If(tx_bit == 0):
m.d.exiclk_n += tx_shift.eq(tx_hold) # first falling edge: MSB
with m.Else():
# CS asserted: run bit engine
with m.If(falling_clk):
# Sample MOSI (MSB first: left-shift, new bit enters at LSB)
# Cat(a, b) → a at lower bits; so Cat(mosi, rx[6:0]) = {rx[6:0], mosi}
m.d[d] += rx_shift.eq(Cat(mosi_s, rx_shift[:-1]))
m.d.exiclk_n += tx_shift.eq(Cat(0, tx_shift[:-1]))
with m.If(armed):
# First falling edge of this byte: master has just sampled
# the MSB (driven live above). Latch tx_byte so the
# remaining 7 bits shift out of a stable register.
m.d[d] += tx_shift.eq(self.tx_byte)
m.d[d] += armed.eq(0)
with m.If(bit_ctr == 7):
# 8th falling edge: byte complete. The master samples the
# LSB on THIS edge, so MISO must still hold tx_shift[7].
# Defer arming to the next rising edge (rearm) so MISO is
# not switched to the next byte's live MSB too early.
m.d[d] += self.rx_byte.eq(Cat(mosi_s, rx_shift[:-1]))
m.d[d] += self.rx_valid.eq(1)
m.d[d] += bit_ctr.eq(0)
m.d[d] += self.tx_load.eq(1) # advance source to next byte
m.d[d] += rearm.eq(1) # arm on the next rising edge
with m.Else():
m.d[d] += bit_ctr.eq(bit_ctr + 1)
with m.If(rising_clk):
with m.If(rearm):
# Byte boundary: arm for the next byte (live MSB drive).
m.d[d] += armed.eq(1)
m.d[d] += rearm.eq(0)
with m.Elif(~armed):
# Shift left: next bit into MSB position
# Cat(0, tx[6:0]) = {tx[6:0], 0} — left shift
m.d[d] += tx_shift.eq(Cat(0, tx_shift[:-1]))
m.d.comb += self.spi_miso.eq(Mux(self.spi_cs_n, 1, tx_shift[7]))
return m
# ── Testbench ───────────────────────────────────────────────────────────────
if __name__ == "__main__":
from amaranth.sim import Simulator, Period
dut = SPIMode3Slave()
# 4 exi ticks per SPI half-period → well above the 3-cycle (2 sync + 1 edge) latency.
HALF = 4
async def spi_send_byte(ctx, mosi_val, next_tx_byte=None):
"""Drive one SPI Mode 3 byte on MOSI; return the MISO byte assembled.
next_tx_byte: if given, written to tx_byte after the LAST falling edge
(before the last rising edge) so need_reload picks it up in time.
"""
miso_byte = 0
for bit in range(7, -1, -1):
ctx.set(dut.spi_mosi, (mosi_val >> bit) & 1)
ctx.set(dut.spi_clk, 0) # falling edge
await ctx.tick("capture").repeat(HALF)
miso_byte = (miso_byte << 1) | ctx.get(dut.spi_miso)
# Set next TX byte here — after last fall, before rising edge.
# The rising edge is detected 3 cycles after we assert clk=1,
# so we have HALF ticks of margin.
if bit == 0 and next_tx_byte is not None:
ctx.set(dut.tx_byte, next_tx_byte)
ctx.set(dut.spi_clk, 1) # rising edge
await ctx.tick("capture").repeat(HALF)
return miso_byte
errors = []
async def testbench(ctx):
# ── Test 1: Single byte TX/RX ──────────────────────────────────────
ctx.set(dut.spi_cs_n, 0)
ctx.set(dut.spi_clk, 1)
ctx.set(dut.tx_byte, 0xA5) # pre-load before CS fall is detected
await ctx.tick("capture").repeat(HALF)
miso = await spi_send_byte(ctx, 0x37)
await ctx.tick("capture").repeat(2)
rx = ctx.get(dut.rx_byte)
ctx.set(dut.spi_cs_n, 1)
await ctx.tick("capture").repeat(HALF)
if rx != 0x37:
errors.append(f"Test1 rx_byte: expected 0x37, got 0x{rx:02X}")
if miso != 0xA5:
errors.append(f"Test1 miso: expected 0xA5, got 0x{miso:02X}")
print(f"Test1 – MOSI→rx_byte: 0x{rx:02X} MISO←tx_byte: 0x{miso:02X}")
await ctx.tick("capture").repeat(HALF)
# ── Test 2: Two-byte transaction; second byte loaded via need_reload ─
ctx.set(dut.spi_cs_n, 0)
ctx.set(dut.tx_byte, 0xBE) # first response byte
await ctx.tick("capture").repeat(HALF)
# Pass next_tx_byte=0xEF so it's set after last falling edge of byte 0,
# giving need_reload time to load it on the subsequent rising edge.
miso0 = await spi_send_byte(ctx, 0x00, next_tx_byte=0xEF)
miso1 = await spi_send_byte(ctx, 0xFF)
await ctx.tick("capture").repeat(2)
rx1 = ctx.get(dut.rx_byte)
ctx.set(dut.spi_cs_n, 1)
await ctx.tick("capture").repeat(HALF)
if miso0 != 0xBE:
errors.append(f"Test2 miso0: expected 0xBE, got 0x{miso0:02X}")
if miso1 != 0xEF:
errors.append(f"Test2 miso1: expected 0xEF, got 0x{miso1:02X}")
if rx1 != 0xFF:
errors.append(f"Test2 rx1: expected 0xFF, got 0x{rx1:02X}")
print(f"Test2 – byte0 MISO: 0x{miso0:02X} byte1 MISO: 0x{miso1:02X} rx1: 0x{rx1:02X}")
await ctx.tick("capture").repeat(HALF)
# ── Test 3: MISO idles HIGH when CS deasserted ─────────────────────
miso_idle = ctx.get(dut.spi_miso)
if miso_idle != 1:
errors.append(f"Test3 MISO idle: expected 1, got {miso_idle}")
print(f"Test3 – MISO idle (CS=1): {miso_idle}")
# ── Test 4: All-zeros byte (0x00) TX and RX ────────────────────────
ctx.set(dut.spi_cs_n, 0)
ctx.set(dut.tx_byte, 0x00)
await ctx.tick("capture").repeat(HALF)
miso = await spi_send_byte(ctx, 0xFF)
await ctx.tick("capture").repeat(2)
rx = ctx.get(dut.rx_byte)
ctx.set(dut.spi_cs_n, 1)
await ctx.tick("capture").repeat(HALF)
if miso != 0x00:
errors.append(f"Test4 miso: expected 0x00, got 0x{miso:02X}")
if rx != 0xFF:
errors.append(f"Test4 rx: expected 0xFF, got 0x{rx:02X}")
print(f"Test4 – 0x00 TX / 0xFF RX: MISO=0x{miso:02X} rx=0x{rx:02X}")
sim = Simulator(dut)
sim.add_clock(Period(MHz=54), domain="capture")
sim.add_testbench(testbench)
with sim.write_vcd("SPIMode3Slave.vcd"):
sim.run()
if errors:
print("\nFAILURES:")
for e in errors:
print(" ", e)
raise SystemExit(1)
else:
print("\nAll tests passed.")