# CPU WaitBlit and final-write overlap test

Run from the repository:

```sh
python3 tests/blitter/run_waitblit.py --log build/waitblit-bus-audit.log
```

This test connects the actual CPU bridge, Gary, Agnus, Blitter, bank mapper
and SRAM bridge. The CPU polls DMACONR until busy clears, then immediately
writes the destination pointer and blit control register. It uses real
Q0–Q3 phases and the CPU `bls` starvation signal. SRAM writes are checked at
physical write-strobe termination, including destination guard words.

The 16 uncontended current-RTL cases cover normal/turbo CPU clocks, Blitter priority
on/off, word and upper-byte busy polling, and three turbo clock phases.
Each runs 96 masked-copy, constant-fill and cookie-cut jobs, with widths
1–4 words and heights 1–3 rows. Polling starts at several alignments after
BLTSIZE. A dummy DMACONR read precedes tight polling; there are no extra
CIA reads or software instruction delays between bus transactions.

Twelve additional turbo cases inject 1/4/8-slot higher-priority bitplane DMA
bursts when the Blitter enters its final write state. The model changes only
the request, fetch address and target-register signals at chipset Q0; the
real Agnus priority mux and CPU starvation counter arbitrate the requests.
It represents controlled contention rather than a complete display fetch
trace. Each job must receive one burst, finish every physical write, signal
exactly one interrupt, and remain idle afterward.

Three additional cases substitute only `Blitter.v` from `a8c27a1`. They keep
the current CPU and SRAM interfaces, so this comparison isolates Blitter
changes and does not represent a complete original-core simulation.
The runner also substitutes R3's `f500976` Blitter while retaining the same
CPU and SRAM interfaces. This negative control must reproduce a destination
pointer update during the pending final write and actual wrong SRAM data.
It bypasses only the new completion-policy assertions, so an assertion that
merely notices the old busy timing cannot count as reproducing corruption.
A second negative control deliberately omits WaitBlit and must likewise
produce lost writes or wrong physical memory data. Neither control identifies
any particular game's instruction sequence.

The 31 passing cases contain 2,976 blits, including the three original-Blitter
controls. Current RTL must keep busy set through the final pending write,
produce no early-idle CPU observations, and complete with exactly one IRQ.
The original-Blitter controls check data while allowing their original busy
timing. The R3 burst failure shows why relying on arbitration alone to flush
the last word before a fast CPU's next register update is insufficient.

The new completion policy deliberately delays area-D busy clear and IRQ
until the last DMA write is granted. The original hardware's early-completion
behavior is a documented compatibility detail. Separate tests in
`tests/datapath/tb_blitter_equivalence.v` retain exact original line/no-D
status timing and address/data comparisons, explicitly stall the final
write by disabling DMA and its clock-enable slot, and check one IRQ/job
without spontaneous restarts. The bitmap golden test retains its independent
memory reference and chained-blit checks.

The CPU model requires 5 ns stable DTACK, then one full CPU period before
completion and another 3 ns before releasing AS/data strobes. It uses
4.4 ns external CPU clock delay, 5.7 ns DTACK output delay, 6 ns CPU write
propagation, and 10/30/10 ns SRAM pin/access/return delays. These are explicit
behavioral timing inputs. Internal routed delays, metastability, PCB loading,
and the CPU's electrical behavior at 60 MHz are not modeled. This focused
sequence does not reproduce a complete game or prove compatibility for
software that omits waits.

The runner freezes and hashes its HDL inputs and rejects concurrent source
changes. It does not edit production RTL or program hardware.
