# Integrated CPU/SRAM timing test

Run `python3 tests/run_cpu_sram_integration.py` from the repository. Add
`--log build/cpu-sram-integration.log` for source hashes, parameters and full
results, or `--verbose` to print each case. The runner tests a frozen source
copy and rejects source changes made during the run.

This connects the real CPU bridge, Gary, bank mapper and SRAM bridge. The
chipset clocks use the production Q0/Q1/Q2/Q3 relationship. The CPU model
launches address, address strobe, write data and byte strobes in separate
68000 bus states, samples DTACK on falling edges, and samples read data one
CPU period after recognizing DTACK. Tests include word/byte writes, uncached
reads, ROM misses and explicitly checked subsequent cache hits.

The default SRAM model uses 30 ns access time, 10 ns address/control delay,
10 ns return delay and 2 ns output disable. These are declared test inputs,
not measured board specifications. The runner sweeps CPU clock phase and
external clock delay, including the routed 4.418 ns CPU/cache relative clock
offset reported during this investigation. Additional cases use 33 ns CPU
write-data path delay and 40 ns SRAM return delay (80 ns total modeled read
latency). DMA cases alternate reads/writes while stealing one in three
chipset slots; slow mode preserves the following CPU slot after an accepted
transfer. Slow-mode cases use the production inverted chipset clock.

The 137 cases contain 39,456 CPU transfers. They assert that turbo writes and read misses
acknowledge at Q3, SRAM writes still capture data at Q2, and the CPU cannot acknowledge
while DMA owns the memory bus. Both read data and hit/miss classification
are checked at CPU acceptance, allowing the registered cache lookup to
settle normally.

The CPU model requires 5 ns DTACK/read-data setup and waits another cycle
when DTACK arrives too late. It includes 5 ns DTACK output delay and 3 ns
clock-to-AS/DS release. The setup and minimum release values come from the
[MC68SEC000 addendum](https://www.nxp.com/docs/en/reference-manual/M68000UMAD.pdf),
tables on PDF pages 12–13. They describe the rated 10/16/20 MHz part and do
not establish its electrical behavior at 60 MHz. Write-data hold after
AS/DS release defaults to zero to stress the FPGA's Q2 data capture.

All delays, setup requirements and clock offsets are testbench parameters.
`TRACE=1` prints the first ROM word's cache-fill events. Setting
`WRITE_TESTS=0` isolates reads; `CHECK_HITS=0` retains data checks while
allowing a miss where a hit was expected.

An independent comparison changed only the turbo read-acknowledgement phase
in frozen `5016887` RTL. With 80 ns modeled read latency, Q2 failed 26 of 45
phase/clock-offset cases without DMA and 21 of 45 with DMA. Q3 passed all 90.
At the nominal 50 ns latency both variants passed all 90 cases. The Q2 SRAM
write-data capture always preceded CPU write-data release in these tests;
R2 moved read acknowledgement without changing that write edge or CPU clock.
R3 also moves write acknowledgement to Q3 to cover custom-register capture
and retires completed slots locally; see README.cpu-bus-retirement.txt.
This demonstrates additional read margin, not the measured cause of the
reported hardware red screen.

This is a behavioral timing-budget test. It does not model routed logic
delays, metastability, CPU internal timing variation, PCB loading or the
complete bidirectional pad electrical path. Routed timing analysis and
hardware measurements remain separate evidence.
