Rename sdram_ctrl to sdram_gw2ar and add example

Rename the module and all associated files to sdram_gw2ar to encode
the target product (GW2AR embedded SDRAM in the Tang Nano 20K).

Add sdram_gw2ar_example.v demonstrating a write-then-read-back pattern
using a 6-state FSM, with LED outputs reporting pass/fail.

Made-with: Cursor

Author: higuoxing

README.md

@@ -27,7 +27,7 @@ NyanSoC/
 │   │   ├── uart_tx.v     # UART transmitter
 │   │   └── uart_rx.v     # UART receiver
 │   └── gowin/
-│       └── sdram_ctrl.v  # SDRAM controller
+│       └── sdram_gw2ar.v  # SDRAM controller for GW2AR embedded SDRAM
 ├── boards/
 │   └── tangnano20k/      # Tang Nano 20K top-level + P&R scripts (only supported board)
 ├── firmware/

rtl/gowin/.gitignore

@@ -1,3 +1,3 @@
 *_prove
 *_cover
-sdram_ctrl/*
+sdram_gw2ar/*

rtl/gowin/Makefile

@@ -1,6 +1,6 @@
 .PHONY: prove cover
 prove:
-	sby -f sdram_ctrl.sby prove
+	sby -f sdram_gw2ar.sby prove
 
 cover:
-	sby -f sdram_ctrl.sby cover
+	sby -f sdram_gw2ar.sby cover

rtl/gowin/sdram_ctrl.sby

@@ -0,0 +1,33 @@
+[tasks]
+cover
+prove
+
+[options]
+prove: mode prove
+cover: mode cover
+prove: depth 50
+cover: depth 80
+
+[engines]
+smtbmc z3
+
+[script]
+read -formal sdram_gw2ar.v
+# Scale down all timing so the full init+read+write sequence fits in <80 cycles:
+# INIT_CYCLES = (2000 * 1) / 1000 = 2
+# T_RP=T_RFC=T_MRD=T_RCD=T_CL=T_WR = 2
+# REFRESH_INTERVAL = (4096 / 1 * 1) / 1000 = 4  (so refresh fires every 4 cycles)
+chparam -set CLOCK_FREQ_MHZ 1 sdram_gw2ar
+chparam -set INITIALIZATION_WAIT_PERIOD_NS 2000 sdram_gw2ar
+chparam -set REFRESH_PERIOD_NS 4096 sdram_gw2ar
+chparam -set REFRESH_TIMES 1 sdram_gw2ar
+chparam -set T_RP_PERIOD 2 sdram_gw2ar
+chparam -set T_RFC_PERIOD 2 sdram_gw2ar
+chparam -set T_MRD_PERIOD 2 sdram_gw2ar
+chparam -set T_RCD_PERIOD 2 sdram_gw2ar
+chparam -set T_CL_PERIOD 2 sdram_gw2ar
+chparam -set T_WR_PERIOD 2 sdram_gw2ar
+prep -top sdram_gw2ar
+
+[files]
+./sdram_gw2ar.v

rtl/gowin/sdram_gw2ar.sby

@@ -10,7 +10,7 @@
 //   [ROW_WIDTH+COLUMN_WIDTH-1            : COLUMN_WIDTH]             = row
 //   [COLUMN_WIDTH-1                      : 0]                        = column
 
-module sdram_ctrl #(
+module sdram_gw2ar #(
     parameter integer DATA_WIDTH              = 32,      // {8,16,32,64}
     parameter integer BANK_WIDTH              = 2,       // {1,2}
     parameter integer ROW_WIDTH               = 11,      // {11,12,13,14}
@@ -473,4 +473,4 @@ module sdram_ctrl #(
 
 `endif  // FORMAL
 
-endmodule  // sdram_ctrl
+endmodule  // sdram_gw2ar

rtl/gowin/sdram_ctrl.v rtl/gowin/sdram_gw2ar.vrtl/gowin/sdram_ctrl.v renamed to rtl/gowin/sdram_gw2ar.v

@@ -0,0 +1,169 @@
+`default_nettype none
+`timescale 1 ns / 1 ps
+
+// Example usage of sdram_gw2ar.
+//
+// After initialization completes the module writes the 32-bit word 0xDEADBEEF
+// to SDRAM address 0, then reads it back.  Two LEDs report the outcome:
+//   o_led_ok   – pulses high when the readback value matches the written word
+//   o_led_err  – pulses high when the readback value does not match
+//
+// Wiring for Tang Nano 20K (27 MHz oscillator, GW2AR-18 embedded SDRAM):
+//   i_clk      <- 27 MHz system clock (same clock fed to SDRAM)
+//   i_rst_n    <- active-low reset (e.g. button_n)
+//   o_sdram_*  <- connect directly to the GW2AR embedded SDRAM pins
+//   io_sdram_dq<- bidirectional data bus
+
+module sdram_gw2ar_example (
+    input  wire        i_clk,
+    input  wire        i_rst_n,
+
+    // Status LEDs (active-high)
+    output reg         o_led_ok,
+    output reg         o_led_err,
+
+    // SDRAM physical interface (pass through from sdram_gw2ar)
+    output wire        o_sdram_clk,
+    output wire        o_sdram_cke,
+    output wire        o_sdram_cs_n,
+    output wire        o_sdram_cas_n,
+    output wire        o_sdram_ras_n,
+    output wire        o_sdram_wen_n,
+    output wire [ 3:0] o_sdram_dqm,
+    output wire [10:0] o_sdram_addr,
+    output wire [ 1:0] o_sdram_ba,
+    inout  wire [31:0] io_sdram_dq
+);
+
+  // ── Controller user-side wires ─────────────────────────────────────────────
+  reg         sdrc_wr_n;
+  reg         sdrc_rd_n;
+  reg  [20:0] sdrc_addr;
+  reg  [31:0] sdrc_data_in;
+  wire [31:0] sdrc_data_out;
+  wire        sdrc_init_done;
+  wire        sdrc_busy_n;
+  wire        sdrc_rd_valid;
+  wire        sdrc_wrd_ack;
+
+  // ── sdram_gw2ar instance ───────────────────────────────────────────────────
+  // Tang Nano 20K: 27 MHz, GW2AR-18 embedded SDRAM (64 Mbit, 32-bit wide).
+  // Timing parameters follow the JEDEC SDR SDRAM spec for -6 speed grade.
+  sdram_gw2ar #(
+      .DATA_WIDTH              (32),
+      .BANK_WIDTH              (2),
+      .ROW_WIDTH               (11),
+      .COLUMN_WIDTH            (8),
+      .CLOCK_FREQ_MHZ          (27),
+      .REFRESH_PERIOD_NS       (64_000_000),
+      .REFRESH_TIMES           (4096),
+      .INITIALIZATION_WAIT_PERIOD_NS(200_000),
+      .T_CL_PERIOD             (3),
+      .T_RP_PERIOD             (3),
+      .T_MRD_PERIOD            (3),
+      .T_WR_PERIOD             (3),
+      .T_RFC_PERIOD            (9),
+      .T_RCD_PERIOD            (3)
+  ) u_sdram (
+      .i_sdrc_rst_n       (i_rst_n),
+      .i_sdrc_clk         (i_clk),
+      .i_sdram_clk        (i_clk),
+      .i_sdrc_self_refresh(1'b0),
+      .i_sdrc_power_down  (1'b0),
+      .i_sdrc_wr_n        (sdrc_wr_n),
+      .i_sdrc_rd_n        (sdrc_rd_n),
+      .i_sdrc_addr        (sdrc_addr),
+      .i_sdrc_dqm         (4'b0000),
+      .i_sdrc_data_len    (8'd0),
+      .i_sdrc_data        (sdrc_data_in),
+      .o_sdrc_data        (sdrc_data_out),
+      .o_sdrc_init_done   (sdrc_init_done),
+      .o_sdrc_busy_n      (sdrc_busy_n),
+      .o_sdrc_rd_valid    (sdrc_rd_valid),
+      .o_sdrc_wrd_ack     (sdrc_wrd_ack),
+
+      .o_sdram_clk  (o_sdram_clk),
+      .o_sdram_cke  (o_sdram_cke),
+      .o_sdram_cs_n (o_sdram_cs_n),
+      .o_sdram_cas_n(o_sdram_cas_n),
+      .o_sdram_ras_n(o_sdram_ras_n),
+      .o_sdram_wen_n(o_sdram_wen_n),
+      .o_sdram_dqm  (o_sdram_dqm),
+      .o_sdram_addr (o_sdram_addr),
+      .o_sdram_ba   (o_sdram_ba),
+      .io_sdram_dq  (io_sdram_dq)
+  );
+
+  // ── Simple write-then-read-back FSM ───────────────────────────────────────
+  localparam [2:0]
+    S_WAIT_INIT = 3'd0,   // wait for controller initialisation to finish
+    S_WRITE     = 3'd1,   // issue a single-word write
+    S_WAIT_ACK  = 3'd2,   // wait for write acknowledgement
+    S_READ      = 3'd3,   // issue a single-word read
+    S_WAIT_DATA = 3'd4,   // wait for read data to be valid
+    S_DONE      = 3'd5;   // latch result, stay here
+
+  localparam [31:0] TEST_WORD    = 32'hDEAD_BEEF;
+  localparam [20:0] TEST_ADDRESS = 21'd0;
+
+  reg [2:0] state;
+
+  always @(posedge i_clk) begin
+    if (!i_rst_n) begin
+      state        <= S_WAIT_INIT;
+      sdrc_wr_n    <= 1'b1;
+      sdrc_rd_n    <= 1'b1;
+      sdrc_addr    <= 21'd0;
+      sdrc_data_in <= 32'd0;
+      o_led_ok     <= 1'b0;
+      o_led_err    <= 1'b0;
+    end else begin
+      // Default: deassert strobes every cycle so they are single-cycle pulses.
+      sdrc_wr_n <= 1'b1;
+      sdrc_rd_n <= 1'b1;
+
+      case (state)
+
+        S_WAIT_INIT: begin
+          if (sdrc_init_done && sdrc_busy_n)
+            state <= S_WRITE;
+        end
+
+        S_WRITE: begin
+          sdrc_wr_n    <= 1'b0;
+          sdrc_addr    <= TEST_ADDRESS;
+          sdrc_data_in <= TEST_WORD;
+          state        <= S_WAIT_ACK;
+        end
+
+        S_WAIT_ACK: begin
+          if (sdrc_wrd_ack)
+            state <= S_READ;
+        end
+
+        S_READ: begin
+          if (sdrc_busy_n) begin
+            sdrc_rd_n <= 1'b0;
+            sdrc_addr <= TEST_ADDRESS;
+            state     <= S_WAIT_DATA;
+          end
+        end
+
+        S_WAIT_DATA: begin
+          if (sdrc_rd_valid) begin
+            o_led_ok  <= (sdrc_data_out == TEST_WORD);
+            o_led_err <= (sdrc_data_out != TEST_WORD);
+            state     <= S_DONE;
+          end
+        end
+
+        S_DONE: begin
+          // Result latched in LEDs; stay idle.
+        end
+
+        default: state <= S_WAIT_INIT;
+      endcase
+    end
+  end
+
+endmodule  // sdram_gw2ar_example