Firmware: Add UART loader and SDRAM instruction fetch

Add a UART loader firmware (uart_loader) that allows uploading and
running programs over UART without reflashing the FPGA. The host-side
script (scripts/uart_load.py) implements a simple binary protocol:
Load, Go, Dump, and Ping commands.

To support executing uploaded code, extend top.v so that instruction
fetches with bit 31 set are routed through the SDRAM arbiter instead
of the LUT-ROM. This allows any program loaded into SDRAM
(0x8000_0000+) to be executed directly.

Add shared firmware/link_ram.ld and firmware/start_ram.S for building
RAM-targeted binaries with the stack placed safely in SDRAM. Update
hello_world with a `make bin BIN_ADDR=0x80000000` target and a README
documenting both the bitstream-bake and UART-loader workflows.

Made-with: Cursor

Author: higuoxing

boards/tangnano20k/Makefile

@@ -21,7 +21,9 @@ all: $(BOARD).fs
 imem.hex imem_rom.vh imem_data_rom.vh: FORCE
 	make -C $(PROG_DIR)
 	cp $(PROG_DIR)/imem.hex .
-	cp $(PROG_DIR)/imem_rom.vh .
+	# Rename the assigned variable so top.v can use imem_lut_rdata as an
+	# intermediate and override it for the SDRAM instruction-fetch path.
+	sed 's/imem_rdata/imem_lut_rdata/g' $(PROG_DIR)/imem_rom.vh > imem_rom.vh
 	cp $(PROG_DIR)/imem_data_rom.vh .
 
 # ── FPGA bitstream ────────────────────────────────────────────────────────────

boards/tangnano20k/top.v

@@ -118,14 +118,32 @@ module top #(
 
   wire        o_trap;
 
-  // ── Instruction memory: combinatorial LUT-ROM ─────────────────────────────
-  // A pure combinatorial case ROM synthesises reliably to LUTs.
-  // $readmemh-based BRAM init is unreliable with the open-source Gowin flow.
+  // ── Instruction memory ────────────────────────────────────────────────────
+  // Addresses with bit 31 = 0 are served by the combinatorial LUT-ROM.
+  // Addresses with bit 31 = 1 are fetched from SDRAM via the shared data-bus
+  // arbiter — this enables uart_loader to upload and execute code in SDRAM
+  // (0x8000_0000 – 0x81FF_FFFF) without reflashing the FPGA.
   wire [9:0] imem_idx = imem_addr[11:2];
+  wire       imem_from_sdram = imem_addr[31] & imem_valid;
 
