# shehrozkashif/vermithor architecture

> Architecture diagram of the GitHub repository shehrozkashif/vermithor, 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/shehrozkashif/vermithor
- Repository: https://github.com/shehrozkashif/vermithor

## Overview

##### Project type and purpose
- This is a hardware‐design project written in Scala using Chisel: it describes and generates a 5-stage pipelined RISC-V RV-32I core (“Vermithor”).
- It’s not a web or database app but a hardware generator: Scala/Chisel code → Verilog → simulation via Verilator → testbenches.

##### File structure
- src/main/scala/core/Memory: instruction memory (Imem.scala)
- src/main/scala/core/Modules: individual pipeline stage modules (fetch, decode, execute, mem, wb), plus ALU, register file, control unit, PC, immediate generator
- src/main/scala/core/Pipelines: pipeline registers (“reg1”..“reg4”) that separate stages
- topcore.scala: instantiates modules, stitches pipeline registers into the full processor datapath
- src/test/scala/core: unit tests for each module and full top-level tests
- build.sbt, project/: SBT build definition
- Dependencies: Chisel (Scala), Verilator (for simulation)

##### Key insights from README
- The build pipeline: sbt → compile Scala/Chisel → emit Verilog → run tests → optionally simulate in Verilator
- The core is a textbook 5-stage RISC-V pipeline

##### Main components
a. Development tools & flow
- Scala/Chisel source code (src/)
- sbt build system
- Verilog output
- Verilator simulation/testbench
b. Core hardware modules & pipeline
- IF stage: PC register → Imem
- ID stage: pipeline register (reg1) → Control Unit + Register File → immediate generator
- EX stage: pipeline register (reg2) → ALU
- MEM stage: pipeline register (reg3) → Data Memory
- WB stage: pipeline register (reg4) → write back into Register File
c. Interconnections
- Pipeline registers between each stage
- Control signals from Control Unit to ALU, memories, register file
- Data paths (instructions, operand buses, result buses) flowing forward

##### Architectural patterns & design principles
- Classic 5-stage pipeline: fetch, decode, execute, memory, writeback
- Separation of concerns: each stage in its own Scala file
- Parameterized modules in Scala/Chisel for reusability
- Explicit pipeline registers for stage isolation and hazard management (no forwarding shown, but pipeline registers are explicit)

##### Relevant technologies & libraries
- Scala (language for Chisel)
- Chisel (hardware description embedded in Scala)
- SBT (build tool)
- Verilator (Verilog simulation)
- RISC-V RV-32I ISA as target spec

## Diagram (Mermaid)

```mermaid
flowchart LR
  subgraph "Development Flow"
    direction TB
    SCALA["Scala/Chisel sources"]:::dev
    SBT["build.sbt (SBT)"]:::dev
    VERILOG["Generated Verilog"]:::dev
    VERILATOR["Verilator Simulation"]:::dev
    TEST["Unit Tests"]:::dev
    SCALA -->|compile| SBT -->|emit Verilog| VERILOG -->|simulate| VERILATOR -->|run tests| TEST
  end

  subgraph "Vermithor 5-Stage Pipeline"
    direction TB

    subgraph "IF Stage"
      direction TB
      PC["PC Register"]:::func
      Imem["Instruction Memory"]:::mem
      Fetch["Fetch Logic"]:::func
    end

    Reg1["Reg1"]:::reg

    subgraph "ID Stage"
      direction TB
      Control["Control Unit"]:::func
      RegFile["Register File"]:::func
      ImmGen["Immediate Generator"]:::func
      Decode["Decode Logic"]:::func
    end

    Reg2["Reg2"]:::reg

    subgraph "EX Stage"
      direction TB
      ALU["ALU"]:::func
      Execute["Execute Logic"]:::func
    end

    Reg3["Reg3"]:::reg

    subgraph "MEM Stage"
      direction TB
      DataMem["Data Memory"]:::mem
      MemLogic["Memory-stage Logic"]:::func
    end

    Reg4["Reg4"]:::reg

    subgraph "WB Stage"
      direction TB
      WBlogic["Write-back Logic"]:::func
    end

    PC --> Imem --> Fetch --> Reg1 --> Control --> RegFile --> ImmGen --> Decode --> Reg2 --> ALU --> Execute --> Reg3 --> DataMem --> MemLogic --> Reg4 --> WBlogic
  end

  Topcore["Topcore (Datapath Integration)"]:::func

  TEST --> Topcore

  click PC "https://github.com/shehrozkashif/vermithor/blob/main/src/main/scala/core/Modules/pc.scala"
  click Imem "https://github.com/shehrozkashif/vermithor/blob/main/src/main/scala/core/Memory/Imem.scala"
  click Fetch "https://github.com/shehrozkashif/vermithor/blob/main/src/main/scala/core/Modules/fetch.scala"
  click Reg1 "https://github.com/shehrozkashif/vermithor/blob/main/src/main/scala/core/Pipelines/reg1.scala"
  click Control "https://github.com/shehrozkashif/vermithor/blob/main/src/main/scala/core/Modules/controlunit.scala"
  click RegFile "https://github.com/shehrozkashif/vermithor/blob/main/src/main/scala/core/Modules/registerfile.scala"
  click ImmGen "https://github.com/shehrozkashif/vermithor/blob/main/src/main/scala/core/Modules/immgenr.scala"
  click Decode "https://github.com/shehrozkashif/vermithor/blob/main/src/main/scala/core/Modules/decode.scala"
  click Reg2 "https://github.com/shehrozkashif/vermithor/blob/main/src/main/scala/core/Pipelines/reg2.scala"
  click ALU "https://github.com/shehrozkashif/vermithor/blob/main/src/main/scala/core/Modules/alu.scala"
  click Execute "https://github.com/shehrozkashif/vermithor/blob/main/src/main/scala/core/Modules/execute.scala"
  click Reg3 "https://github.com/shehrozkashif/vermithor/blob/main/src/main/scala/core/Pipelines/reg3.scala"
  click DataMem "https://github.com/shehrozkashif/vermithor/blob/main/src/main/scala/core/Modules/datamemory.scala"
  click MemLogic "https://github.com/shehrozkashif/vermithor/blob/main/src/main/scala/core/Modules/mem.scala"
  click Reg4 "https://github.com/shehrozkashif/vermithor/blob/main/src/main/scala/core/Pipelines/reg4.scala"
  click WBlogic "https://github.com/shehrozkashif/vermithor/blob/main/src/main/scala/core/Modules/wb.scala"
  click Topcore "https://github.com/shehrozkashif/vermithor/blob/main/src/main/scala/core/topcore.scala"
  click SCALA "https://github.com/shehrozkashif/vermithor/tree/main/src/main/scala"
  click TEST "https://github.com/shehrozkashif/vermithor/tree/main/src/test/scala/core"

  classDef dev fill:#dddddd,stroke:#333,stroke-width:1px
  classDef func fill:#ccffcc,stroke:#333,stroke-width:1px
  classDef mem fill:#ffcc66,stroke:#333,stroke-width:1px
  classDef reg fill:#66ccff,stroke:#333,stroke-width:1px
```
