# evensgn/risc-v-cpu architecture

> Architecture diagram of the GitHub repository evensgn/risc-v-cpu, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/evensgn/risc-v-cpu
- Repository: https://github.com/evensgn/risc-v-cpu

## Overview

The product is a five-stage RV32I-subset CPU implemented in Verilog, with forwarding, caches, and a UART link for accessing a PC-hosted memory simulator. The main hardware workflow is instruction fetch through execute, memory access, and writeback; the alternate host workflow loads a program and runs either the instruction simulator or UART protocol handler against an environment-managed memory. Pipeline and UART capabilities are documented in the README; detailed hardware wiring was not sampled, so the graph omits uncertain module-level connections.

Main entry points: [`src/memory/environment.cpp`](https://github.com/evensgn/risc-v-cpu/blob/master/src/memory/environment.cpp) (Memory environment), [`src/cpu/riscv_cpu.v`](https://github.com/evensgn/risc-v-cpu/blob/master/src/cpu/riscv_cpu.v) (RISC-V CPU), [`src/cpu/stage_id.v`](https://github.com/evensgn/risc-v-cpu/blob/master/src/cpu/stage_id.v) (Decode), [`src/cpu/stage_ex.v`](https://github.com/evensgn/risc-v-cpu/blob/master/src/cpu/stage_ex.v) (Execute)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pipeline["CPU pipeline"]
  node_cpu["RISC-V CPU<br/>[riscv_cpu.v]"]
  node_fetch["Instruction fetch<br/>[stage_if.v]"]
  node_decode["Decode<br/>[stage_id.v]"]
  node_execute["Execute<br/>[stage_ex.v]"]
  node_memory_stage["Memory stage<br/>[stage_mem.v]"]
  node_pipeline_regs["Pipeline registers<br/>[reg_if_id.v]"]
  node_control["Control and forwarding<br/>[ctrl.v]"]
  node_register_file["Register file<br/>[regfile.v]"]
  node_cache["Instruction/data caches<br/>[cache.v]"]
  node_mem_ctrl["Memory controller<br/>[mem_ctrl.v]"]
end

subgraph group_link["UART interface"]
  node_uart["UART transport<br/>[uart_trans.v]"]
end

subgraph group_host["Host memory simulator"]
  node_memory_main["Simulator entry<br/>[main.cpp]"]
  node_environment[("Memory environment<br/>[environment.cpp]")]
  node_simulator["Instruction simulator<br/>[simulator.cpp]"]
  node_adapter["UART adapter<br/>[adapter.cpp]"]
end

node_programmer(("Program input"))
node_fpga(("FPGA / PC"))
node_serial["Serial port"]

node_programmer -->|"provides program"| node_memory_main
node_memory_main -->|"starts run"| node_environment
node_environment -->|"runs instructions"| node_simulator
node_simulator -->|"reads/writes memory"| node_environment
node_environment -->|"dispatches received bytes"| node_adapter
node_adapter -->|"reads/writes memory"| node_environment
node_adapter -->|"sends UART data"| node_environment
node_environment -->|"reads/writes bytes"| node_serial
node_fpga -.->|"UART link"| node_serial
node_cpu -->|"runs pipeline"| node_fetch
node_fetch -->|"passes instructions"| node_decode
node_decode -->|"passes operands"| node_execute
node_execute -->|"passes results"| node_memory_stage
node_memory_stage -->|"returns results"| node_cpu
node_decode -->|"reads registers"| node_register_file
node_execute -->|"writes results"| node_register_file
node_control -->|"controls stalls and forwarding"| node_cpu
node_cpu -->|"uses instruction/data caches"| node_cache
node_cpu -->|"accesses memory"| node_mem_ctrl
node_mem_ctrl -.->|"transfers memory requests"| node_uart
node_uart -.->|"communicates with PC"| node_fpga

click node_cpu "https://github.com/evensgn/risc-v-cpu/blob/master/src/cpu/riscv_cpu.v"
click node_fetch "https://github.com/evensgn/risc-v-cpu/blob/master/src/cpu/stage_if.v"
click node_decode "https://github.com/evensgn/risc-v-cpu/blob/master/src/cpu/stage_id.v"
click node_execute "https://github.com/evensgn/risc-v-cpu/blob/master/src/cpu/stage_ex.v"
click node_memory_stage "https://github.com/evensgn/risc-v-cpu/blob/master/src/cpu/stage_mem.v"
click node_pipeline_regs "https://github.com/evensgn/risc-v-cpu/blob/master/src/cpu/reg_if_id.v"
click node_control "https://github.com/evensgn/risc-v-cpu/blob/master/src/cpu/ctrl.v"
click node_register_file "https://github.com/evensgn/risc-v-cpu/blob/master/src/cpu/regfile.v"
click node_cache "https://github.com/evensgn/risc-v-cpu/blob/master/src/cpu/cache.v"
click node_mem_ctrl "https://github.com/evensgn/risc-v-cpu/blob/master/src/cpu/mem_ctrl.v"
click node_uart "https://github.com/evensgn/risc-v-cpu/blob/master/src/cpu/uart_trans.v"
click node_memory_main "https://github.com/evensgn/risc-v-cpu/blob/master/src/memory/main.cpp"
click node_environment "https://github.com/evensgn/risc-v-cpu/blob/master/src/memory/environment.cpp"
click node_simulator "https://github.com/evensgn/risc-v-cpu/blob/master/src/memory/simulator.cpp"
click node_adapter "https://github.com/evensgn/risc-v-cpu/blob/master/src/memory/adapter.cpp"

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_cpu,node_fetch,node_decode,node_execute,node_memory_stage,node_pipeline_regs,node_control,node_register_file,node_cache,node_mem_ctrl toneBlue
class node_uart toneAmber
class node_memory_main,node_environment,node_simulator,node_adapter toneMint
class node_programmer,node_fpga,node_serial toneIndigo
```

## Components

### CPU pipeline

- [RISC-V CPU](https://github.com/evensgn/risc-v-cpu/blob/master/src/cpu/riscv_cpu.v): `src/cpu/riscv_cpu.v`
- [Instruction fetch](https://github.com/evensgn/risc-v-cpu/blob/master/src/cpu/stage_if.v): `src/cpu/stage_if.v`
- [Decode](https://github.com/evensgn/risc-v-cpu/blob/master/src/cpu/stage_id.v): `src/cpu/stage_id.v`
- [Execute](https://github.com/evensgn/risc-v-cpu/blob/master/src/cpu/stage_ex.v): `src/cpu/stage_ex.v`
- [Memory stage](https://github.com/evensgn/risc-v-cpu/blob/master/src/cpu/stage_mem.v): `src/cpu/stage_mem.v`
- [Pipeline registers](https://github.com/evensgn/risc-v-cpu/blob/master/src/cpu/reg_if_id.v): `src/cpu/reg_if_id.v`
- [Control and forwarding](https://github.com/evensgn/risc-v-cpu/blob/master/src/cpu/ctrl.v): `src/cpu/ctrl.v`
- [Register file](https://github.com/evensgn/risc-v-cpu/blob/master/src/cpu/regfile.v): `src/cpu/regfile.v`
- [Instruction/data caches](https://github.com/evensgn/risc-v-cpu/blob/master/src/cpu/cache.v): `src/cpu/cache.v`
- [Memory controller](https://github.com/evensgn/risc-v-cpu/blob/master/src/cpu/mem_ctrl.v): `src/cpu/mem_ctrl.v`

### UART interface

- [UART transport](https://github.com/evensgn/risc-v-cpu/blob/master/src/cpu/uart_trans.v): `src/cpu/uart_trans.v`

### Host memory simulator

- [Simulator entry](https://github.com/evensgn/risc-v-cpu/blob/master/src/memory/main.cpp): `src/memory/main.cpp`
- [Memory environment](https://github.com/evensgn/risc-v-cpu/blob/master/src/memory/environment.cpp): `src/memory/environment.cpp`
- [Instruction simulator](https://github.com/evensgn/risc-v-cpu/blob/master/src/memory/simulator.cpp): `src/memory/simulator.cpp`
- [UART adapter](https://github.com/evensgn/risc-v-cpu/blob/master/src/memory/adapter.cpp): `src/memory/adapter.cpp`

### Other components

- **Program input**
- **FPGA / PC**
- **Serial port**

## Connections

- Program input → Simulator entry: provides program
- Simulator entry → Memory environment: starts run
- Memory environment → Instruction simulator: runs instructions
- Instruction simulator → Memory environment: reads/writes memory
- Memory environment → UART adapter: dispatches received bytes
- UART adapter → Memory environment: reads/writes memory
- UART adapter → Memory environment: sends UART data
- Memory environment → Serial port: reads/writes bytes
- FPGA / PC → Serial port: UART link
- RISC-V CPU → Instruction fetch: runs pipeline
- Instruction fetch → Decode: passes instructions
- Decode → Execute: passes operands
- Execute → Memory stage: passes results
- Memory stage → RISC-V CPU: returns results
- Decode → Register file: reads registers
- Execute → Register file: writes results
- Control and forwarding → RISC-V CPU: controls stalls and forwarding
- RISC-V CPU → Instruction/data caches: uses instruction/data caches
- RISC-V CPU → Memory controller: accesses memory
- Memory controller → UART transport: transfers memory requests
- UART transport → FPGA / PC: communicates with PC