+  // LUT-ROM: combinatorial case ROM (renamed to imem_lut_rdata by the Makefile
+  // sed pass so the SDRAM mux below can override without a multiple-driver error).
+  reg [31:0] imem_lut_rdata;
   always @(*) begin
     `include "imem_rom.vh"
-    imem_ready = imem_valid;
+  end
+
+  // Final IMEM output mux.  bus_rdata / bus_rready are defined further below
+  // (after the SDRAM arbiter section); Verilog combinatorial always blocks may
+  // reference signals declared later in the file.
+  always @(*) begin
+    if (imem_from_sdram) begin
+      imem_rdata = bus_rdata;
+      imem_ready = bus_rready;
+    end else begin
+      imem_rdata = imem_lut_rdata;
+      imem_ready = imem_valid;
+    end
   end
 
   // ── Data BRAM ─────────────────────────────────────────────────────────────
@@ -136,11 +154,16 @@ module top #(
 
   wire dmem_wsel = dmem_wvalid && (dmem_waddr[19:16] == 4'b0001);
 
-  // Unified read address: PTW read takes priority when ptw_valid is asserted.
-  // The CPU is stalled (dmem_rvalid=0) during PTW walks, so no conflict arises.
-  // bus_raddr_full is declared later (after SDRAM section), alias it here for BRAM.
-  wire [31:0] bus_raddr  = ptw_valid ? ptw_addr  : dmem_raddr;
-  wire        bus_rvalid = ptw_valid ? 1'b1       : dmem_rvalid;
+  // Unified read address mux — priority: PTW > IMEM-from-SDRAM > DMEM.
+  // PTW: CPU is stalled (dmem_rvalid=0, imem_valid still set but we ignore it).
+  // IMEM-from-SDRAM: CPU is stalled at fetch; dmem_rvalid=0 during fetch stall.
+  // DMEM: normal data read.
+  wire [31:0] bus_raddr  = ptw_valid        ? ptw_addr   :
+                           imem_from_sdram   ? imem_addr  :
+                                              dmem_raddr;
+  wire        bus_rvalid = ptw_valid        ? 1'b1        :
+                           imem_from_sdram   ? 1'b1        :
+                                              dmem_rvalid;
 
   wire [9:0] dmem_raddr_idx = bus_raddr[11:2];
   wire [9:0] dmem_waddr_idx = dmem_waddr[11:2];
@@ -719,12 +742,13 @@ module top #(
     end
   end
 
-  // CPU DMEM read port: forward from shared bus when not ptw.
+  // CPU DMEM read port: forward from shared bus when not ptw or imem-sdram.
   always @(*) begin
     dmem_rdata  = bus_rdata;
-    dmem_rready = ptw_valid ? 1'b0 : bus_rready;
+    dmem_rready = (ptw_valid || imem_from_sdram) ? 1'b0 : bus_rready;
   end
 
+
   // PTW read port: combinatorial pass-through from shared bus.
   assign ptw_rdata = bus_rdata;
   assign ptw_ready = ptw_valid ? bus_rready : 1'b0;

firmware/hello_world/Makefile

@@ -10,9 +10,13 @@ LDFLAGS := -T link.ld -march=rv32i -mabi=ilp32 -nostdlib \
 
 SRCS    := start.S hello_world.c
 
+# Load address used when building a flat .bin for uart_loader.
+# Default: DMEM base.  Override: make BIN_ADDR=0x80000000
+BIN_ADDR ?= 0x00010000
+
 AWK_HEXTODEC := function hextodec(h,  i,v,c){v=0;h=toupper(h);for(i=1;i<=length(h);i++){c=index("0123456789ABCDEF",substr(h,i,1))-1;v=v*16+c};return v} {gsub(/\r/,"",$$0)}
 
-.PHONY: all clean dis
+.PHONY: all clean dis bin
 
 all: imem.hex imem_init.vh imem_rom.vh imem_data_rom.vh
 
@@ -40,6 +44,16 @@ imem_rom.vh: imem.hex
 hello_world.elf: $(SRCS) link.ld
 	$(CC) $(CFLAGS) $(LDFLAGS) -o $@ $(SRCS)
 
+# Flat binary linked at BIN_ADDR for uart_loader.
+# Uses start_ram.S (stack in SDRAM) instead of start.S (stack in DMEM).
+bin: hello_world.bin
+hello_world.bin: hello_world.c ../start_ram.S ../link_ram.ld
+	$(CC) $(CFLAGS) -T ../link_ram.ld -Wl,--defsym,RAM_BASE=$(BIN_ADDR) \
+	    -march=rv32im_zicsr -mabi=ilp32 -nostdlib -nostartfiles -Wl,--no-relax \
+	    -o hello_world_ram.elf ../start_ram.S hello_world.c
+	$(OBJCOPY) -O binary hello_world_ram.elf $@
+	@ls -la $@
+
 dis: hello_world.elf
 	$(OBJDUMP) -d $<
 
@@ -51,4 +65,5 @@ imem_data_rom.vh: imem.hex
 	    $< > $@
 
 clean:
-	rm -f hello_world.elf imem.hex imem_init.vh imem_rom.vh imem_data_rom.vh
+	rm -f hello_world.elf hello_world_ram.elf hello_world.bin \
+	    imem.hex imem_init.vh imem_rom.vh imem_data_rom.vh

firmware/hello_world/README.md

@@ -0,0 +1,75 @@
+# hello_world
+
+Repeatedly prints `Hello, world!` over UART TX every ~0.5 s.
+
+## Prerequisites
+
+- `riscv64-elf-gcc` toolchain
+- OSS CAD Suite (`yosys`, `nextpnr-himbaechel`, `gowin_pack`, `openFPGALoader`)
+- `pyserial` (`pip3 install pyserial`)
+- Tang Nano 20K connected over USB
+
+## Method 1 — Bake into FPGA bitstream (IMEM LUT-ROM)
+
+This is the traditional path. The firmware is compiled into the FPGA bitstream
+itself and runs immediately on power-up.
+
+```bash
+# Build and flash (synthesises the full SoC with hello_world in the ROM)
+make -C boards/tangnano20k FW=hello_world flash-sram
+
+# Connect to see output
+picocom -b 115200 /dev/tty.usbserial-XXXXXXXX
+```
+
+## Method 2 — Upload via UART loader (no reflash needed)
+
+The UART loader firmware sits in the IMEM LUT-ROM and accepts programs over
+UART. Programs are linked to run from SDRAM (`0x8000_0000`) where the CPU can
+both write and fetch instructions.
+
+### Step 1 — Flash the UART loader (one time only)
+
+```bash
+make -C boards/tangnano20k FW=uart_loader flash-sram
+```
+
+### Step 2 — Build the SDRAM binary
+
+```bash
+make -C firmware/hello_world bin BIN_ADDR=0x80000000
+# produces firmware/hello_world/hello_world.bin (140 bytes)
+```
+
+### Step 3 — Upload and run
+
+```bash
+python3 scripts/uart_load.py -p /dev/tty.usbserial-XXXXXXXX run \
+    firmware/hello_world/hello_world.bin 0x80000000
+```
+
+The script uploads the binary, jumps to it, and streams the program's output
+directly to your terminal. Press `Ctrl+C` to disconnect.
+
+Expected output:
+
+```
+Connected to /dev/tty.usbserial-XXXXXXXX at 115200 baud
+Loading 140 bytes to 0x80000000 (csum=0x9A)...
+  OK
+Jumping to 0x80000000...
+--- program output (Ctrl+C to exit) ---
+Hello, world!
+Hello, world!
+Hello, world!
+...
+```
+
+## Notes
+
+- The `BIN_ADDR` default is `0x00010000` (DMEM), but DMEM cannot be used for
+  instruction fetch — always use `BIN_ADDR=0x80000000` (SDRAM) with the UART
+  loader.
+- The stack is placed at `0x801F_FFFC` (top of the first 2 MiB of SDRAM) by
+  `firmware/start_ram.S`, safely above the 140-byte program image.
+- To disassemble: `make -C firmware/hello_world dis`

firmware/link_ram.ld

@@ -0,0 +1,39 @@
+/* link_ram.ld — position-independent RAM link script for uart_loader targets.
+ *
+ * Links the entire program (text + rodata + data + bss) into one contiguous
+ * region starting at RAM_BASE.  RAM_BASE must be provided on the linker
+ * command line with --defsym RAM_BASE=0x....
+ *
+ * Usage:
+ *   $(CC) ... -T ../../link_ram.ld -Wl,--defsym,RAM_BASE=0x00010000 ...
+ *
+ * Typical targets:
+ *   DMEM  : RAM_BASE = 0x00010000  (4 KiB)
+ *   SDRAM : RAM_BASE = 0x80000000  (32 MiB)
+ */
+
+ENTRY(_start)
+
+MEMORY {
+    RAM (rwx) : ORIGIN = RAM_BASE, LENGTH = 32M
+}
+
+SECTIONS {
+    .text : {
+        *(.text.start)
+        *(.text*)
+        *(.rodata*)
+    } > RAM
+
+    .data : { *(.data*) } > RAM
+
+    .bss : {
+        __bss_start = .;
+        *(.bss*)
+        *(.sbss*)
+        *(COMMON)
+        __bss_end = .;
+    } > RAM
+
+    /DISCARD/ : { *(.comment) *(.eh_frame) }
+}

firmware/start_ram.S

@@ -0,0 +1,32 @@
+/* start_ram.S — CRT0 for uart_loader-uploaded programs.
+ *
+ * Used when a firmware binary is loaded into RAM (DMEM or SDRAM) via the
+ * UART loader rather than baked into the IMEM LUT-ROM.
+ *
+ * Stack is placed at the top of the first 2 MiB of SDRAM (0x801F_FFFC).
+ * This is safe for both DMEM-loaded programs (stack is far above the code)
+ * and SDRAM-loaded programs (stack is within SDRAM, above the typical load
+ * address of 0x8000_0000).
+ *
+ * .bss is zeroed in-place (it follows .data in the same RAM region).
+ */
+
+    .section .text.start
+    .global _start
+_start:
+    /* Stack at top of first 2 MiB of SDRAM — safe for any load address */
+    li   sp, 0x801FFFFC
+
+    /* Zero .bss */
+    la   a0, __bss_start
+    la   a1, __bss_end
+1:  bge  a0, a1, 2f
+    sw   zero, 0(a0)
+    addi a0, a0, 4
+    j    1b
+2:
+    call main
+
+    /* main() returned — spin forever */
+halt:
+    j    halt

firmware/uart_loader/Makefile

@@ -0,0 +1,51 @@
+CROSS   ?= riscv64-elf
+CC      := $(CROSS)-gcc
+OBJCOPY := $(CROSS)-objcopy
+OBJDUMP := $(CROSS)-objdump
+
+CFLAGS  := -march=rv32im_zicsr -mabi=ilp32 -Os -ffreestanding -nostdlib \
+            -nostartfiles -Wall -Wextra
+LDFLAGS := -T link.ld -march=rv32im_zicsr -mabi=ilp32 -nostdlib \
+            -nostartfiles -Wl,--no-relax
+
+SRCS    := start.S uart_loader.c
+
+AWK_HEXTODEC := function hextodec(h,  i,v,c){v=0;h=toupper(h);for(i=1;i<=length(h);i++){c=index("0123456789ABCDEF",substr(h,i,1))-1;v=v*16+c};return v} {gsub(/\r/,"",$$0)}
+
+.PHONY: all clean dis
+
+all: imem.hex imem_init.vh imem_rom.vh imem_data_rom.vh
+
+imem.hex: uart_loader.elf
+	$(OBJCOPY) -O verilog --verilog-data-width=4 \
+	    --only-section=.text --only-section=.rodata \
+	    $< $@
+
+imem_init.vh: imem.hex
+	awk '$(AWK_HEXTODEC) \
+	     /^@/{addr=hextodec(substr($$0,2)); next} \
+	     {for(i=1;i<=NF;i++) printf "    imem[%d] = 32'\''h%s;\n", addr++, $$i}' \
+	    $< > $@
+
+imem_rom.vh: imem.hex
+	@printf '    case (imem_idx)\n' > $@
+	awk '$(AWK_HEXTODEC) \
+	     /^@/{addr=hextodec(substr($$0,2)); next} \
+	     {for(i=1;i<=NF;i++){gsub(/\r/,"",$$i); printf "      10'\''d%d: imem_rdata = 32'\''h%s;\n", addr++, toupper($$i)}}' \
+	    $< >> $@
+	@printf '      default: imem_rdata = 32'\''h00000013;\n    endcase\n' >> $@
+
+imem_data_rom.vh: imem.hex
+	awk '$(AWK_HEXTODEC) \
+	     /^@/{addr=hextodec(substr($$0,2)); next} \
+	     {for(i=1;i<=NF;i++){gsub(/\r/,"",$$i); printf "      10'\''d%d: dmem_imem_rdata = 32'\''h%s;\n", addr++, toupper($$i)}}' \
+	    $< > $@
+
+uart_loader.elf: $(SRCS) link.ld
+	$(CC) $(CFLAGS) $(LDFLAGS) -o $@ $(SRCS)
+
+dis: uart_loader.elf
+	$(OBJDUMP) -d $<
+
+clean:
+	rm -f uart_loader.elf imem.hex imem_init.vh imem_rom.vh imem_data_rom.vh

firmware/uart_loader/link.ld

@@ -0,0 +1,33 @@
+/* Linker script for NyanSoC firmware running on Tang Nano 20K.
+ *
+ * Memory map:
+ *   IMEM: 0x0000_0000 - 0x0000_0FFF  (4 KiB, combinatorial LUT-ROM)
+ *   DMEM: 0x0001_0000 - 0x0001_0FFF  (4 KiB, BRAM, read/write)
+ */
+
+ENTRY(_start)
+
+MEMORY {
+    IMEM (rx) : ORIGIN = 0x00000000, LENGTH = 4K
+    DMEM (rw) : ORIGIN = 0x00010000, LENGTH = 4K
+}
+
+SECTIONS {
+    .text : {
+        *(.text.start)
+        *(.text*)
+        *(.rodata*)
+    } > IMEM
+
+    .data : { *(.data*) } > DMEM
+
+    .bss : {
+        __bss_start = .;
+        *(.bss*)
+        *(.sbss*)
+        *(COMMON)
+        __bss_end = .;
+    } > DMEM
+
+    /DISCARD/ : { *(.comment) *(.eh_frame) }
+}

firmware/uart_loader/start.S

@@ -0,0 +1,31 @@
+/* start.S — CRT0 for uart_loader.
+ *
+ * Sets up stack in DMEM, installs a minimal trap handler, zeroes .bss,
+ * calls main().  The loader never enables interrupts so the trap handler
+ * is just a safety net.
+ */
+
+    .section .text.start
+    .global _start
+_start:
+    li   sp, 0x00010FFC
+
+    la   t0, trap_handler
+    csrw mtvec, t0
+
+    /* Zero .bss */
+    la   a0, __bss_start
+    la   a1, __bss_end
+1:  bge  a0, a1, 2f
+    sw   zero, 0(a0)
+    addi a0, a0, 4
+    j    1b
+2:
+    call main
+
+halt:
+    j    halt
+
+    .balign 4
+trap_handler:
+    mret