# Clock and timing model

The original clock model below is retained by R2. Its additional CPU path
constraints, placement and inactive slow-mode lookup exception are documented
in [CPU interface timing](cpu-interface-timing.txt) and [R2 results](r2-results.txt).

## Frequencies and clock groups

The PAL oscillator is 4.433619 MHz. The first DCM multiplies it by 32/5
to 28.3751616 MHz. The feedback DLL generates that chipset clock and its
7.0937904 MHz divided clock. The CPU DCM multiplies the divided clock by
17/2, producing **60.2972184 MHz** for the nominal 60 MHz setting.

The CPU clock mux switches between inverted 7 MHz and inverted turbo
clocks. The chipset continues running at 28/7 MHz in either CPU mode.

The implementation UCF uses disjoint groups:

| Group | Members | Timing relationship |
| --- | --- | --- |
| `chip28` | Registers clocked by `clk28m` | 35.242089 ns |
| `chip7` | `clk` loads excluding CPU and 28 MHz registers | Four times `TS_chip28` |
| `cpu` | Registers and RAM on `cpu_clk_OBUF` | Independent 16.584513 ns |
| `dcm_reset28` | DLL reset release pipeline | 35.242089 ns before the feedback DLL |

`cpu_clk` is the output pad net after synthesis. Applying TNM_NET to it
alone constrains no internal CPU registers. `cpu_clk_OBUF` is the mux
output net that actually clocks those registers and the cache RAM.

The 7 MHz net also feeds the CPU mux and the D input of `CLOCK1/clk7_sample`
(the direct `CLOCK1/c3` input before R3).
The UCF excludes both downstream groups to prevent overlapping PERIOD
constraints. The chipset 7/28 MHz relationship remains explicitly timed.
The [phase audit](chipset-phase-timing.txt) separately checks the clock-as-data
path and the new half-cycle sampling stage.

The CPU DCM uses CLKFX without phase feedback. A common input oscillator
does not establish a guaranteed synchronous CPU-to-chipset phase. Its
independent PERIOD checks paths within the fast CPU domain; clock-domain
crossings need a separate protocol review.

`SYSTEM_JITTER = 0.5 ns` is an engineering allowance, not a measured board
specification or a datasheet guarantee. TRACE combines it according to its
jitter formula; the audited register paths show 0.354 ns clock uncertainty.
Spartan-3 TRACE otherwise reports zero system jitter and does not calculate
the device's discrete jitter and phase error automatically.

## Additional routed reports

Run after a build with the disjoint UCF:

```sh
scripts/audit_timing.sh build/candidate-name
```

The script leaves the routed design and implementation PCF unchanged and
creates these reports:

- `timing-components.twr`: all three DCM input frequencies and component
  switching limits, plus the existing internal timing constraints.
- `timing-slow.twr`: CPU PERIOD derived from the inverted 7 MHz clock,
  checking the slow mode's related clock paths separately. Its explicit
  `PHASE + 70.484178 ns` places CPU rising edges at chipset falling edges.
  `LOW 50%` alone does not set that related-clock phase in TRACE.
- `timing-cdc.twr`: CPU/chipset crossing inventory and measured data path
  delays. Its deliberately loose 1000 ns reporting limits **do not establish
  CDC safety or permissible interface delay**.
- Matching `.tsi` reports show constraint interactions and clock group
  overlaps. The validated disjoint model reports no overlap.

DCM operating limits use explicit input-pin groups in these audit PCFs.
This preserves those checks without propagating an input PERIOD through
both mux branches and reintroducing overlapping CPU/7 MHz groups.

The slow report has narrowly scoped inactive-path exceptions. Turbo
acknowledgment `_ta_t1` cannot assert in settled slow mode, so only its path
to the first synchronizer stage `_ta_t2` is excluded there. `_ta_t2` to
`_ta_t` remains timed. For snapshots with turbo-only cache refill, slow mode
also holds cache invalidation asserted; memory configuration bits 3:0
cannot affect the three cache RAM write ports. Only those configuration
paths are excluded. The script checks the snapshot's RTL before applying
each exception. Turbo constraints and the crossing inventory retain
these paths. Mode-switch behavior is checked separately in regression.

For the staged lookup, six chipset configuration/mode registers
(`memory_config[3:0]`, `scanline[1]`/cache bypass, and `turbo`) also have
inactive paths to the single `cache_lookup_hit` decision register in slow
mode. `turbo=0` forces lookup eligibility to zero. Speed changes require
AS high, which asynchronously clears the lookup decision. The script checks
these assignments and the mode-change condition before adding the exception.
It retains all CPU-clocked tag, valid-bit and lookup paths. The guard test
changes each assumption and verifies that the exception is then omitted;
the corner regression toggles bypass/configuration while slow and checks
that both the decision and cache acknowledgment remain zero.

R3 includes bits 1:0 in these existing source-checked exceptions because the
512K+512K cache bypass also depends on chip-RAM size. This changes only the
audit of inactive slow-mode cache paths; turbo paths and the timing budgets
remain constrained. Memory configuration is latched only during system
reset, which also invalidates the CPU cache.

