fix: generate 27.000 MHz from a dedicated video PLL

The fitter rejected 27.000000 MHz on the shared PLL: all outputs of one
PLL divide a common VCO, and lcm(100 MHz clk_sys, 27 MHz) = 2700 MHz is
beyond the Cyclone V's 600-1600 MHz VCO range. 27.027027 MHz (1000/37)
is exactly the closest sharable frequency, which is why stock MiSTer
uses it.

- Revert rtl/pll/pll_0002.v to stock; its 27.027 MHz output is now
  unconnected.
- Add rtl/pll_video.v (+ pll_video_0002.v, qip): dedicated PLL whose
  sole output is exact 27.000000 MHz (VCO 1350 MHz = 50 x 27, C = 50);
  CLK_VIDEO comes from it, and the native video path holds in reset
  until it locks.
- Add menu.sdc declaring the video clock asynchronous to all other
  clocks. It was absent from sys_top.sdc's exclusive clock groups, so
  TimeQuest analyzed the two-flop synchronizer and line-FIFO crossings
  as related paths (worst slack -10.4 ns, TNS -1529). All crossings are
  designed CDC structures. With the constraint, the full Quartus 17.0.2
  compile meets timing on every domain (worst setup slack +0.53 ns,
  TNS 0), which the previous 27.027 MHz baseline did not (-4.8 ns,
  TNS -426).
- Document the shared-VCO constraint in docs/native-video-plan.md.

Author: wizzomafizzo

docs/native-video-plan.md

@@ -145,9 +145,17 @@ geometry (section 4) plus safe-area UI rules (section 6).
 
 ## 4. Target timings
 
-Everything derives from **one PLL change**: output 1 of `rtl/pll/pll_0002.v`
-goes from 27.027027 MHz to **27.000000 MHz** — the universal SD video clock
-(it is exactly 1716 × NTSC line rate and 1728 × PAL line rate).
+Everything derives from one clock change: CLK_VIDEO goes from 27.027027 MHz
+to **27.000000 MHz** — the universal SD video clock (it is exactly 1716 ×
+NTSC line rate and 1728 × PAL line rate).
+
+> **Implementation note (found at fit time):** 27.000 MHz cannot come from
+> the existing PLL. All outputs of one PLL divide a shared VCO, and
+> lcm(100 MHz clk_sys, 27 MHz) = 2700 MHz exceeds the Cyclone V's
+> 600–1600 MHz VCO range — 27.027027 (1000 MHz / 37) is precisely the
+> closest sharable frequency, which is why stock MiSTer uses it. The fix is
+> a dedicated video PLL (`rtl/pll_video.v`, VCO 1350 MHz = 50 × 27, C = 50)
+> whose sole output drives CLK_VIDEO; `pll_0002.v` stays stock.
 
 | Mode | ce_pix | H total | H active / FP / sync / BP (px) | V total | V active / FP / sync / BP (lines) | Line rate | Refresh |
 |---|---|---|---|---|---|---|---|
@@ -348,9 +356,12 @@ These are as much a part of the fix as the RTL — geometry alone doesn't solve
 
 FPGA (this repo):
 
-1. **`rtl/pll/pll_0002.v`**: `output_clock_frequency1` 27.027027 MHz →
-   `27.000000 MHz`. (Same single-line style as the earlier 20→27.027 change;
-   no other PLL params move.)
+1. ~~`rtl/pll/pll_0002.v`: `output_clock_frequency1` 27.027027 MHz →
+   `27.000000 MHz`.~~ Superseded: the shared PLL cannot fit 27.000 MHz (see
+   the implementation note in §4). Instead `pll_0002.v` stays stock and a
+   new dedicated `rtl/pll_video.v` (+ `rtl/pll_video/pll_video_0002.v`,
+   `rtl/pll_video.qip`) generates CLK_VIDEO = 27.000000 MHz; menu.sv holds
+   the native video path in reset until it locks.
 2. **`rtl/native_video_timing.sv`**: mode-0 constants — H 352/12/32/33,
    V 240/3/3/16. Structure the constants as per-mode parameter sets selected
    by a `mode` input (tied to 0 until Phases B/C) so later modes are additive.

files.qip

