# riscv-software-src/riscv-perf-model architecture

> Architecture diagram of the GitHub repository riscv-software-src/riscv-perf-model, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/riscv-software-src/riscv-perf-model
- Repository: https://github.com/riscv-software-src/riscv-perf-model

## Overview

Based on our analysis of the file structure and the README, Olympia is an out-of-order RISC-V CPU performance simulator built in C++ using the Sparta Modeling Framework. It is a trace-driven simulator that “runs” traces (in JSON or STF format) through various CPU pipeline components (like fetch, decode, dispatch, rename, execute, LSU, and vector units) while accepting configuration (via YAML and command‐line switches) and generating detailed simulation reports and performance event logs.

##### Main components of the system
- Simulator Core: This is the heart of the simulator, represented by the “sim” module (see sim/OlympiaSim.cpp) that loads trace inputs and drives simulation.
- CPU Core Model: Organized under the “core” directory, this includes submodules for:
– Fetch: Fetch unit (core/fetch) which contains modules like ICache and branch prediction (BranchPredIF).
– Decode: Decode unit (core/decode) for interpreting instructions and handling fusion (see FusionDecode.cpp, MavisUnit.cpp).
– Dispatch: Dispatch unit (core/dispatch) managing the distribution of instructions.
– Rename: Rename unit (core/rename) which is responsible for register renaming and dependency handling.
– Execute: Execute, including execution pipelines (core/execute) which cover unit operations such as ALU and FPU functions.
– LSU: Load-store unit (core/lsu) for memory operations including DCache functionalities.
– Vector Unit: Specific modules in core/vector handle vector instruction execution.
- Memory/Cache Subsystem: In addition to the core memory instructions, the simulation includes L2 caches and cache coherence elements (see mss/ and caches in core/).
- Architecture Configurations: The “arches” directory holds YAML files and JSON trace inputs for different core configurations (small_core, medium_core, big_core, fusion variants). These files define pipeline mappings, issue queue configurations, and rename mappings.
- Reporting and Logging: The simulation has built-in mechanisms for generating logs, performance events (PEvents), and reports (see reports directory and relevant command-line options). This includes report generation (core_report.def, core_timeseries.def) and log settings.
- Auxiliary Tools: There are helper scripts and supporting files (e.g., generation of configuration files, STF trace generation in traces/stf_trace_gen, and Python scripts for plotting in reports).

##### Architectural Patterns and Design Principles
- The simulator is designed using modular pipeline components. Each pipeline stage (fetch, decode, dispatch, rename, execute) is implemented in its own subdirectory with independently compiled C++ files.
- The design supports extensibility—new instructions or modules (e.g., branch prediction or prefetching enhancements) can be added easily. Indicate extension points where further customization is allowed.
- Integration with external systems (Sparta Modeling Framework, STF trace tools) should be visually represented as dependency components.

##### Technology and Tools
- C++ (core simulation modules, CPU core modeling)
- CMake (build management)
- Python (for processing reports and visualization, e.g., in reports/plot_ts.py)
- YAML/JSON (for configuration and traces)
- Concurrency aspects could be highlighted if applicable.

##### Essential Elements
- Clear labels for each primary block:
– Simulator Entry Point ("Olympia Simulator")
– CPU Pipeline stages: Fetch, Decode, Dispatch, Rename, Issue Queues, Execute, LSU, Vector
– Memory subsystem / L2 Cache (MSS)
– Reporting & Logging (PEvents, Report Generation)
– Configuration and Architecture files (arches directory)
– External Dependencies (Sparta, STF, conda environment)
– Show the instruction flow through the CPU pipeline.
– Indicate configuration inputs and output reporting flows.
- Annotations:
– Add notes for pipeline mapping and renaming strategy as seen in the README examples.
– Highlight that the simulator supports multiple core configurations (e.g., small, medium, and big core) based on the YAML configuration files.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Inputs
    TI("Trace Input (JSON/STF)"):::input
    CFG("Configuration (YAML/CLI)"):::input
    ARCHCFG("Architecture Configurations"):::config

    %% Simulator Entry Point
    OS("Olympia Simulator"):::sim

    %% CPU Core Model Subgraph
    subgraph "CPU Core Model"
        F("Fetch Unit"):::pipeline
        D("Decode Unit"):::pipeline
        DIS("Dispatch Unit"):::pipeline
        R("Rename Unit"):::pipeline
        IQ("Issue Queues"):::pipeline
        EX("Execute Unit"):::pipeline
        LSU("LSU"):::pipeline
        V("Vector Unit"):::pipeline
    end

    %% Reporting & Logging and External Tools
    PLOG("PEvent & Logging"):::report
    RV("Reporting & Visualization"):::report
    EXT("External Tools"):::external
    MSS("MSS - L2 Cache/Memory Subsystem"):::cache

    %% Primary Flow Connections
    TI --> OS
    CFG --> ARCHCFG
    ARCHCFG --> OS
    OS --> F
    F --> D
    D --> DIS
    DIS --> R
    R --> IQ
    IQ --> EX
    EX --> PLOG
    PLOG --> RV
    EXT --> RV

    %% Branches for LSU and Vector operations from Rename Unit
    R --- LSU
    R --- V

    %% Interaction from LSU to Memory Subsystem
    LSU --> MSS

    %% Click Events
    click OS "https://github.com/riscv-software-src/riscv-perf-model/blob/master/sim/OlympiaSim.cpp"
    click F "https://github.com/riscv-software-src/riscv-perf-model/tree/master/core/fetch"
    click D "https://github.com/riscv-software-src/riscv-perf-model/tree/master/core/decode"
    click DIS "https://github.com/riscv-software-src/riscv-perf-model/tree/master/core/dispatch"
    click R "https://github.com/riscv-software-src/riscv-perf-model/tree/master/core/rename"
    click EX "https://github.com/riscv-software-src/riscv-perf-model/tree/master/core/execute"
    click LSU "https://github.com/riscv-software-src/riscv-perf-model/tree/master/core/lsu"
    click V "https://github.com/riscv-software-src/riscv-perf-model/tree/master/core/vector"
    click MSS "https://github.com/riscv-software-src/riscv-perf-model/tree/master/mss"
    click ARCHCFG "https://github.com/riscv-software-src/riscv-perf-model/tree/master/arches"
    click PLOG "https://github.com/riscv-software-src/riscv-perf-model/tree/master/reports"
    click EXT "https://github.com/riscv-software-src/riscv-perf-model/tree/master/traces/stf_trace_gen"

    %% Styles
    classDef sim fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
    classDef pipeline fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef report fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef config fill:#FADBD8,stroke:#C0392B,stroke-width:2px;
    classDef input fill:#D6EAF8,stroke:#1F618D,stroke-width:2px;
    classDef external fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
    classDef cache fill:#FDEBD0,stroke:#E67E22,stroke-width:2px;
```
