# agra-uni-bremen/riscv-vp architecture

> Architecture diagram of the GitHub repository agra-uni-bremen/riscv-vp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/agra-uni-bremen/riscv-vp
- Repository: https://github.com/agra-uni-bremen/riscv-vp

## Overview

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.

Main entry points: [`vp/CMakeLists.txt`](https://github.com/agra-uni-bremen/riscv-vp/blob/master/vp/CMakeLists.txt) (VP Build), [`vp/src/platform/common`](https://github.com/agra-uni-bremen/riscv-vp/tree/master/vp/src/platform/common) (Platform Common), [`sw`](https://github.com/agra-uni-bremen/riscv-vp/tree/master/sw) (Guest SW), [`vp/src/core/common`](https://github.com/agra-uni-bremen/riscv-vp/tree/master/vp/src/core/common) (Core Common)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_tooling["Tooling"]
  node_n_build["Build<br/>host tooling"]
  node_n_container["Container<br/>packaging"]
end

subgraph group_grp_vp["Simulator"]
  node_n_vp_cmake["VP Build<br/>cmake build<br/>[CMakeLists.txt]"]
  node_n_core_common["Core Common<br/>shared ISS runtime"]
  node_n_gdb["GDB Server<br/>debug service"]
  node_n_core_rv32["RV32 Core<br/>rv32 ISS"]
  node_n_core_rv64["RV64 Core<br/>rv64 ISS"]
  node_n_platform_common["Platform Common<br/>bus + irq"]
  node_n_basic["Basic SoC<br/>platform"]
  node_n_hifive["HiFive SoC<br/>platform"]
  node_n_linux["Linux Host<br/>platform"]
  node_n_linux32["Linux32 Host<br/>platform"]
  node_n_hwitl["HW-in-Loop<br/>platform bridge"]
  node_n_tiny32["Tiny32<br/>platform"]
  node_n_tiny64["Tiny64<br/>platform"]
  node_n_microrv32["MicroRV32<br/>platform"]
  node_n_test32["Test32<br/>platform"]
end

subgraph group_grp_sw["Guest SW"]
  node_n_sw["Guest SW<br/>firmware examples"]
  node_n_basic_c["Boot C<br/>bare-metal app"]
  node_n_uart_gpio["UART/GPIO<br/>bare-metal app"]
  node_n_debug_sw["Debug Demo<br/>debug workload"]
  node_n_sched["Scheduler<br/>runtime experiment"]
  node_n_display_sw["Display Demo<br/>display workload"]
end

subgraph group_grp_env["Host UI"]
  node_n_vp_display["VP Display<br/>qt frontend"]
end

node_n_build -->|"drives"| node_n_vp_cmake
node_n_container -->|"packages"| node_n_build
node_n_vp_cmake -->|"builds"| node_n_core_common
node_n_vp_cmake -->|"builds"| node_n_core_rv32
node_n_vp_cmake -->|"builds"| node_n_core_rv64
node_n_vp_cmake -->|"builds"| node_n_platform_common
node_n_vp_cmake -->|"builds"| node_n_basic
node_n_vp_cmake -->|"builds"| node_n_hifive
node_n_vp_cmake -->|"builds"| node_n_linux
node_n_vp_cmake -->|"builds"| node_n_linux32
node_n_vp_cmake -->|"builds"| node_n_hwitl
node_n_vp_cmake -->|"builds"| node_n_tiny32
node_n_vp_cmake -->|"builds"| node_n_tiny64
node_n_vp_cmake -->|"builds"| node_n_microrv32
node_n_vp_cmake -->|"builds"| node_n_test32
node_n_core_common -->|"provides"| node_n_gdb
node_n_core_common -->|"interfaces"| node_n_platform_common
node_n_core_rv32 -->|"extends"| node_n_core_common
node_n_core_rv64 -->|"extends"| node_n_core_common
node_n_platform_common -->|"assembles"| node_n_basic
node_n_platform_common -->|"assembles"| node_n_hifive
node_n_platform_common -->|"assembles"| node_n_linux
node_n_platform_common -->|"assembles"| node_n_hwitl
node_n_sw -->|"contains"| node_n_basic_c
node_n_sw -->|"contains"| node_n_uart_gpio
node_n_sw -->|"contains"| node_n_debug_sw
node_n_sw -->|"contains"| node_n_sched
node_n_sw -->|"contains"| node_n_display_sw
node_n_display_sw -->|"connects to"| node_n_vp_display
node_n_debug_sw -->|"connects to"| node_n_gdb
node_n_basic_c -->|"targets"| node_n_basic
node_n_uart_gpio -->|"targets"| node_n_microrv32

click node_n_build "https://github.com/agra-uni-bremen/riscv-vp/tree/master/Makefile"
click node_n_container "https://github.com/agra-uni-bremen/riscv-vp/tree/master/Dockerfile"
click node_n_vp_cmake "https://github.com/agra-uni-bremen/riscv-vp/blob/master/vp/CMakeLists.txt"
click node_n_core_common "https://github.com/agra-uni-bremen/riscv-vp/tree/master/vp/src/core/common"
click node_n_gdb "https://github.com/agra-uni-bremen/riscv-vp/tree/master/vp/src/core/common/gdb-mc"
click node_n_core_rv32 "https://github.com/agra-uni-bremen/riscv-vp/tree/master/vp/src/core/rv32"
click node_n_core_rv64 "https://github.com/agra-uni-bremen/riscv-vp/tree/master/vp/src/core/rv64"
click node_n_platform_common "https://github.com/agra-uni-bremen/riscv-vp/tree/master/vp/src/platform/common"
click node_n_basic "https://github.com/agra-uni-bremen/riscv-vp/tree/master/vp/src/platform/basic"
click node_n_hifive "https://github.com/agra-uni-bremen/riscv-vp/tree/master/vp/src/platform/hifive"
click node_n_linux "https://github.com/agra-uni-bremen/riscv-vp/tree/master/vp/src/platform/linux"
click node_n_linux32 "https://github.com/agra-uni-bremen/riscv-vp/tree/master/vp/src/platform/linux32"
click node_n_hwitl "https://github.com/agra-uni-bremen/riscv-vp/tree/master/vp/src/platform/hwitl"
click node_n_tiny32 "https://github.com/agra-uni-bremen/riscv-vp/tree/master/vp/src/platform/tiny32"
click node_n_tiny64 "https://github.com/agra-uni-bremen/riscv-vp/tree/master/vp/src/platform/tiny64"
click node_n_microrv32 "https://github.com/agra-uni-bremen/riscv-vp/tree/master/vp/src/platform/microrv32"
click node_n_test32 "https://github.com/agra-uni-bremen/riscv-vp/tree/master/vp/src/platform/test32"
click node_n_sw "https://github.com/agra-uni-bremen/riscv-vp/tree/master/sw"
click node_n_basic_c "https://github.com/agra-uni-bremen/riscv-vp/tree/master/sw/basic-c"
click node_n_uart_gpio "https://github.com/agra-uni-bremen/riscv-vp/tree/master/sw/basic-gpio"
click node_n_debug_sw "https://github.com/agra-uni-bremen/riscv-vp/tree/master/sw/basic-debug"
click node_n_sched "https://github.com/agra-uni-bremen/riscv-vp/tree/master/sw/simple-scheduler"
click node_n_display_sw "https://github.com/agra-uni-bremen/riscv-vp/tree/master/sw/simple-display"
click node_n_vp_display "https://github.com/agra-uni-bremen/riscv-vp/tree/master/env/basic/vp-display"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_build,node_n_container toneBlue
class node_n_vp_cmake,node_n_core_common,node_n_gdb,node_n_core_rv32,node_n_core_rv64,node_n_platform_common,node_n_basic,node_n_hifive,node_n_linux,node_n_linux32,node_n_hwitl,node_n_tiny32,node_n_tiny64,node_n_microrv32,node_n_test32 toneAmber
class node_n_sw,node_n_basic_c,node_n_uart_gpio,node_n_debug_sw,node_n_sched,node_n_display_sw toneMint
class node_n_vp_display toneRose
```

## Components

### Tooling

Host-side build and packaging support.

- [Build](https://github.com/agra-uni-bremen/riscv-vp/tree/master/Makefile): host tooling · Top-level build, CI, and container workflow. · `Makefile`
- [Container](https://github.com/agra-uni-bremen/riscv-vp/tree/master/Dockerfile): packaging · Reproducible build environment for toolchains and simulator setup. · `Dockerfile`

### Simulator

SystemC/TLM virtual prototype core and platform assemblies.

- [VP Build](https://github.com/agra-uni-bremen/riscv-vp/blob/master/vp/CMakeLists.txt): cmake build · CMake entrypoint for the virtual prototype stack. · `vp/CMakeLists.txt`
- [Core Common](https://github.com/agra-uni-bremen/riscv-vp/tree/master/vp/src/core/common): shared ISS runtime · Instruction decoding, MMU, traps, timer, debug memory, ELF loading, and GDB RSP support. · `vp/src/core/common`
- [GDB Server](https://github.com/agra-uni-bremen/riscv-vp/tree/master/vp/src/core/common/gdb-mc): debug service · Remote GDB server and runner used for host debugger attachment. · `vp/src/core/common/gdb-mc`
- [RV32 Core](https://github.com/agra-uni-bremen/riscv-vp/tree/master/vp/src/core/rv32): rv32 ISS · RV32GC execution, CSR, syscall, memory, and MMU implementation. · `vp/src/core/rv32`
- [RV64 Core](https://github.com/agra-uni-bremen/riscv-vp/tree/master/vp/src/core/rv64): rv64 ISS · RV64GC execution, CSR, syscall, memory, and MMU implementation. · `vp/src/core/rv64`
- [Platform Common](https://github.com/agra-uni-bremen/riscv-vp/tree/master/vp/src/platform/common): bus + irq · Reusable bus, memory, UART, SLIP, and interrupt-controller abstractions. · `vp/src/platform/common`
- [Basic SoC](https://github.com/agra-uni-bremen/riscv-vp/tree/master/vp/src/platform/basic): platform · Compact demo platform with display, Ethernet, sensor, flash, DMA, and timer integration. · `vp/src/platform/basic`
- [HiFive SoC](https://github.com/agra-uni-bremen/riscv-vp/tree/master/vp/src/platform/hifive): platform · HiFive1-style board platform with GPIO, CAN, SPI, PRCI, OTP/ROM, OLED, and UART tunnel. · `vp/src/platform/hifive`
- [Linux Host](https://github.com/agra-uni-bremen/riscv-vp/tree/master/vp/src/platform/linux): platform · Host-co-simulation platform for Linux-oriented integration. · `vp/src/platform/linux`
- [Linux32 Host](https://github.com/agra-uni-bremen/riscv-vp/tree/master/vp/src/platform/linux32): platform · 32-bit Linux-oriented platform variant. · `vp/src/platform/linux32`
- [HW-in-Loop](https://github.com/agra-uni-bremen/riscv-vp/tree/master/vp/src/platform/hwitl): platform bridge · Virtual bus/TLM connector for hardware-in-the-loop setups. · `vp/src/platform/hwitl`
- [Tiny32](https://github.com/agra-uni-bremen/riscv-vp/tree/master/vp/src/platform/tiny32): platform · Minimal 32-bit platform configuration. · `vp/src/platform/tiny32`
- [Tiny64](https://github.com/agra-uni-bremen/riscv-vp/tree/master/vp/src/platform/tiny64): platform · Minimal 64-bit platform configuration. · `vp/src/platform/tiny64`
- [MicroRV32](https://github.com/agra-uni-bremen/riscv-vp/tree/master/vp/src/platform/microrv32): platform · Small RV32 platform with LED, GPIO, and UART device set. · `vp/src/platform/microrv32`
- [Test32](https://github.com/agra-uni-bremen/riscv-vp/tree/master/vp/src/platform/test32): platform · Test-oriented 32-bit platform with HTIF support. · `vp/src/platform/test32`

### Guest SW

Example firmware and validation programs for target platforms.

- [Guest SW](https://github.com/agra-uni-bremen/riscv-vp/tree/master/sw): firmware examples · Guest programs and validation workloads for the simulator platforms. · `sw`
- [Boot C](https://github.com/agra-uni-bremen/riscv-vp/tree/master/sw/basic-c): bare-metal app · Simple C bootstrapping example for basic platform bring-up. · `sw/basic-c`
- [UART/GPIO](https://github.com/agra-uni-bremen/riscv-vp/tree/master/sw/basic-gpio): bare-metal app · Peripheral-oriented guest code for UART and GPIO interaction. · `sw/basic-gpio`
- [Debug Demo](https://github.com/agra-uni-bremen/riscv-vp/tree/master/sw/basic-debug): debug workload · Guest used to exercise remote debugging workflows. · `sw/basic-debug`
- [Scheduler](https://github.com/agra-uni-bremen/riscv-vp/tree/master/sw/simple-scheduler): runtime experiment · C and no-clib scheduler and coroutine experiments. · `sw/simple-scheduler`
- [Display Demo](https://github.com/agra-uni-bremen/riscv-vp/tree/master/sw/simple-display): display workload · Guest application for display-oriented integration. · `sw/simple-display`

### Host UI

Optional host-side interactive display frontend.

- [VP Display](https://github.com/agra-uni-bremen/riscv-vp/tree/master/env/basic/vp-display): qt frontend · Qt-based host display surface and display server endpoint. · `env/basic/vp-display`

## Connections

- Build → VP Build: drives · Root build delegates simulator compilation to CMake.
- Container → Build: packages · Container image provides a reproducible build environment.
- VP Build → Core Common: builds · Simulator build includes shared runtime core components.
- VP Build → RV32 Core: builds · Simulator build includes the RV32 ISA backend.
- VP Build → RV64 Core: builds · Simulator build includes the RV64 ISA backend.
- VP Build → Platform Common: builds · Simulator build includes shared platform interconnect code.
- VP Build → Basic SoC: builds · Simulator build includes the basic platform target.
- VP Build → HiFive SoC: builds · Simulator build includes the HiFive-style target.
- VP Build → Linux Host: builds · Simulator build includes Linux host-co-simulation target.
- VP Build → Linux32 Host: builds · Simulator build includes 32-bit Linux target.
- VP Build → HW-in-Loop: builds · Simulator build includes HW-in-the-loop target.
- VP Build → Tiny32: builds · Simulator build includes tiny 32-bit target.
- VP Build → Tiny64: builds · Simulator build includes tiny 64-bit target.
- VP Build → MicroRV32: builds · Simulator build includes MicroRV32 target.
- VP Build → Test32: builds · Simulator build includes test-oriented target.
- Core Common → GDB Server: provides · Shared core layer exposes the GDB remote debugging service.
- Core Common → Platform Common: interfaces · Shared core executes through platform memory, interrupt, and bus abstractions.
- RV32 Core → Core Common: extends · RV32 backend uses common decode, trap, MMU, and debug machinery.
- RV64 Core → Core Common: extends · RV64 backend uses common decode, trap, MMU, and debug machinery.
- Platform Common → Basic SoC: assembles · Basic platform reuses shared bus, UART, and interrupt helpers.
- Platform Common → HiFive SoC: assembles · HiFive platform reuses shared bus, UART, and interrupt helpers.
- Platform Common → Linux Host: assembles · Linux platform reuses shared bus, UART, and interrupt helpers.
- Platform Common → HW-in-Loop: assembles · HW-in-the-loop platform reuses shared bus, UART, and interrupt helpers.
- Guest SW → Boot C: contains · Guest software includes bare-metal boot examples.
- Guest SW → UART/GPIO: contains · Guest software includes peripheral interaction examples.
- Guest SW → Debug Demo: contains · Guest software includes remote debug validation workloads.
- Guest SW → Scheduler: contains · Guest software includes scheduler and coroutine experiments.
- Guest SW → Display Demo: contains · Guest software includes display-focused demos.
- Display Demo → VP Display: connects to · Display guest pairs with the Qt display frontend/server.
- Debug Demo → GDB Server: connects to · Debug guest pairs with the GDB RSP server.
- Boot C → Basic SoC: targets · Boot example is intended for the basic platform.
- UART/GPIO → MicroRV32: targets · Peripheral demo is intended for small board-style platforms.