# Shared external CPU interface and selectable clocks

## Status

Development branch: `work/r5-unified-cpu`, based on published R4 commit
`00464da53412984bdcecba9a4c4c5afcbd3de6dd`. R4 remains the hardware comparison
image; no replacement binary has been hardware qualified. R5 was copied and
read-back verified on September 15. With the 68SEC000 it boots at 60 MHz but
crashes starting Alien Breed; the game loads in Normal mode. TF534 and TF536
cards in their original configuration both fail to boot R5 in Normal mode.
These are separate recorded failures. No current R4 TF030 result is established.
The user confirms the latest AmiCube core operates TF030 at selected 50 and
60 MHz; its actual shared response sequence is the primary adaptation reference.

Active development is now the [R7 recorded-read response](r7-results.txt), on
branch `work/r7-recorded-return`. It adapts H20's fresh-request and held-response
ordering to the original SRAM phases. Final integrated functional checks and
routed audits pass; R7 is a hardware test candidate. R5 remains the last card handoff, with
the failures above. No TF030 hardware pass is claimed for R7.

The intended result is one FPGA image for the physical 68000 socket,
including SEC000, TF030 and PiStorm, with selectable nominal Normal and
20/30/40/50/60 MHz clocks. There is no FPGA soft CPU in this target. Every
new hardware candidate needs a new version and exact source/binary identity.

The [Toki investigation](toki-turbo.txt) is closed for now at the user's
request. It is not the reason for these CPU-interface changes.

## Reference lineage