@@ -1,3 +1,5 @@
+set_global_assignment -name QIP_FILE rtl/pll_video.qip
+set_global_assignment -name SDC_FILE menu.sdc
 set_global_assignment -name SYSTEMVERILOG_FILE rtl/sdram.sv
 set_global_assignment -name VERILOG_FILE rtl/lfsr.v
 set_global_assignment -name SYSTEMVERILOG_FILE rtl/cos.sv

menu.sdc

@@ -0,0 +1,12 @@
+# Core-level timing constraints (processed after sys/sys_top.sdc).
+
+# CLK_VIDEO comes from a dedicated PLL (rtl/pll_video.v) and is asynchronous
+# to every other clock in the design: all crossings into and out of the video
+# domain go through two-flop synchronizers or the line FIFO's dual-clock
+# logic (rtl/native_video_reader.sv, rtl/native_video_top.sv). Without this
+# group, derive_pll_clocks leaves the 27 MHz output related to the other
+# clocks (shared 50 MHz reference, and absent from sys_top.sdc's exclusive
+# groups), and the fitter tries to close those CDC paths against a ~1 ns
+# edge relationship.
+set_clock_groups -asynchronous \
+   -group [get_clocks { *|pll_video|pll_video_inst|altera_pll_i|*[*].*|divclk}]

menu.sv

@@ -237,10 +237,21 @@ pll pll
 	.refclk(CLK_50M),
 	.rst(0),
 	.outclk_0(clk_sys),
-	.outclk_1(CLK_VIDEO),
+	.outclk_1(),         // stock 27.027 MHz output, unused (see pll_video)
 	.locked(locked)
 );
 
+// Exact 27.000000 MHz video clock from its own PLL: 27 MHz can't share a
+// VCO with the 100 MHz clk_sys (lcm = 2700 MHz, above the VCO ceiling).
+wire vid_locked;
+pll_video pll_video
+(
+	.refclk(CLK_50M),
+	.rst(0),
+	.outclk_0(CLK_VIDEO),
+	.locked(vid_locked)
+);
+
 
 /////////////////////   SDRAM   ///////////////////
 //
@@ -472,7 +483,7 @@ wire [1:0] native_mode;
 reg [1:0] ce_div;
 reg       ce_pix;
 always @(posedge CLK_VIDEO) begin
-	if (RESET) ce_div <= 2'd0;
+	if (RESET | ~vid_locked) ce_div <= 2'd0;
 		else  ce_div <= ce_div + 2'd1;
 	ce_pix <= (native_mode == 2'd1) ? ce_div[0] : (ce_div == 2'd0);
 end
@@ -498,7 +509,7 @@ native_video_top native_video
 	.clk_sys        (clk_sys),
 	.clk_vid        (CLK_VIDEO),
 	.ce_pix         (ce_pix),
-	.reset          (RESET),
+	.reset          (RESET | ~vid_locked),
 
 	.ddr_busy       (DDRAM_BUSY),
 	.ddr_burstcnt   (DDRAM_BURSTCNT),

rtl/pll/pll_0002.v

