feat(fpga): add board-neutral RetroCore RTL skeleton

.github/workflows/fpga-qualification.yml

@@ -15,7 +15,7 @@ permissions:
   contents: read
 
 jobs:
-  ecp5-85k-smoke:
+  ecp5-toolchain-smoke:
     runs-on: ubuntu-latest
     container:
       image: hdlc/impl:latest
@@ -25,11 +25,21 @@ jobs:
         run: |
           yosys -V
           nextpnr-ecp5 --version
-      - name: Synthesize ECP5 smoke RTL
+      - name: Install Icarus Verilog
+        run: |
+          apt-get update
+          DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends iverilog
+
+      - name: Qualify board-neutral RetroCore RTL
+        run: |
+          make -C fpga/rtl test
+          make -C fpga/rtl synth
+
+      - name: Synthesize synthetic ECP5 85K smoke RTL
         run: |
           mkdir -p build
           yosys -l build/yosys.log -p 'read_verilog fpga/qualification/ecp5_85k_smoke.v; synth_ecp5 -top ecp5_85k_smoke -json build/smoke.json'
-      - name: Validate 85K target is available
+      - name: Validate synthetic 85K toolchain target is available
         run: |
           nextpnr-ecp5 --help 2>&1 | tee build/nextpnr-help.txt
           grep -Eq -- '--um5g-85k|--85k' build/nextpnr-help.txt
@@ -45,11 +55,6 @@ jobs:
         run: |
           yosys -l build/sdram-controller-yosys.log -p 'read_verilog fpga/retrocore/platform/sdram_controller.v fpga/retrocore/platform/sdram_controller_qual_top.v; synth_ecp5 -top sdram_controller_qual_top -json build/sdram-controller.json'
 
-      - name: Install Icarus Verilog
-        run: |
-          apt-get update
-          DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends iverilog
-
       - name: Simulate SDRAM controller protocol
         run: |
           iverilog -g2012 -o build/tb-sdram-controller fpga/retrocore/platform/sdram_controller.v fpga/qualification/tb_sdram_controller.v
@@ -80,5 +85,5 @@ jobs:
       - uses: actions/upload-artifact@v4
         if: always()
         with:
-          name: ecp5-85k-smoke-logs
+          name: ecp5-toolchain-smoke-logs
           path: build/

fpga/README.md

@@ -0,0 +1,20 @@
+# RetroSBC FPGA
+
+This directory is the board-neutral starting point for RetroCore RTL.
+
+The current target is the Lattice ECP5UM family in the approximately 45K LUT class. The exact Rev A device, package and pin constraints remain consumer/board facts and are not guessed here.
+
+## Current qualification
+
+- RTL smoke simulation: available via `make test`
+- ECP5 synthesis: available via `make synth`
+- Place-and-route / bitstream: pending exact Rev A device/package/constraints
+- Physical FPGA qualification: pending Rev A hardware
+
+The eventual hardware-ci integration will use the generic `ecp5` profile while RetroSBC owns the exact device, package, constraints and bitstream build target.
+
+## Synthetic CI target
+
+The repository's existing 85K smoke check is a toolchain regression test only. It verifies that the CI environment exposes an ECP5 85K target; it is **not** the RetroSBC Rev A FPGA selection and does not qualify physical RetroSBC hardware.
+
+The documented Rev A baseline remains ECP5UM, approximately 45K LUT class, until the exact device/package and board constraints are frozen.

fpga/rtl/Makefile

@@ -0,0 +1,18 @@
+BUILD_DIR ?= build
+TOP := retrocore_top
+
+.PHONY: test synth clean
+
+test:
+	mkdir -p $(BUILD_DIR)
+	iverilog -g2012 -o $(BUILD_DIR)/tb $(TOP).v tb_$(TOP).v
+	vvp $(BUILD_DIR)/tb
+
+synth:
+	mkdir -p $(BUILD_DIR)
+	yosys -p 'synth_ecp5 -top $(TOP) -json $(BUILD_DIR)/$(TOP).json' $(TOP).v
+
+# A physical ECP5UM-45K bitstream target is intentionally deferred until
+# the exact Rev A device/package and board constraints are frozen.
+clean:
+	rm -rf $(BUILD_DIR)

fpga/rtl/retrocore_top.v

@@ -0,0 +1,16 @@
+module retrocore_top(
+    input  wire clk,
+    input  wire reset_n,
+    output wire alive
+);
+    reg [23:0] heartbeat = 24'd0;
+
+    always @(posedge clk) begin
+        if (!reset_n)
+            heartbeat <= 24'd0;
+        else
+            heartbeat <= heartbeat + 1'b1;
+    end
+
+    assign alive = heartbeat[23];
+endmodule

fpga/rtl/tb_retrocore_top.v

@@ -0,0 +1,18 @@
+`timescale 1ns/1ps
+module tb_retrocore_top;
+    reg clk = 0;
+    reg reset_n = 0;
+    wire alive;
+
+    retrocore_top dut(.clk(clk), .reset_n(reset_n), .alive(alive));
+
+    always #5 clk = ~clk;
+
+    initial begin
+        repeat (2) @(posedge clk);
+        reset_n = 1;
+        repeat (8) @(posedge clk);
+        $display("RetroCore RTL smoke test PASS");
+        $finish;
+    end
+endmodule