The requested AmiCube reference is pinned to commit
`0ef2e8f1ed240b5ec13b0dc8e30b88aab959d790` in
[AmiCube_V11_Codex](https://gitlab.minimig.ca/ranko/AmiCube_V11_Codex).
Its current H20 source is `fpga/hard_floppy_virtual_ready_h20/hard/source`.
The directory `cores/HARD/source` is explicitly historical R15h and must
not be mistaken for the selected implementation.

H20 has fixed physical socket ownership. Its socket setting does not choose
between TF030 and 68000/PiStorm. Useful shared-interface properties are:

- Capture a fresh request after every AS gap.
- Acknowledge local writes after their actual internal commit.
- Hold returned read data and the selected response source through cycle end.
- Withdraw output enable and acknowledgment without switching the returned
  data underneath the receiver during release.
- Control reset and host bus handover explicitly.

These properties need adaptation to this core's SRAM timing, cache and
Spartan-3 clock resources. H20's generic successful board reports do not
establish every adapter/profile combination; its records retain open setup
timing and intermittent PiStorm startup issues.

### Original Minimig TF030 comparison

The local archives provide an additional comparison on the actual Minimig
platform:

| Archive | SHA-256 |
| --- | --- |
| `Minimig1-v197itx-terriblefire030-6mb-FMG230217-source.zip` | `db81a64c2c31b471d71dadb4e4539d55f7b33586c7a904b12e9b5c3ca2f24eaf` |
| `Minimig1-v197itx-68k-pistorm-6mb-FMG230427-source.zip` | `0bb62bf53862960d36057838da485cebc47152d03f32f93150d7ccf2bc0c512c` |

Both are under `/home/ranko/Downloads`. Normalized comparison copies and
diffs are retained locally in `build/legacy-tf030-comparison`.

The old TF030 bridge adds sixteen read-data registers clocked at 28 MHz
while internal `rd` is active, and another 28 MHz acknowledgment register
which releases on sampled idle. The 68000/PiStorm source removes those
registers and returns the latch/cache mux directly. The TF030 archive also
advertises turbo disabled. The archives differ in other features, including
autoconfiguration and Action Replay, so this is not an isolated historical
experiment proving that one register bank explains all incompatibility.

A retained AmiCube August 6 shared-boot report records both TF030 and MC68000
booting its registered-return candidate (BIN SHA-256
`9121aaebab7b95dc956255aaff4dd30848ef2df78063caaac1fd3fc0ca207add`).
It does not establish PiStorm or turbo qualification for that exact image.

## Focused interface checks

The first test uses the reference's actual PiStorm CPLD and external latch
model. R4 changes away from its held cached word as soon as AS rises.
The CPLD opens its read latch on that same cycle-ending transition. Separate
data-path and output-enable delays are required to test their ordering;
an ideal zero-delay tri-state assignment hides this failure mode.

An unchanged-R4 comparison reproduces bad final PiStorm captures
for all 64 cache hits in 128 turbo reads with 2 ns data / 10 ns output-enable
delay. All 128 pre-release samples are correct. The corresponding Normal
run and the reverse 10 ns data / 2 ns output-enable case pass. These are
simulation assumptions, not measured delays on the user's board.

The integrated R5 candidate registers the source selection at the existing
classification edge and holds it through AS-high. If bypass withdraws and
restores a cached response within one AS interval, it restores the data
source before allowing the registered ACK to return. It passes 24 PiStorm
cases with 3,072 reads, 105 selector-transition accesses and 75 bypass-recovery
accesses. The maintained
[compatibility regression](../tests/cpu-compat/README.txt) includes exact R4
negative controls and records an existing, separate cache-refill failure with
a synthetic 1 ns AS gap. No TF030 fix is claimed from these PiStorm results.
`build/r5-cache-release-02` contains this revised candidate. Main, Normal and
DCM component reports have zero timing errors. The final full regression suite
and focused physical audits pass; see [R5 results](r5-results.txt). The earlier `-01` build lacks
the bypass-recovery fix and is not the selected candidate.

R5 still uses the existing 60.2972184 MHz clock; selectable rates are a
separate experiment. The tested version is **PI FMG260915R560Mhz**, with the failures recorded above.

The noncached return is being checked separately for an acknowledged
transaction that remains active after the internal SRAM/custom slot retires.
The existing transparent latch can reopen onto inactive internal data.
A generic delayed receiver is a robustness probe until the fitted TF030
adapter's actual timing is established. Do not label it a TF030 model.

A private Q0 captured-return experiment passes 720 held/late reads and an
eight-case SRAM integration subset of 2,304 transfers. It adds two Normal
CPU wait clocks and changes turbo acknowledgment latency. Its new physical
capture/refill paths and CIA/VPA behavior remain unqualified, so it is not
part of the R5 candidate. Exact scripts, hashes and limitations are retained
locally in `build/r5-registered-return/README.txt`.

A second private experiment retains the original sixteen latches and ACK
latency. Its ideal-clock tests pass held reads, SRAM/cache/DMA, independent
data/output-enable delay and CIA interrupt read-to-clear checks. However,
combining it with R5 and introducing chipset clock skew exposes a new fault:
a 28 MHz completion flag can withdraw return data before the related 7 MHz
edge closes the latch, or miss the completion when the edge order reverses.
Twelve of 36 skew cases fail while unchanged R5 passes all 36. This form is
rejected before routing. A revised structure is being checked with completion
and fresh-cycle recognition on the existing 7 MHz edge, and latch-hold changes
restricted to the following 28 MHz phase. Neither experiment is in R5. See the [R6 experiment record](r6-read-hold-experiment.txt)
for the revised digital results and routed review.

Any fix must retain the existing CPU/SRAM, custom-write, cache-coherency and
Normal-mode phase regressions and be audited after routing. A simulation
failure alone does not establish the cause of a hardware black screen.

## Selectable clock architecture under evaluation

Keep both chipset DCMs. Two fixed CPU DCMs can derive the requested rates
from buffered 28.3751616 MHz:

| Selection | Source | Actual proposed frequency |
| --- | --- | ---: |
| Normal | Existing chipset / 4 | 7.0937904 MHz |
| 20 MHz | (chip28 × 17/4) / 6 | 20.0990728 MHz |
| 30 MHz | (chip28 × 17/4) / 4 | 30.1486092 MHz |
| 40 MHz | (chip28 × 17/4) / 3 | 40.1981456 MHz |
| 50 MHz | chip28 × 30/17 | 50.0738146 MHz |
| 60 MHz | (chip28 × 17/4) / 2 | 60.2972184 MHz |

This uses all four DCMs and an estimated seven of eight global buffers.
R4 already uses 3,550 of 3,584 slices, so final fit and timing are open.
Spartan-3 lacks AmiCube's Spartan-6 programmable `DCM_CLKGEN` interface.
The divide-by-three duty-cycle correction requires a half-cycle path at
120.5944368 MHz; its nominal budget is only 4.146 ns.

Clock-profile changes will be applied under CPU reset. The prototype first
switches to running Normal, updates the unused turbo selector, waits for a
stable target, then switches and supplies warmup clocks before reset release.
The final mux selection must meet the Spartan-3 -4 0.60 ns select-setup
requirement. Reset alone does not make an unsafe clock mux acceptable.
See AMD's [Spartan-3 datasheet](https://docs.amd.com/api/khub/documents/y7TWBeO97VdEfASgDFNn~Q/content)
and [Spartan-3 Libraries Guide](https://docs.amd.com/api/khub/documents/y69WxdkWPXDQH2SmhT3RFA/content).

The isolated prototype passes all 36 ordered profile transitions with ideal,
delayed, stressed and UNISIM DCM sources, plus all six cold-boot profiles,
reset-interruption checks and five rejected mutations. Its standalone XST
result is 33 slices, 42 flip-flops and 58 LUTs. This is not a full-core fit
or routed timing result. Source and runners are preserved in
`experiments/selectable-clock` for further integration.

### Space for the clock controller

A complete R5 build with MAP packing changed from 95% to 85% produces the
same 3,554 slices, 5,368 LUTs and reported timing margins. All 25 source inputs
are identical. This trial provides no headroom, so 95% remains selected;
private evidence is in `build/r5-pack85-01/packing-comparison.txt`.

An isolated palette RAM experiment saves 28 slices in comparable standalone
MAP runs by using one spare BRAM and absorbing the existing RGB output
registers. It is not an equivalent drop-in change: when the physical 7 MHz
write precedes the proposed 28 MHz write, same-address pixels can differ,
and early register-bus retirement can lose a write. The aligned digital
comparison passes 8,228 pixels, but the offset counterexamples remain. Its
bus timing and collision behavior must be resolved before integration;
`build/r5-palette-prototype/README.txt` preserves both successful cases and
counterexamples. Production palette logic is unchanged.

Each selected clock still needs a routed interface check. These frequencies
refer to the socket clock pin; an accelerator's onboard CPU oscillator is
a separate setting. Integration must keep the external reset request
separate from the clock controller's own reset hold, avoiding feedback that
would prevent reset release, and retain the legacy boot-overlay Normal clock
behavior.

## Host menu dependency

The existing OSD is a host-written text buffer. FPGA changes alone cannot
add the clock menu. The current legacy host command `0xD0 | chipset_bits`
has one Normal/turbo bit, with the other bits already assigned. `0x94` through
`0x97` are fast-RAM configuration and must not be reused for clock control.

AmiCube's native `0x18` plus `0xA8` through `0xAD` profile command and
versioned capabilities are useful extension concepts. Final protocol and
saved-configuration migration must be matched to this board's host firmware.
Old host firmware must retain working Normal/60 MHz behavior.

The installed Minimig ARM firmware version/source is still unidentified.
The nearby SAM7 AmiCube firmware has incompatible command assignments and
is not a drop-in replacement. No host firmware has been flashed or selected
for this work.
