Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 72 additions & 0 deletions docs/fpga/clocking.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
# FPGA Clocking — XC7A100T QMTECH Wukong V1

## Canonical Clock Source

**STARTUPE2.CFGMCLK** — internal configuration oscillator, ~66 MHz.

This board has NO working external oscillator. Pins U22, M22, M21, F22 were all tested — none carry a clock signal. See `trinity-fpga/CLOCK_PIN_INVESTIGATION_REPORT.md` for full test matrix.

## Usage

```verilog
wire cfgmclk;
STARTUPE2 #(
.PROG_USR("FALSE"),
.SIM_CCLK_FREQ(10.0)
) startup (
.CFGCLK(),
.CFGMCLK(cfgmclk), // ~66 MHz free-running
.EOS(),
.PREQ(),
.CLK(1'b0),
.GSR(1'b0),
.GTS(1'b0),
.KEYCLEARB(1'b0),
.PACK(1'b0),
.USRCCLKO(1'b0),
.USRCCLKTS(1'b0),
.USRDONEO(1'b1),
.USRDONETS(1'b1)
);
```

## Pin Mapping (Verified on Silicon)

| FPGA Pin | Board LED | Polarity |
|----------|-----------|------------|
| R23 | D5 (left) | Active-LOW |
| T23 | D6 (right)| Active-LOW |
| J26 | PMOD | Active-LOW |

## XDC Constraints

```
set_property BITSTREAM.GENERAL.COMPRESS TRUE [current_design]
set_property BITSTREAM.CONFIG.UNUSEDPIN PULLDOWN [current_design]
```

No clock constraints needed — STARTUPE2.CFGMCLK is not a dedicated clock pin.

## Ring Oscillator (DOES NOT WORK)

Ring oscillators fail with openXC7/Yosys:
- `-abc9` inserts SCC breaker that destroys the combinational loop
- Behavioral `assign osc = ~osc` is optimized away by Yosys
- LUT1 primitive instantiation also broken by ABC9 SCC detection
- Building without `-abc9` still results in non-functional oscillator

## Toolchain

```
yosys synth_xilinx -flatten -abc9 -nobram
nextpnr-xilinx --chipdb xc7a100t.bin
fasm2frames --db-root .../artix7
xc7frames2bit
```

Programming: `tools/dlc10_jtag.py` (native Python DLC10 JTAG, SRAM only).

## Golden Artifacts

- `fpga/vsa/temporal_heartbeat_top.v` — 3-phase phi heartbeat (hardware verified)
- `fpga/vsa/gf16_heartbeat_top.v` — phi heartbeat + live GF16 dot4 (hardware verified)
129 changes: 129 additions & 0 deletions fpga/vsa/gf16_heartbeat_top.v
Original file line number Diff line number Diff line change
@@ -0,0 +1,129 @@
`default_nettype none

module gf16_heartbeat_top (
output wire led_d5,
output wire led_d6,
output wire led_j26
);

wire cfgmclk;
STARTUPE2 #(
.PROG_USR("FALSE"),
.SIM_CCLK_FREQ(10.0)
) startup (
.CFGCLK(),
.CFGMCLK(cfgmclk),
.EOS(),
.PREQ(),
.CLK(1'b0),
.GSR(1'b0),
.GTS(1'b0),
.KEYCLEARB(1'b0),
.PACK(1'b0),
.USRCCLKO(1'b0),
.USRCCLKTS(1'b0),
.USRDONEO(1'b1),
.USRDONETS(1'b1)
);

localparam PHI_CYCLE = 27'd80_901_699;
localparam GF16_ONE = 16'h3E00;
localparam GF16_PHI_FRAC = 16'h3D9E;
localparam GF16_HALF = 16'h3C00;
localparam GF16_QUARTER = 16'h3A00;

reg [26:0] phi_counter = 0;
reg [1:0] temporal_layer = 0;
reg [24:0] blink_counter = 0;

always @(posedge cfgmclk) begin
blink_counter <= blink_counter + 1'b1;
phi_counter <= phi_counter + 1'b1;
if (phi_counter >= PHI_CYCLE) begin
phi_counter <= 0;
temporal_layer <= temporal_layer + 1'b1;
end
end

reg [15:0] vec_a0, vec_a1, vec_a2, vec_a3;
reg [15:0] vec_b0, vec_b1, vec_b2, vec_b3;

always @(posedge cfgmclk) begin
vec_a0 <= GF16_ONE;
vec_a1 <= GF16_PHI_FRAC;
vec_a2 <= GF16_HALF;
vec_a3 <= GF16_QUARTER;
case (temporal_layer)
2'd0: begin
vec_b0 <= GF16_ONE;
vec_b1 <= GF16_ONE;
vec_b2 <= GF16_ONE;
vec_b3 <= GF16_ONE;
end
2'd1: begin
vec_b0 <= GF16_PHI_FRAC;
vec_b1 <= GF16_PHI_FRAC;
vec_b2 <= GF16_PHI_FRAC;
vec_b3 <= GF16_PHI_FRAC;
end
2'd2: begin
vec_b0 <= GF16_HALF;
vec_b1 <= GF16_HALF;
vec_b2 <= GF16_HALF;
vec_b3 <= GF16_HALF;
end
default: begin
vec_b0 <= GF16_QUARTER;
vec_b1 <= GF16_QUARTER;
vec_b2 <= GF16_QUARTER;
vec_b3 <= GF16_QUARTER;
end
endcase
end

wire [15:0] dot4_result;

gf16_dot4 dot4 (
.a0(vec_a0), .a1(vec_a1), .a2(vec_a2), .a3(vec_a3),
.b0(vec_b0), .b1(vec_b1), .b2(vec_b2), .b3(vec_b3),
.result(dot4_result)
);

wire dot4_is_positive = ~dot4_result[15];
wire [5:0] dot4_exp = dot4_result[14:9];
wire dot4_is_nonzero = (dot4_exp != 6'd0);

reg d5_out, d6_out, j26_out;
always @(*) begin
d5_out = 1'b0;
d6_out = 1'b0;
j26_out = 1'b0;
case (temporal_layer)
2'd0: begin
d5_out = blink_counter[24];
d6_out = blink_counter[24];
j26_out = dot4_is_nonzero ? blink_counter[20] : 1'b0;
end
2'd1: begin
d5_out = 1'b1;
d6_out = 1'b1;
j26_out = dot4_is_positive ? blink_counter[19] : 1'b0;
end
2'd2: begin
d5_out = blink_counter[22];
d6_out = blink_counter[22];
j26_out = dot4_is_positive ? blink_counter[18] : 1'b0;
end
default: begin
d5_out = 1'b0;
d6_out = 1'b0;
j26_out = 1'b0;
end
endcase
end

assign led_d5 = d5_out;
assign led_d6 = d6_out;
assign led_j26 = j26_out;

endmodule
11 changes: 11 additions & 0 deletions fpga/vsa/gf16_heartbeat_top.xdc
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
set_property LOC R23 [get_ports led_d5]
set_property IOSTANDARD LVCMOS33 [get_ports led_d5]

set_property LOC T23 [get_ports led_d6]
set_property IOSTANDARD LVCMOS33 [get_ports led_d6]

set_property LOC J26 [get_ports led_j26]
set_property IOSTANDARD LVCMOS33 [get_ports led_j26]

set_property BITSTREAM.GENERAL.COMPRESS TRUE [current_design]
set_property BITSTREAM.CONFIG.UNUSEDPIN PULLDOWN [current_design]
77 changes: 77 additions & 0 deletions fpga/vsa/temporal_heartbeat_top.v
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
`default_nettype none