@@ -25,7 +25,7 @@ module  pll_0002(
 		.output_clock_frequency0("100.000000 MHz"),
 		.phase_shift0("0 ps"),
 		.duty_cycle0(50),
-		.output_clock_frequency1("27.000000 MHz"),
+		.output_clock_frequency1("27027027 Hz"),
 		.phase_shift1("0 ps"),
 		.duty_cycle1(50),
 		.output_clock_frequency2("0 MHz"),

rtl/pll_video.qip

@@ -0,0 +1,6 @@
+set_global_assignment -name VERILOG_FILE [file join $::quartus(qip_path) "pll_video.v"]
+set_global_assignment -name VERILOG_FILE [file join $::quartus(qip_path) "pll_video/pll_video_0002.v"]
+
+set_instance_assignment -name PLL_COMPENSATION_MODE DIRECT -to "*pll_video_0002*|altera_pll:altera_pll_i*|*"
+set_instance_assignment -name PLL_AUTO_RESET ON -to "*pll_video_0002*|altera_pll:altera_pll_i*|*"
+set_instance_assignment -name PLL_BANDWIDTH_PRESET AUTO -to "*pll_video_0002*|altera_pll:altera_pll_i*|*"

rtl/pll_video.v

@@ -0,0 +1,25 @@
+// Dedicated video PLL: exact 27.000000 MHz for SD CRT timing.
+//
+// This cannot come from the main PLL: every output of a PLL divides the
+// same VCO, and the smallest common multiple of 100 MHz (clk_sys) and
+// 27 MHz is 2700 MHz — outside the Cyclone V's 600-1600 MHz VCO range.
+// (That constraint is why stock MiSTer uses 27.027027 MHz: 1000 MHz / 37
+// is the closest to 27 MHz a VCO shared with 100 MHz can reach.)
+// Standalone, 27 MHz is exact: VCO = 50 MHz x 27 = 1350 MHz, C = 50.
+
+`timescale 1 ps / 1 ps
+module pll_video (
+		input  wire  refclk,   //  refclk.clk
+		input  wire  rst,      //   reset.reset
+		output wire  outclk_0, // outclk0.clk
+		output wire  locked    //  locked.export
+	);
+
+	pll_video_0002 pll_video_inst (
+		.refclk   (refclk),   //  refclk.clk
+		.rst      (rst),      //   reset.reset
+		.outclk_0 (outclk_0), // outclk0.clk
+		.locked   (locked)    //  locked.export
+	);
+
+endmodule

rtl/pll_video/pll_video_0002.v

@@ -0,0 +1,86 @@
+`timescale 1ns/10ps
+module  pll_video_0002(
+
+	// interface 'refclk'
+	input wire refclk,
+
+	// interface 'reset'
+	input wire rst,
+
+	// interface 'outclk0'
+	output wire outclk_0,
+
+	// interface 'locked'
+	output wire locked
+);
+
+	altera_pll #(
+		.fractional_vco_multiplier("false"),
+		.reference_clock_frequency("50.0 MHz"),
+		.operation_mode("direct"),
+		.number_of_clocks(1),
+		.output_clock_frequency0("27.000000 MHz"),
+		.phase_shift0("0 ps"),
+		.duty_cycle0(50),
+		.output_clock_frequency1("0 MHz"),
+		.phase_shift1("0 ps"),
+		.duty_cycle1(50),
+		.output_clock_frequency2("0 MHz"),
+		.phase_shift2("0 ps"),
+		.duty_cycle2(50),
+		.output_clock_frequency3("0 MHz"),
+		.phase_shift3("0 ps"),
+		.duty_cycle3(50),
+		.output_clock_frequency4("0 MHz"),
+		.phase_shift4("0 ps"),
+		.duty_cycle4(50),
+		.output_clock_frequency5("0 MHz"),
+		.phase_shift5("0 ps"),
+		.duty_cycle5(50),
+		.output_clock_frequency6("0 MHz"),
+		.phase_shift6("0 ps"),
+		.duty_cycle6(50),
+		.output_clock_frequency7("0 MHz"),
+		.phase_shift7("0 ps"),
+		.duty_cycle7(50),
+		.output_clock_frequency8("0 MHz"),
+		.phase_shift8("0 ps"),
+		.duty_cycle8(50),
+		.output_clock_frequency9("0 MHz"),
+		.phase_shift9("0 ps"),
+		.duty_cycle9(50),
+		.output_clock_frequency10("0 MHz"),
+		.phase_shift10("0 ps"),
+		.duty_cycle10(50),
+		.output_clock_frequency11("0 MHz"),
+		.phase_shift11("0 ps"),
+		.duty_cycle11(50),
+		.output_clock_frequency12("0 MHz"),
+		.phase_shift12("0 ps"),
+		.duty_cycle12(50),
+		.output_clock_frequency13("0 MHz"),
+		.phase_shift13("0 ps"),
+		.duty_cycle13(50),
+		.output_clock_frequency14("0 MHz"),
+		.phase_shift14("0 ps"),
+		.duty_cycle14(50),
+		.output_clock_frequency15("0 MHz"),
+		.phase_shift15("0 ps"),
+		.duty_cycle15(50),
+		.output_clock_frequency16("0 MHz"),
+		.phase_shift16("0 ps"),
+		.duty_cycle16(50),
+		.output_clock_frequency17("0 MHz"),
+		.phase_shift17("0 ps"),
+		.duty_cycle17(50),
+		.pll_type("General"),
+		.pll_subtype("General")
+	) altera_pll_i (
+		.rst	(rst),
+		.outclk	(outclk_0),
+		.locked	(locked),
+		.fboutclk	( ),
+		.fbclk	(1'b0),
+		.refclk	(refclk)
+	);
+endmodule