# ssaadakhtar/rv32i-five-stage-pipeline architecture

> Architecture diagram of the GitHub repository ssaadakhtar/rv32i-five-stage-pipeline, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ssaadakhtar/rv32i-five-stage-pipeline
- Repository: https://github.com/ssaadakhtar/rv32i-five-stage-pipeline

## Overview

##### Project type and purpose
- This is a hardware‐design and verification project built in Scala/Chisel, targeting a RISC-V CPU in both single‐cycle and 5-stage pipeline styles.
- It uses SBT to compile Chisel (Scala) sources into FIRRTL, then Verilog, then Verilator/C++ for cycle‐accurate simulation. Python test harnesses (RISCoF, sail_cSim) drive memory models and compare results.

##### File structure
- src/main/scala/SingleCycle – Chisel implementation of single-cycle CPU
- 5stagepipeline – YAML configurations and Python harness for 5-stage pipeline implementation
- sail_cSim – Python harness + SAIL-C based ISS simulator
- core.v, core.fir, core.cpp – generated FIRRTL/Verilog/C++ simulation artifacts
- obj_dir/Vcore* – Verilator‐generated C++ model and build artifacts
- test_run_dir, waveform.vcd – simulation outputs and waveforms
- build.sbt, build.sc, project/ – SBT build and configuration files

##### README insights
- Contains RISC-V assembly test cases loaded at specific addresses in data memory

##### Main components
a. Chisel/Scala Frontend
- Scala source files under src/main/scala (SingleCycle, Pipeline generator)
- SBT/Scala build tool (build.sbt)
b. FIRRTL Compiler
- Transforms Chisel AST → FIRRTL (core.fir)
c. Verilog Backend
- FIRRTL → Verilog (core.v, sram_top.v, etc.)
d. Verilator/C++ Simulation
- Verilator generates C++ model (obj_dir/Vcore*.cpp/.h)
- Build produces simulation executable (Vcore)
e. Memory & Test Harness
- Python RISCoF scripts (riscof_5stagepipeline.py, riscof_sail_cSim.py)
- Linker scripts (link.ld) and test headers (model_test.h)
- Assembly test binaries loaded into simulated memory (imem.txt, .anno.json)
f. SAIL-C ISS
- sail_cSim harness for comparison to the Verilator model
g. Outputs & Verification
- Waveform (.vcd) viewer, test logs, PASS/FAIL comparison

##### Relationships & interactions
- SBT invokes Chisel → FIRRTL → Verilog
- Verilog + Verilator → C++ model → compiled simulator
- Python harness drives simulator: loads test code into memory, steps clock, reads register outputs
- sail_cSim harness runs the same test in the SAIL-C ISS
- Results from Verilator model vs ISS compared and discrepancies logged
- VCD waveforms generated during simulation for manual inspection

##### Architectural patterns and design principles
- Modular pipeline stages (Fetch, Decode, Execute, MEM, Write-Back) implemented as independent Chisel modules
- Memory‐mapped imem / dmem abstractions
- Build pipeline follows source-to-artifact pattern (Chisel → FIRRTL → Verilog → C++)
- Test‐driven verification via external Python harness

- Clear component labels (e.g., “Fetch.scala,” “Execute.scala,” “Pipeline YAML Config”)
- Two distinct flows: Build Flow (Chisel → FIRRTL → Verilog → C++ model) vs Test Flow (Python harness → Simulator & ISS → Comparison)
- Arrowheads indicating data and control flow direction

## Diagram (Mermaid)

```mermaid
graph TD

    %% Build Stage (Blue)
    subgraph "Build Stage"
        direction TB
        ScalaFrontend["Chisel/Scala Frontend<br/>(src/main/scala/SingleCycle)"]:::blue
        SBTBuild["SBT Build Tool<br/>(build.sbt, build.sc)"]:::blue
        FIRRTLCompiler["FIRRTL Compiler<br/>(core.fir)"]:::green
        VerilogBackend["Verilog Backend<br/>(core.v, sram.v, sram_top.v)"]:::green
    end

    %% Simulation Stage (Orange)
    subgraph "Simulation Stage"
        direction TB
        VerilatorModel["Verilator Model<br/>(obj_dir/Vcore*)"]:::orange
        CppSimulator["C++ Simulator<br/>(Vcore executable)"]:::orange
        WaveformViewer["Waveform Viewer<br/>(.vcd files)"]:::orange
    end

    %% Test Harness Stage (Purple)
    subgraph "Test Harness"
        direction TB
        PythonRISCoF["Python RISCoF Harness"]:::purple
        SAILISS["SAIL-C ISS Harness"]:::purple
        MemoryModel["Memory Model<br/>(imem.txt, dmem.txt)"]:::purple
        Comparison["Results Comparison<br/>(PASS/FAIL logs)"]:::purple
    end

    %% Build Flow
    ScalaFrontend -->|"via SBT"| SBTBuild
    SBTBuild -->|"generates FIRRTL"| FIRRTLCompiler
    FIRRTLCompiler -->|"generates Verilog"| VerilogBackend

    %% Simulation Flow
    VerilogBackend -->|"Verilator generates C++"| VerilatorModel
    VerilatorModel -->|"compile/link"| CppSimulator
    CppSimulator -->|"produce .vcd"| WaveformViewer

    %% Test Flow
    PythonRISCoF -->|"load tests into"| MemoryModel
    PythonRISCoF -->|"drive clocks & read regs"| CppSimulator
    SAILISS -->|"run ISS on tests"| MemoryModel
    SAILISS -->|"compare outputs"| Comparison
    CppSimulator -->|"export results"| Comparison

    %% Memory Model feeds both
    MemoryModel --> CppSimulator
    MemoryModel --> SAILISS

    %% Click Events
    click ScalaFrontend "https://github.com/ssaadakhtar/rv32i-five-stage-pipeline/tree/main/src/main/scala/SingleCycle"
    click SBTBuild "https://github.com/ssaadakhtar/rv32i-five-stage-pipeline/blob/main/build.sbt"
    click FIRRTLCompiler "https://github.com/ssaadakhtar/rv32i-five-stage-pipeline/blob/main/core.fir"
    click VerilogBackend "https://github.com/ssaadakhtar/rv32i-five-stage-pipeline/blob/main/src/main/resources/sram_top.v"
    click VerilatorModel "https://github.com/ssaadakhtar/rv32i-five-stage-pipeline/blob/main/obj_dir/Vcore.cpp"
    click PythonRISCoF "https://github.com/ssaadakhtar/rv32i-five-stage-pipeline/blob/main/5stagepipeline/riscof_5stagepipeline.py"
    click SAILISS "https://github.com/ssaadakhtar/rv32i-five-stage-pipeline/blob/main/sail_cSim/riscof_sail_cSim.py"

    %% Styles
    classDef blue fill:#cfe2f3,stroke:#0b5394,color:#0b5394
    classDef green fill:#d9ead3,stroke:#38761d,color:#38761d
    classDef orange fill:#f9cb9c,stroke:#e69138,color:#e69138
    classDef purple fill:#d9d2e9,stroke:#674ea7,color:#674ea7
```
