NEORV32 RISC-V Softcore with Ada HAL

Note: This is a fork of stnolting/neorv32-setups with curated instructions and repository structure optimized for Ada firmware development with neorv32-hal. The original repository contains setups for many more FPGA boards.

This repository provides FPGA setups for the NEORV32 RISC-V Processor with Ada firmware support through neorv32-hal (included as a submodule).

Supported FPGA Boards

This guide covers three development boards:

Board	FPGA	Toolchain	Setup Location
Digilent Basys3	Xilinx Artix-7 XC7A35TCPG236-1	Vivado	vivado/basys3-a7-test-setup
ULX3S	Lattice ECP5 LFE5U-85F	Open Source (GHDL/Yosys/nextPNR)	osflow
Sipeed Tang Nano 9K	Gowin GW1NR-9 GW1NR-LV9QN88PC6/I5	Gowin EDA	gowineda/tang-nano-9k

---

Getting Started

Important: This repository uses Git submodules. You must clone with submodules to get the complete project.

Clone this repository with submodules:

git clone --recurse-submodules https://github.com/GNAT-Academic-Program/neorv32-setups.git
cd neorv32-setups

---

Building the Softcore

Option 1: Digilent Basys3 (Xilinx Vivado)

Prerequisites: Xilinx Vivado installed

1. Navigate to the Basys3 setup directory:

   cd vivado/basys3-a7-test-setup

2. Generate the bitstream:

   vivado -mode batch -source create_project.tcl

3. Program the FPGA:

   vivado -mode batch -source program_bitstream.tcl

4. Connect via UART at 19200 baud, 8N1 (USB-UART appears as /dev/ttyUSB0 or COM* on Windows)

See vivado/basys3-a7-test-setup/README.md for details.

---

Option 2: ULX3S (Open Source Toolchain)

Prerequisites: Docker installed

1. Pull the neorv32/impl container (includes GHDL, Yosys, nextPNR):

   docker pull ghcr.io/stnolting/neorv32/impl:latest

2. Run the container:

   docker run --rm -it -v "$(pwd)":/workspace ghcr.io/stnolting/neorv32/impl bash
   cd /workspace

3. Build the bitstream:

   cd osflow
   make BOARD=ULX3S MinimalBoot

4. Program the board using fujprog:

   fujprog neorv32_ULX3S_MinimalBoot.bit

See osflow/README.md for more targets and details.

---

Option 3: Tang Nano 9K (Gowin EDA)

Prerequisites: Gowin EDA installed

1. Navigate to the Tang Nano 9K setup directory:

   cd gowineda/tang-nano-9k

2. Open the project in Gowin EDA IDE

3. Generate and program the bitstream using Gowin Programmer

See gowineda/tang-nano-9k/README.md for details.

---

Building Ada Firmware

Prerequisites

1. Install Alire (Ada package manager): alire.ada.dev

2. Ensure RISC-V toolchain is in PATH (installed automatically by Alire):

   Linux/macOS:

   export PATH="$PATH:~/.local/share/alire/toolchains/gnat_riscv64_elf_*/bin"

   Add to ~/.bashrc or ~/.zshrc to make permanent.

   Windows (PowerShell):

   $env:PATH += ";$env:USERPROFILE\.local\share\alire\toolchains\gnat_riscv64_elf_*\bin"

   Add to PowerShell profile or set permanently via System Environment Variables.

3. Build and install the bootloader image generator:

   Linux/macOS:

   cd neorv32/sw/image_gen
   gcc image_gen.c -o image_gen
   sudo cp image_gen /usr/local/bin/

   Windows (PowerShell/CMD):

   cd neorv32\sw\image_gen
   gcc image_gen.c -o image_gen.exe

   Then manually copy image_gen.exe to a directory in your PATH (e.g., C:\Windows\System32) or add the current directory to your PATH.

Build the Demo Firmware

The neorv32-hal repository is already included as a submodule in this fork.

1. Navigate to the demos directory:

   cd neorv32-hal/demos

2. Build the firmware using the provided scripts:

   For application binary (to upload via bootloader):

   Linux/macOS:

   ./build_app_bin.sh

   Windows:

   build_app_bin.bat

   This script builds the Ada firmware with Alire and converts it to the NEORV32 executable format (bin/bios.exe) that can be uploaded via the bootloader.

   For bootloader VHDL image (to synthesize into bitstream):

   1. Edit the linker script neorv32-hal/src/link.ld:

      Change the ROM origin from:

      rom (rx) : ORIGIN = 0x0, LENGTH = 0x10000
      

      To:

      rom (rx) : ORIGIN = 0xFFE00000, LENGTH = 0x10000
      

   2. Run the build script:

      Linux/macOS:

      ./build_bld_vhd.sh

      Windows:

      build_bld_vhd.bat

   This script builds the Ada firmware and generates a VHDL file (neorv32/rtl/core/neorv32_bootloader_image.vhd) that will be synthesized directly into the FPGA bitstream as the bootloader ROM.

Upload Firmware to FPGA

Linux

1. Install gtkterm:

   sudo apt install gtkterm

2. Connect to bootloader:

   gtkterm --port /dev/ttyUSB0 --speed 19200

   Set CR LF auto in Configuration menu.

3. Upload firmware:

   • Type u at CMD:> prompt
   • Press Ctrl+Shift+R and select bin/bios.exe
   • After upload completes, type e to execute

Windows

1. Install Tera Term: Download from teratermproject.github.io

2. Connect to bootloader:

   • Open Tera Term
   • Select your COM port (e.g., COM3)
   • Set speed to 19200 baud, 8N1
   • Go to Setup → Terminal → Set "New-line" to "Receive: AUTO" and "Transmit: CR+LF"

3. Upload firmware:

   • Type u at CMD:> prompt
   • Go to File → Transfer → XMODEM → Send
   • Select bin\bios.exe
   • After upload completes, type e to execute

---

Using neorv32_hal in Your Ada Projects

For information on integrating neorv32_hal into your own Ada projects, see the neorv32-hal README.

---

Additional Resources

• NEORV32 Documentation
• neorv32-hal Repository
• Ada Blog Post: Open Source Ada from Gateware to Application
• NEORV32 User Guide
• Original neorv32-setups Repository

License

See LICENSE for details.