# vortexgpgpu/vortex architecture

> Architecture diagram of the GitHub repository vortexgpgpu/vortex, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vortexgpgpu/vortex
- Repository: https://github.com/vortexgpgpu/vortex

## Overview

##### Main Components
- Simulation Backends (sim): Several simulation environments exist, for instance, simx (C++ based simulation), rtlsim, opaesim, and XRt simulation. These define the cycle-accurate or functional simulation paths.
- Runtime & Driver Infrastructure (runtime, kernel): The runtime folder contains kernel runtime libraries and host-side drivers that interface with the hardware or simulators. In addition, the kernel folder provides support libraries and scripts (including linker scripts and intrinsics) for the actual GPU execution.
- Testing and CI (tests, ci): Comprehensive regression, unit tests, and continuous integration scripts to automate builds and simulations.
- Build and Configuration Tools: Files such as configure, Makefiles, and various CI scripts orchestrate the build, toolchain installation, environment settings, and dependency management.

##### Relationships and Data Flow
- The Host Driver/Runtime Layer initiates the GPU kernel execution and interacts with whichever simulation backend or physical FPGA is selected. The driver script (located in “ci” as well as the host driver scripts in the top level “driver” or “runtime” folders) configures the target environment.
- The simulation subsystem is triggered by user selection – for example, simx is used during rapid prototyping. It interfaces with abstract models of the GPU cores and memory hierarchy.
- In a production environment (or for hardware validation), the RTL design (in hw/rtl and related subdirectories) synthesizes to FPGA bitstreams. Toolchain scripts (e.g., in “ci/toolchain_install.sh” and “ci/toolchain_env.sh”) set up the environment for compiling and deploying to the physical device.
- Testing and continuous integration modules (in tests and ci) are connected to every major component to validate design changes, simulate runtime traces (for debugging as per docs/debugging.md), and run regression benchmarks.

##### Architectural Patterns and Design Principles
- Modularity and Configurability: The architecture is split along functional boundaries (hardware kernels, simulation models, runtime libraries, and testing) while being highly configurable with options for different pipeline widths, core counts, cache hierarchies, etc.
- Multi-Layer Abstraction: There is clear separation between low-level hardware implementation (RTL source code) and high-level software drivers (runtime libraries, OpenCL support, host-side kernel drivers). This separation allows rapid prototyping in a simulator (simx) before migrating to an RTL or FPGA implementation.
- Multi-Backend Integration: The same high-level interface (driver script) selects among different backend implementations (e.g., C++ simulation, RTL simulation, or FPGA execution) using conditional flows in the code.

##### Final Assembly
- Below the “Hardware Implementation Block,” further subdivide into modules representing the GPU core microarchitecture (ALU, FPU, LSU units, caches, etc.) as seen in hw/rtl and hw/libs.
- Parallel to this, show the “Simulation” branch subdividing into simx, rtlsim, opaesim, and xrt—which the developer uses for prototyping, testing, and eventual deployment on FPGA.
- CI and regression testing tools with all these layers.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Runtime & Drivers Layer
    subgraph "Runtime & Drivers"
        R1["Host Drivers\n(runtime)"]:::runtime
        R2["GPU Kernel Libraries\n(kernel)"]:::runtime
    end

    %% Backend Selector
    M["Backend Selector"]:::selector

    %% Simulation Backends
    subgraph "Simulation Backends"
        S1["simx"]:::simulation
        S2["rtlsim"]:::simulation
        S3["opaesim"]:::simulation
        S4["XRt Simulation"]:::simulation
    end

    %% Hardware Implementation
    subgraph "Hardware Implementation"
        H1["Hardware RTL\n(Vortex Core, Cache, FPU, etc.)"]:::hardware
        H2["DPI Sources"]:::hardware
        H3["Synthesis Scripts"]:::hardware
        H4["Supporting Scripts"]:::hardware
    end

    %% Tests & CI
    subgraph "Tests & CI"
        T1["Regression & Unit Tests\n(tests)"]:::ci
        T2["CI & Toolchain Scripts\n(ci)"]:::ci
    end

    %% Build & Config Tools
    subgraph "Build & Config Tools"
        B1["configure"]:::build
        B2["Makefile.in"]:::build
        B3["config.mk.in"]:::build
    end

    %% Connections from Runtime & Drivers to Backend Selector
    R1 -->|"routes"| M
    R2 -->|"routes"| M

    %% Backend Selector to Simulation Engines
    M -->|"select_sim"| S1
    M -->|"select_sim"| S2
    M -->|"select_sim"| S3
    M -->|"select_sim"| S4

    %% Backend Selector to Hardware Implementation
    M -->|"select_hw"| H1

    %% Hardware Implementation internal breakdown
    H1 -->|"includes"| H2
    H1 -->|"includes"| H3
    H1 -->|"includes"| H4

    %% Simulation and Hardware to Tests
    S1 -->|"simulate"| T1
    S2 -->|"simulate"| T1
    S3 -->|"simulate"| T1
    S4 -->|"simulate"| T1
    H1 -->|"validate"| T1

    %% Tests CI flow
    T1 -->|"CI_step"| T2
    T2 -->|"feedback"| R1

    %% Tests triggering Build & Config Tools
    T2 -->|"trigger"| B1
    T2 -->|"trigger"| B2
    T2 -->|"trigger"| B3

    %% Styles Definitions
    classDef runtime fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef simulation fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef hardware fill:#FFC0CB,stroke:#333,stroke-width:2px;
    classDef ci fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef build fill:#FFA07A,stroke:#333,stroke-width:2px;
    classDef selector fill:#D3D3D3,stroke:#333,stroke-width:2px;

    %% Click Events
    click R1 "https://github.com/vortexgpgpu/vortex/tree/master/runtime/"
    click R2 "https://github.com/vortexgpgpu/vortex/tree/master/kernel/"
    click H1 "https://github.com/vortexgpgpu/vortex/tree/master/hw/rtl"
    click H2 "https://github.com/vortexgpgpu/vortex/tree/master/hw/dpi"
    click H3 "https://github.com/vortexgpgpu/vortex/tree/master/hw/syn"
    click H4 "https://github.com/vortexgpgpu/vortex/tree/master/hw/scripts"
    click S1 "https://github.com/vortexgpgpu/vortex/tree/master/sim/simx"
    click S2 "https://github.com/vortexgpgpu/vortex/tree/master/sim/rtlsim"
    click S3 "https://github.com/vortexgpgpu/vortex/tree/master/sim/opaesim"
    click S4 "https://github.com/vortexgpgpu/vortex/tree/master/sim/xrtsim"
    click T1 "https://github.com/vortexgpgpu/vortex/tree/master/tests/"
    click T2 "https://github.com/vortexgpgpu/vortex/tree/master/ci/"
    click B1 "https://github.com/vortexgpgpu/vortex/tree/master/configure"
    click B2 "https://github.com/vortexgpgpu/vortex/blob/master/Makefile.in"
    click B3 "https://github.com/vortexgpgpu/vortex/blob/master/config.mk.in"
```
