VESP: "VEřejný Studentský Procesor" (public students' processor), version beta

The VESP-beta is a single-cycle RV32IMZicsr processor with M-mode and RISC-V Debug support. The VESP-beta is integrated in an SoC, the VESP Megatron, which contains several peripherals: graphical adapter with HDMI output, UART, GPIO and more.

The VESP-beta (as a part of VESP Megatron) is synthesizable on Xilinx's FPGAs. For now, the project targets Digilent's Nexys Video development board (Artix 7-200T) at 50 MHz system clock. For RTL simulation, the Siemens Questa Simulator is used.

We use FuseSoC as a build tool in this project. The major advantage of this tool is that it acts as a front-end for simulators and synthesis tools, so you usually don't have to deal with the tools directly.

Requirements

• FuseSoC
• RISC-V GCC toolchain (in $PATH)
• Python >3.10
• scanelf

Only for synthesis:

• Vivado

To load pre-generated bitstream without Vivado, you need:

• openFPGALoader

Only for simulation:

• Siemens Questa Simulator

For generating documentation:

• mkdocs

Quick Start on VESP Megatron

Note: this repository includes dependecies as git submodules. Do not forget to download all submodules before proceeding:

git submodule update --init --recursive

FPGA

Option 1: I have Vivado and/or want to run synthesis myself

Generate a bitstream for Nexys Video:

fusesoc run --target synth core

The bitstream will be available as build/hgm_vesp-ip_core_2.0.0/synth-vivado/hgm_vesp-ip_core_2.0.0.bit. The synthesis will preload the RAM with contents of the sw/bootloader/firmware.mem file. The bitstream can be loaded to the FPGA either by using Vivado, or an openFPGALoader.

Option 2: I do not have Vivado and/or want to skip synthesis

You don't have to run synthesis yourself. Just grab a pre-generated bitstream from Releases (TBA) and load the bitstream using OpenFPGALoader:

openFPGALoader -b nexysVideo <path_to_bitstream>

RTL Simulation

To run the complete VESP SoC in simulation, run:

fusesoc run generic-sw --firmware <path_to_mem_file>

To enable a virtual JTAG cable for debugging with OpenOCD+gdb as well, run:

fusesoc run debug --firmware <path_to_mem_file>

In both cases, the system RAM will be preloaded with contents of the MEM file passed as the firmware argument.

A guide on generating a mem file from your own C program is in the next section.

Your Program on VESP Megatron

1. Write a C program using the template: sw/example/template.c.

2. Compile the program and generate the mem file using the Makefile:

cd ./sw/
make firmware SRC=<path_to_c_source>

The mem file will be at: sw/firmware.mem.

3. Loading the program

• To run to program in simulation, simply run one of the RTL simulation configurations described above and pass a path to the program in mem format as a firmware argument.
• To load the program to a synthesized SoC running on the FPGA, use the Debug Module. See documentation.

Documentation

The latest documentation generated from master is available on GitHub Pages.

You can generate the HTML version yourself using mkdocs. This command will generate the docs and launch a local webserver for you:

mkdocs serve

If you need offline documentation and don't want to use mkdocs for some reason, you can just read through the Markdown source in the docs/ directory.

License

Dependencies

This project includes dependencies on external components located in the vendor/ directory and in tb/riscv-suite/riscv-tests. These components are licensed separately. Please refer to the respective README and LICENSE files within those directories for more information. All other parts of this project are licensed as described below.

License and Acknowledgements

This project is based on the VESP-alpha project, originally developed by Jan Medek and myself. VESP-alpha is licensed under the GNU General Public License version 3 (GPLv3).

This project itself is licensed under the same license. A full copy of the license text can be found in the LICENSE file. Here is a short form of the license:

    Copyright (C) 2025 Ondrej Golasowski

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <https://www.gnu.org/licenses/>.

Legal Note (in Czech)

As this project is a part of a master's thesis created at the Faculty of Information Technology of Czech Technical University in Prague, I am legally required to append also this text:

V souladu s ust. § 2373 odst. 2 zákona č. 89/2012 Sb., občanský zákoník, ve znění pozdějších předpisů, tímto
uděluji nevýhradní oprávnění (licenci) k užití tohoto autorského díla, a to včetně všech počítačových
programů a veškeré jejich dokumentace (dále souhrnně jen „Dílo“), a to všem osobám, které si přejí Dílo užít.
Tyto osoby jsou oprávněny Dílo užít jakýmkoli způsobem, který nesnižuje hodnotu Díla, a za jakýmkoli účelem (včetně užití k výdělečným účelům), musí ale zachovat platnost copyleft licence, na
kterém bylo dílo postaveno. Toto oprávnění je časově, teritoriálně i množstevně neomezené.