## Crossings that require review

- `_ta_t1` to `_ta_t2` is the first stage of the turbo acknowledgment
  synchronizer; `_ta_t2` to `_ta_t` must remain a timed CPU path. The
  acknowledgment is held until the external address strobe releases it.
- `t_dtack` now samples the synchronized turbo acknowledgment `_ta_t`.
  Slow acknowledgment `_ta_n` no longer feeds this cache capture register,
  and cache hits do not cause redundant refills. Slow mode holds the cache
  invalid, so returning to turbo requires a complete scrub before hits.
- Cache hit and acknowledgment logic feed the chipset's `l_as28m` and
  `l_dtack`. These are single-stage sampling paths, not a general-purpose
  asynchronous handshake. CPU bus phase and bus stability matter.
- Memory configuration controls cache-bank enables. Configuration changes
  require cache invalidation and stable configuration while CPU accesses
  are enabled.
- Cache invalidation from reset or MIA ownership must reach the CPU domain
  through its synchronizer and inhibit cache hits until clearing finishes.

The CPU input/output interface remains dependent on the installed CPU's
timing and the board wiring. Internal PERIOD closure and the historical
20/33 ns path budgets do not prove CPU setup/hold timing at 60 MHz. SPI
input/output timing likewise requires the controller's actual clock rate
and launch/capture timing. No blanket false-path constraints hide these
issues.

`TS19` extends the existing 33 ns SRAM data budget to RAM destinations;
the legacy `FFS` group omits block/distributed RAM endpoints. With
registered SRAM write data, the FIFO feeds the write register under the
related chipset PERIOD. A focused routed audit also enumerates these
RAM-to-register paths. The temporary direct RAM-to-pad `TS18` constraint
was removed once that direct path no longer existed. `TS20` budgets CPU data
pads to the Q2 write register at 33 ns, based on data being valid before
the write strobe sampled at Q1. CPU/PCB timing still needs qualification.
The held write register and half-cycle output-enable extension separate
data release from write termination; final routed minimum/maximum delays
and the actual SRAM specification must establish the external margins.

For the staged CPU read path, `TS21` checks held data and its two selector
registers to the CPU data pads at 16 ns. `TS22` checks registered turbo/cache
acknowledgment to DTACK at 6 ns. The former RAM-to-DTACK path now ends at a
CPU-clocked lookup register and is covered internally by `TS_cpu`.
`TS23` preserves the old 20 ns byte-strobe input budget to that lookup
boundary. The obsolete direct RAM/strobe-to-DTACK constraints were removed
after TRACE confirmed zero paths. See [CPU interface timing](cpu-interface-timing.txt)
for the forwarded-clock measurement and the limits of these FPGA budgets.

## DCM startup

Both cascaded DCM inputs use global clock buffers. Each downstream DCM is
held in reset until its upstream source locks, then its reset releases
through three registers clocked by that DCM's own input. Directly wiring
`RST = ~upstream_locked` failed the vendor simulation's required three
input-clock reset cycles; the reset pipelines satisfy that requirement.

Only the first DCM has `STARTUP_WAIT=TRUE`. The downstream DLL and CPU DCM
use `FALSE`: their reset-release registers cannot shift before configuration
asserts global write enable (GWE). Waiting for those DCMs to lock before GWE
would create a circular dependency and stall startup. `clocks_ready` clears
asynchronously when any DCM loses lock, and asserts after three locked
7 MHz edges. It holds the CPU reset and system reset timer until all three
DCMs lock. The internal reset register also starts asserted at configuration.

`tests/tb_clock_generator.v` checks the non-simulatable `STARTUP_WAIT`
attributes explicitly and emulates inhibited fabric writes before GWE. It
uses ISE UNISIM models to check digital lock sequencing, reset readiness,
frequency ratios, clock enables, the ten E-clock phases, and pulse widths
while switching turbo on and off. The vendor models emit two initial
long-input-period warnings while upstream clocks start, then all three
DCMs lock and the regression passes. The test does not simulate the actual
configuration controller, characterize analog clock jitter or establish
recovery of the complete Amiga system after a physical oscillator failure.

## References

- [AMD/Xilinx Timing Closure User Guide, UG612](https://docs.amd.com/v/u/en-US/ug612):
  clock groups and exclusions, constraint interactions, system jitter,
  component switching limits, and external timing constraints.
- [Spartan-3 FPGA Family Data Sheet, DS099](https://docs.amd.com/v/u/en-US/ds099):
  DCM operating limits, clock routing, and reset requirements.
- [Spartan-3 Generation FPGA User Guide, UG331](https://docs.amd.com/v/u/en-US/ug331):
  cascaded DCM reset recommendations (p. 144) and configuration ordering
  of GTS, lock wait, GWE and DONE (pp. 148–150).
- [Spartan-3 Libraries Guide, UG607](https://docs.amd.com/api/khub/documents/y69WxdkWPXDQH2SmhT3RFA/content):
  supported DCM primitive connections.
