agra-uni-bremen/riscv-vp

1. This repository is a full RISC-V virtual prototype stack, not just a single simulator. It is split into three major areas: the simulator/runtime in vp/, example guest software in sw/, and a small Qt-based display frontend in env/basic/vp-display/.

2. The core product is the SystemC TLM-2.0 simulator under vp/. It models RV32GC and RV64GC CPUs, platform peripherals, buses, interrupts, timing, and optional debug services. The simulator is built with CMake and depends on external SystemC/Boost/softfloat components that are pulled in through submodules and local build scripts.

3. CPU execution is separated by ISA family and by common infrastructure. vp/src/core/common contains shared execution machinery such as instruction decoding, MMU/virtual memory support, trap handling, debug memory, timer/CLINT models, and the GDB remote protocol server. vp/src/core/rv32 and vp/src/core/rv64 contain the ISA-specific ISS, CSR, syscall, memory, and MMU implementations.

4. The main runtime data flow is: an ELF binary is loaded into simulated memory, the ISS executes instructions, memory accesses go through the platform bus and memory map, and traps/interrupts are routed back through the core’s trap and interrupt interfaces. Timing can be instruction-accurate or use annotated TLM delays, so the core layer is the boundary between instruction semantics and platform timing.

5. Debugging is a first-class subsystem. The gdb-mc code in vp/src/core/common implements a GDB RSP server and runner, backed by register formatting and debug memory access. This lets host GDB/Eclipse connect to a running virtual CPU for breakpoints, register inspection, and memory access without needing a physical target.

6. The platform layer in vp/src/platform/ is where SoC/board-specific integration happens. It provides multiple machine configurations such as basic, hifive, linux, tiny32, tiny64, microrv32, hwitl, and test platforms. Each platform wires a CPU core to a specific set of memories, buses, interrupts, and devices.

7. Platform peripherals are modeled as separate device classes, usually with a clear split between generic device behavior and platform integration. Examples include UARTs, GPIO, flash, display, sensor, Ethernet, CAN, PRCI/clock logic, OTP/ROM, SPI, and DMA. The basic platform is a compact integration target for demos, while hifive mirrors a HiFive1-style board with richer device modeling.

8. Interrupt and bus routing is handled by reusable platform-common abstractions. vp/src/platform/common includes bus and memory helpers, UART interfaces, SLIP/terminal support, and PLIC implementations for FE310 and FU540-style interrupt controllers. This is the main interconnect boundary between CPU cores and peripherals.

9. Some platform families are specialized for particular integration styles. linux and linux32 target host-co-simulation scenarios, hwitl bridges to a virtual bus/TLM connector for hardware-in-the-loop style setups, and test32 exists for test-oriented execution. These variants show that the platform layer is meant to swap interconnects and device sets without changing the core ISS.

10. The sw/ directory contains many small guest programs used as validation and usage examples. They cover bare-metal bootstrapping, UART and GPIO, DMA/interrupts, multicore behavior, sleep/timing, C and C++ runtime support, printf, CRC, scheduler experiments, flash/MRAM tests, and display demos. These are built with RISC-V cross toolchains and are intended to run on matching VP platform configurations.

11. Guest software and simulator communicate through the platform’s emulated peripherals and boot/runtime conventions. Many examples include custom bootstrap.S, linker scripts, and small HAL-style files for UART/GPIO/IRQ handling, showing that the repository treats firmware and simulator as a coupled system rather than independent projects.

12. The env/basic/vp-display/ application is an external GUI endpoint for interactive I/O. It is a Qt-based program that presents a framebuffer/display surface and a display server interface, which pairs with the simulator’s display or virtual breadboard features. The README notes that the fuller Virtual Breadboard GUI lives in a separate repository, so this repo only contains one concrete display integration.

13. Build and packaging are part of the architecture. Root-level Makefile, .gitlab-ci.yml, and Dockerfile support reproducible builds, while the simulator can be installed into vp/build/bin. The software examples assume a RISC-V GNU toolchain in PATH, and the Docker image bundles that toolchain for a self-contained workflow.

14. In diagram terms, the highest-level boundaries are: host build/runtime tooling; the SystemC simulator core; platform-specific SoC/board assemblies; guest firmware/software; and optional host-side debug/UI attachments such as GDB and the display frontend. The main runtime traffic is instruction fetch/execute and memory-mapped I/O between the core and platform, with asynchronous interrupts, timers, and debug connections as side channels.