first release of gbatang

Author: nand2mario

README.md

@@ -0,0 +1,49 @@
+
+# GBATang - GBA for Sipeed Tang FPGA boards
+
+<img src='doc/gbatang0.1.jpg' width=300 />
+
+This is a working but early-stage Gameboy Advance FPGA core for Sipeed [Tang Mega 138K](https://wiki.sipeed.com/hardware/en/tang/tang-mega-138k/mega-138k.html), [Mega 138K Pro](https://wiki.sipeed.com/hardware/en/tang/tang-mega-138k/mega-138k-pro.html) and the upcoming portable Sipeed Tang 60K board/handheld. 
+
+The core outputs 720p HDMI video, accepts DS2 controller input, and supports all ROM sizes (up to 32MB). An open source BIOS is used so it can be used out of the box. ROMs are loaded from the SD card through a convenient menu system.  Some games does not work yet. The following are some that are verified to work,
+
+* Super Mario Advance 2 (Super Mario World) 
+* F-ZERO Maximum Velocity
+* Donkey Kong Country
+* NES Classic Super Mario Brothers, IceClimber
+* and more
+
+Missing things that I expect to implement include cartridge backup, SNES controller input, game compatibility fixes and ability to use original BIOS.
+
+Follow [me](https://x.com/nand2mario) on X to get updates. Also check out other cores in the series: [SNESTang](https://github.com/nand2mario/snestang) and [NESTang](https://github.com/nand2mario/nestang).
+
+## Instructions
+
+You need the Tang Mega 138K or Tang Mega 138K Pro board. Or you can wait for the Tang retro handheld. You also need a [Tang DS2 Pmod](https://wiki.sipeed.com/hardware/en/tang/tang-PMOD/FPGA_PMOD.html), a [Tang SDRAM Pmod](https://wiki.sipeed.com/hardware/en/tang/tang-PMOD/FPGA_PMOD.html), a [DS2 controller](https://en.wikipedia.org/wiki/DualShock), and finally a MicroSD card. Then assemble the parts as shown in the picture above.
+
+Then follow these steps to install the core (for detailed instructions, for now refer to [SNESTang installation](https://github.com/nand2mario/snestang/blob/main/doc/installation.md)),
+
+1. Download and install [Gowin IDE 1.9.10.02](https://cdn.gowinsemi.com.cn/Gowin_V1.9.10.02_x64_win.zip).
+
+2. Download a [GBATang release](https://github.com/nand2mario/gbatang/releases).
+
+3. Use Gowin programmer to program `firmware.bin` to on-board flash, at starting address **0x500000**.
+
+4. Again use Gowin programmer. Program `gbatang_m138k.fs` or `gbatang_m138kpro.fs` to on-board flash at starting address 0x000000.
+
+5. Put GBA roms on the MicroSD card and insert it into the on-board MicroSD slot. Then power up the board.
+
+## About this project
+
+The project started as a port of the MiSTer GBA core to Tang FPGAs in June 2024. However, it quickly turned into a half-rewrite. By September 2024 it finally reached usable state and about half of the code is different. Here are the main differences.
+
+* The overall design is a more traditional "FPGA replica" approach, as opposed to the "cycle counting" approach in the MiSTer core. Most modules work at 16Mhz, the GBA main frequency. The MiSTer main frequency is 100Mhz. 
+* The CPU is [replaced](https://github.com/risclite/ARM9-compatible-soft-CPU-core), with missing features like 16-bit instructions added. The processor uses a similar pipelined design as the original GBA CPU.
+* The memory system is also completely rewritten, as required by the overall design change.
+* Timing accuracy could use a lot of improvements. However as a more "modern" console, GBA mostly uses interrupts and timers to keep time. So cycle-accuracy is not as important as previous consoles.
+* A softcore-based menu system is provided, similar to SNESTang and NESTang.
+
+## Acknowledgements
+* [GBA_MiSTer](https://github.com/MiSTer-devel/GBA_MiSTer)
+* [risclite's CPU core](https://github.com/risclite/ARM9-compatible-soft-CPU-core)
+

build.tcl

@@ -0,0 +1,79 @@
+add_file -type verilog "src/common/dpram32_block.v"
+add_file -type verilog "src/common/dpram_block.v"
+add_file -type verilog "src/common/dual_clk_fifo.v"
+add_file -type verilog "src/common/eprocreg_gba.sv"
+add_file -type verilog "src/common/gba_bios.sv"
+add_file -type verilog "src/cpu/gba_cpu.v"
+add_file -type verilog "src/cpu/gba_cpu_thumbdecoder.v"
+add_file -type verilog "src/cpu/gba_interrupts.v"
+add_file -type verilog "src/gba2hdmi.sv"
+add_file -type verilog "src/gbatang_top.sv"
+add_file -type verilog "src/gpu/gba_drawer_merge.v"
+add_file -type verilog "src/gpu/gba_drawer_mode0.v"
+add_file -type verilog "src/gpu/gba_drawer_mode2.v"
+add_file -type verilog "src/gpu/gba_drawer_mode345.v"
+add_file -type verilog "src/gpu/gba_drawer_obj.sv"
+add_file -type verilog "src/gpu/gba_gpu.v"
+add_file -type verilog "src/gpu/gba_gpu_colorshade.sv"
+add_file -type verilog "src/gpu/gba_gpu_drawer.v"
+add_file -type verilog "src/gpu/gba_gpu_timing.v"
+add_file -type verilog "src/gpu/gba_timer.v"
+add_file -type verilog "src/gpu/gba_timer_module.v"
+add_file -type verilog "src/gpu/vram_hi.v"
+add_file -type verilog "src/gpu/vram_lo.v"
+add_file -type verilog "src/hdmi/audio_clock_regeneration_packet.sv"
+add_file -type verilog "src/hdmi/audio_info_frame.sv"
+add_file -type verilog "src/hdmi/audio_sample_packet.sv"
+add_file -type verilog "src/hdmi/auxiliary_video_information_info_frame.sv"
+add_file -type verilog "src/hdmi/hdmi.sv"
+add_file -type verilog "src/hdmi/packet_assembler.sv"
+add_file -type verilog "src/hdmi/packet_picker.sv"
+add_file -type verilog "src/hdmi/serializer.sv"
+add_file -type verilog "src/hdmi/source_product_description_info_frame.sv"
+add_file -type verilog "src/hdmi/tmds_channel.sv"
+add_file -type verilog "src/iosys/gowin_dpb_menu.v"
+add_file -type verilog "src/iosys/iosys.v"
+add_file -type verilog "src/iosys/picorv32.v"
+add_file -type verilog "src/iosys/simplespimaster.v"
+add_file -type verilog "src/iosys/simpleuart.v"
+add_file -type verilog "src/iosys/spi_master.v"
+add_file -type verilog "src/iosys/spiflash.v"
+add_file -type verilog "src/iosys/textdisp.v"
+add_file -type verilog "src/m138k/pll_27.v"
+add_file -type verilog "src/m138k/pll_33.v"
+add_file -type verilog "src/m138k/pll_74.v"
+add_file -type verilog "src/memory/gba_dma.v"
+add_file -type verilog "src/memory/gba_dma_module.sv"
+add_file -type verilog "src/memory/gba_eeprom.sv"
+add_file -type verilog "src/memory/gba_flash_sram.sv"
+add_file -type verilog "src/memory/gba_memory.sv"
+add_file -type verilog "src/memory/mem_eeprom.v"
+add_file -type verilog "src/memory/mem_iwram.v"
+add_file -type verilog "src/memory/rv_sdram_adapter.v"
+add_file -type verilog "src/memory/sdram_gba.v"
+add_file -type verilog "src/peripherals/controller_ds2.sv"
+add_file -type verilog "src/peripherals/dualshock_controller.v"
+add_file -type verilog "src/peripherals/gba_joypad.v"
+add_file -type verilog "src/sound/gba_sound.v"
+add_file -type verilog "src/sound/gba_sound_ch1.v"
+add_file -type verilog "src/sound/gba_sound_ch3.v"
+add_file -type verilog "src/sound/gba_sound_ch4.v"
+add_file -type verilog "src/sound/gba_sound_dma.v"
+add_file -type verilog "src/test_loader.v"
+
+set_option -synthesis_tool gowinsynthesis
+set_option -top_module gbatang_top
+set_option -include_path {"src/common"}
+set_option -verilog_std sysv2017
+set_option -vhdl_std vhd2008
+set_option -ireg_in_iob 1
+set_option -oreg_in_iob 1
+set_option -ioreg_in_iob 1
+set_option -use_sspi_as_gpio 1
+set_option -use_mspi_as_gpio 1
+set_option -use_cpu_as_gpio 1
+
+# use the slower but timing-optimized place algorithm
+set_option -place_option 2
+
+run all

doc/gbatang0.1.jpg

@@ -0,0 +1,60 @@
+#
+# The xPack GNU RISC-V Embedded GCC
+# https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack
+#
+TARGET_ELF = firmware.elf
+TARGET_BIN = firmware.bin
+#RISCV = /opt/xpack-riscv-none-elf-gcc-13.2.0-2/bin/riscv-none-elf
+RISCV = /usr/local/xpack-riscv-none-embed-gcc-10.1.0-1.1/bin/riscv-none-embed
+CC = $(RISCV)-gcc
+OBJCOPY = $(RISCV)-objcopy
+OBJDUMP = $(RISCV)-objdump
+CFLAGS  = -Wall -O2 -g -mabi=ilp32 -march=rv32i -ffreestanding
+LFLAGS = -mabi=ilp32 -march=rv32i -Wl,--build-id=none,-Bstatic,-T,baremetal.ld -nostdlib
+LIBS = -lgcc
+
+SRCS := start.S firmware.c picorv32.c spi_sd.c spiflash.c \
+	fatfs/diskio.c fatfs/ff.c fatfs/ffunicode.c
+OBJS := $(SRCS:.c=.o)
+OBJS := $(OBJS:.S=.o)
+HDRS := $(wildcard *.h)
+
+ifeq ($(VERBOSE),1)
+  Q =
+else
+  Q = @
+endif
+
+default: $(TARGET_BIN)
+all: default
+
+%.o: %.c $(HDRS)
+ifneq ($(VERBOSE),1)
+	@echo CC $@
+endif
+	$(Q)$(CC) $(CFLAGS) -c $< -o $@
+
+%.o: %.S $(HDRS)
+ifneq ($(VERBOSE),1)
+	@echo CC $@
+endif
+	$(Q)$(CC) $(CFLAGS) -c $< -o $@
+
+.PRECIOUS: $(TARGET_BIN) $(TARGET_ELF) $(OBJS)
+
+$(TARGET_ELF): $(OBJS)
+ifneq ($(VERBOSE),1)
+	@echo CC $@
+endif
+	$(Q)$(CC) $(LFLAGS) $(OBJS) $(LIBS) -o $@
+
+$(TARGET_BIN): $(TARGET_ELF)
+ifneq ($(VERBOSE),1)
+	@echo OBJCOPY $@
+endif
+	$(Q)$(OBJCOPY) $(TARGET_ELF) $(TARGET_BIN) -O binary
+
+clean:
+	$(Q)rm -f $(OBJS) $(TARGET_ELF) $(TARGET_BIN)
+
+.PHONY: default all clean

firmware/Makefile

@@ -0,0 +1,53 @@
+/*
+ * linker control script for 'bare metal' executables.
+ * Ensures that _start defined in start.S is put at address 0
+ * Uses the first 2MB of RAM.
+ */
+MEMORY
+{
+    FLASH (RX): ORIGIN = 0x00000, LENGTH = 100K
+    RAM  (RWX): ORIGIN = 100K, LENGTH = 0x1e7000
+}
+SECTIONS
+{
+    .text :
+    {
+        start.o (.text)
+        *(.text)
+        _end = .;           /* as expected by syscalls.c */
+    } >FLASH
+
+    /* global and static variable with initial values */
+    .data :
+    {
+        . = ALIGN(4);
+        _sdata = .;
+        . = ALIGN(4);
+        *(.data)           /* .data sections */
+        *(.data*)          /* .data* sections */
+        *(.sdata)           /* .sdata sections */
+        *(.sdata*)          /* .sdata* sections */
+        . = ALIGN(4);
+        _edata = .;
+    }
+
+    /* global and static variables without initial values. initialized to 0 by start.S */
+    .bss :
+    {
+        . = ALIGN(4);
+        _sbss = .;         /* start of bss, used by startup code */
+        *(.bss)
+        *(.bss*)
+        *(.sbss)
+        *(.sbss*)
+        *(COMMON)
+        . = ALIGN(4);
+        _ebss = .;         /* end of bss, used by startup code */
+    }
+
+    .heap :
+    {
+        . = ALIGN(4);
+        _heap_start = .;    /* define a global symbol at heap start */
+    }
+}

firmware/baremetal.ld

@@ -0,0 +1,27 @@
+
+@REM This compiles the firmware into firmware.bin in RV32I format.
+@REM It is to be loaded at address 0.
+
+@REM Download RISC-V gcc toolchain for x64 from https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/releases/
+set CROSS=D:\opt\xpack-riscv-none-elf-gcc-13.2.0-2\bin\riscv-none-elf-
+set CFLAGS=-O -mabi=ilp32 -march=rv32i -ffreestanding
+
+%CROSS%as -mabi=ilp32 -march=rv32i -c -o start.o start.S
+%CROSS%gcc %CFLAGS% -c -o firmware.o firmware.c
+%CROSS%gcc %CFLAGS% -c -o picorv32.o picorv32.c
+%CROSS%gcc %CFLAGS% -c -o spi_sd.o spi_sd.c
+%CROSS%gcc %CFLAGS% -c -o spiflash.o spiflash.c
+
+@REM fatfs
+%CROSS%gcc %CFLAGS% -c -o fatfs\diskio.o fatfs\diskio.c
+%CROSS%gcc %CFLAGS% -c -o fatfs\ff.o fatfs\ff.c
+%CROSS%gcc %CFLAGS% -c -o fatfs\ffunicode.o fatfs\ffunicode.c
+
+%CROSS%gcc %CFLAGS% -Wl,--build-id=none,-Bstatic,-T,baremetal.ld,--strip-debug ^
+   -nostdlib -o firmware.elf start.o firmware.o picorv32.o spi_sd.o spiflash.o ^
+   fatfs\diskio.o fatfs\ff.o fatfs\ffunicode.o -lgcc
+
+%CROSS%objcopy firmware.elf firmware.bin -O binary
+@REM python bin2hexwords.py firmware.bin firmware.hex
+
+%CROSS%objdump -Mnumeric -D firmware.elf > firmware.elf.list

firmware/build.bat

@@ -0,0 +1,2 @@
+
+del *.bin *.elf *.list *.o *.hex fatfs\*.o