module temporal_heartbeat_top (
output wire led_d5,
output wire led_d6,
output wire led_j26
);

wire cfgmclk;
STARTUPE2 #(
.PROG_USR("FALSE"),
.SIM_CCLK_FREQ(10.0)
) startup (
.CFGCLK(),
.CFGMCLK(cfgmclk),
.EOS(),
.PREQ(),
.CLK(1'b0),
.GSR(1'b0),
.GTS(1'b0),
.KEYCLEARB(1'b0),
.PACK(1'b0),
.USRCCLKO(1'b0),
.USRCCLKTS(1'b0),
.USRDONEO(1'b1),
.USRDONETS(1'b1)
);

localparam PHI_CYCLE = 27'd80_901_699;

reg [26:0] phi_counter = 0;
reg [1:0] temporal_layer = 0;
reg [24:0] blink_counter = 0;

always @(posedge cfgmclk) begin
blink_counter <= blink_counter + 1'b1;
phi_counter <= phi_counter + 1'b1;
if (phi_counter >= PHI_CYCLE) begin
phi_counter <= 0;
temporal_layer <= temporal_layer + 1'b1;
end
end

reg d5_out, d6_out, j26_out;
always @(*) begin
d5_out = 1'b0;
d6_out = 1'b0;
j26_out = 1'b0;
case (temporal_layer)
2'd0: begin
d5_out = blink_counter[24];
d6_out = blink_counter[24];
j26_out = blink_counter[22];
end
2'd1: begin
d5_out = 1'b1;
d6_out = 1'b1;
j26_out = blink_counter[20];
end
2'd2: begin
d5_out = blink_counter[22];
d6_out = blink_counter[22];
j26_out = blink_counter[20];
end
default: begin
d5_out = 1'b0;
d6_out = 1'b0;
j26_out = 1'b0;
end
endcase
end

assign led_d5 = d5_out;
assign led_d6 = d6_out;
assign led_j26 = j26_out;

endmodule
11 changes: 11 additions & 0 deletions fpga/vsa/temporal_heartbeat_top.xdc
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
set_property LOC R23 [get_ports led_d5]
set_property IOSTANDARD LVCMOS33 [get_ports led_d5]

set_property LOC T23 [get_ports led_d6]
set_property IOSTANDARD LVCMOS33 [get_ports led_d6]

set_property LOC J26 [get_ports led_j26]
set_property IOSTANDARD LVCMOS33 [get_ports led_j26]

set_property BITSTREAM.GENERAL.COMPRESS TRUE [current_design]
set_property BITSTREAM.CONFIG.UNUSEDPIN PULLDOWN [current_design]
Loading
Loading