# vivaansh001/risc-v-cpu architecture

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

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

## Overview

This repository is a Verilog RV32I processor project: its product workflow is executing instruction programs on either a pipelined or single-cycle core, with memory access routed through a shared interface and a SoC wrapper extending the core with UART MMIO. The README also describes reusable Verilog learning building blocks and the pipeline’s forwarding and hazard handling. Source excerpts were limited to the README and encoder; relationships among RTL modules below are therefore included only where the README explicitly documents them, and other connections are omitted rather than inferred.

Main entry points: [`rtl/core/core_pipelined.v`](https://github.com/vivaansh001/risc-v-cpu/blob/main/rtl/core/core_pipelined.v) (Pipelined core), [`rtl/core/mem_interface.v`](https://github.com/vivaansh001/risc-v-cpu/blob/main/rtl/core/mem_interface.v) (Memory interface), [`rtl/core/core.v`](https://github.com/vivaansh001/risc-v-cpu/blob/main/rtl/core/core.v) (Single-cycle core), [`rtl/soc/soc.v`](https://github.com/vivaansh001/risc-v-cpu/blob/main/rtl/soc/soc.v) (SoC wrapper)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cores["CPU cores"]
  node_single["Single-cycle core<br/>[core.v]"]
  node_pipelined["Pipelined core<br/>[core_pipelined.v]"]
end

subgraph group_pipeline["Pipeline control"]
  node_pipeline_regs["Pipeline registers<br/>[if_id_reg.v]"]
  node_forwarding["Forwarding unit<br/>[forwarding_unit.v]"]
  node_hazard["Hazard detection<br/>[hazard_detect.v]"]
end

subgraph group_memory["Memory and I/O"]
  node_memif["Memory interface<br/>[mem_interface.v]"]
  node_instrmem[("Instruction memory<br/>[instr_mem.v]")]
  node_datamem[("Data memory<br/>[data_mem.v]")]
  node_uart["UART MMIO<br/>[uart_mmio.v]"]
  node_uarttx["UART transmitter<br/>[uart_tx.v]"]
  node_uartrx["UART receiver<br/>[uart_rx.v]"]
end

subgraph group_soc["System integration"]
  node_soc["SoC wrapper<br/>[soc.v]"]
end

subgraph group_learning["Logic foundations"]
  node_fundamentals["Verilog building blocks"]
end

node_programmer(("Program author"))
node_hexprogram["Encoded program"]
node_encoder["Instruction encoder<br/>[encoder.py]"]

node_programmer -->|"encodes instructions"| node_encoder
node_encoder -->|"writes hex program"| node_hexprogram
node_hexprogram -.->|"loads instructions"| node_single
node_hexprogram -.->|"loads instructions"| node_pipelined
node_single -->|"accesses memory"| node_memif
node_pipelined -->|"accesses memory"| node_memif
node_pipelined -->|"separates stages"| node_pipeline_regs
node_pipelined -->|"uses forwarding"| node_forwarding
node_pipelined -->|"detects hazards"| node_hazard
node_memif -->|"routes RAM accesses"| node_datamem
node_memif -->|"routes UART writes"| node_uarttx
node_soc -.->|"integrates core"| node_single
node_soc -.->|"integrates core"| node_pipelined
node_fundamentals -->|"foundation for"| node_single

click node_encoder "https://github.com/vivaansh001/risc-v-cpu/blob/main/programs/encoder/encoder.py"
click node_single "https://github.com/vivaansh001/risc-v-cpu/blob/main/rtl/core/core.v"
click node_pipelined "https://github.com/vivaansh001/risc-v-cpu/blob/main/rtl/core/core_pipelined.v"
click node_pipeline_regs "https://github.com/vivaansh001/risc-v-cpu/blob/main/rtl/core/if_id_reg.v"
click node_forwarding "https://github.com/vivaansh001/risc-v-cpu/blob/main/rtl/core/forwarding_unit.v"
click node_hazard "https://github.com/vivaansh001/risc-v-cpu/blob/main/rtl/core/hazard_detect.v"
click node_memif "https://github.com/vivaansh001/risc-v-cpu/blob/main/rtl/core/mem_interface.v"
click node_instrmem "https://github.com/vivaansh001/risc-v-cpu/blob/main/rtl/core/instr_mem.v"
click node_datamem "https://github.com/vivaansh001/risc-v-cpu/blob/main/rtl/core/data_mem.v"
click node_uart "https://github.com/vivaansh001/risc-v-cpu/blob/main/rtl/core/uart_mmio.v"
click node_uarttx "https://github.com/vivaansh001/risc-v-cpu/blob/main/rtl/core/uart_tx.v"
click node_uartrx "https://github.com/vivaansh001/risc-v-cpu/blob/main/rtl/core/uart_rx.v"
click node_soc "https://github.com/vivaansh001/risc-v-cpu/blob/main/rtl/soc/soc.v"
click node_fundamentals "https://github.com/vivaansh001/risc-v-cpu/tree/main/verilog-fundamentals"

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_single,node_pipelined toneBlue
class node_pipeline_regs,node_forwarding,node_hazard toneAmber
class node_memif,node_instrmem,node_datamem,node_uart,node_uarttx,node_uartrx toneMint
class node_soc toneRose
class node_fundamentals,node_programmer,node_hexprogram toneIndigo
class node_encoder toneTeal
```

## Components

### CPU cores

- [Single-cycle core](https://github.com/vivaansh001/risc-v-cpu/blob/main/rtl/core/core.v): `rtl/core/core.v`
- [Pipelined core](https://github.com/vivaansh001/risc-v-cpu/blob/main/rtl/core/core_pipelined.v): `rtl/core/core_pipelined.v`

### Pipeline control

- [Pipeline registers](https://github.com/vivaansh001/risc-v-cpu/blob/main/rtl/core/if_id_reg.v): `rtl/core/if_id_reg.v`
- [Forwarding unit](https://github.com/vivaansh001/risc-v-cpu/blob/main/rtl/core/forwarding_unit.v): `rtl/core/forwarding_unit.v`
- [Hazard detection](https://github.com/vivaansh001/risc-v-cpu/blob/main/rtl/core/hazard_detect.v): `rtl/core/hazard_detect.v`

### Memory and I/O

- [Memory interface](https://github.com/vivaansh001/risc-v-cpu/blob/main/rtl/core/mem_interface.v): `rtl/core/mem_interface.v`
- [Instruction memory](https://github.com/vivaansh001/risc-v-cpu/blob/main/rtl/core/instr_mem.v): `rtl/core/instr_mem.v`
- [Data memory](https://github.com/vivaansh001/risc-v-cpu/blob/main/rtl/core/data_mem.v): `rtl/core/data_mem.v`
- [UART MMIO](https://github.com/vivaansh001/risc-v-cpu/blob/main/rtl/core/uart_mmio.v): `rtl/core/uart_mmio.v`
- [UART transmitter](https://github.com/vivaansh001/risc-v-cpu/blob/main/rtl/core/uart_tx.v): `rtl/core/uart_tx.v`
- [UART receiver](https://github.com/vivaansh001/risc-v-cpu/blob/main/rtl/core/uart_rx.v): `rtl/core/uart_rx.v`

### System integration

- [SoC wrapper](https://github.com/vivaansh001/risc-v-cpu/blob/main/rtl/soc/soc.v): `rtl/soc/soc.v`

### Logic foundations

- [Verilog building blocks](https://github.com/vivaansh001/risc-v-cpu/tree/main/verilog-fundamentals): `verilog-fundamentals`

### Other components

- **Program author**
- **Encoded program**
- [Instruction encoder](https://github.com/vivaansh001/risc-v-cpu/blob/main/programs/encoder/encoder.py): `programs/encoder/encoder.py`

## Connections

- Program author → Instruction encoder: encodes instructions (evidence: `programs/encoder/encoder.py`)
- Instruction encoder → Encoded program: writes hex program (evidence: `programs/encoder/encoder.py`)
- Encoded program → Single-cycle core: loads instructions (evidence: `README.md`)
- Encoded program → Pipelined core: loads instructions (evidence: `README.md`)
- Single-cycle core → Memory interface: accesses memory (evidence: `README.md`)
- Pipelined core → Memory interface: accesses memory (evidence: `README.md`)
- Pipelined core → Pipeline registers: separates stages (evidence: `README.md`)
- Pipelined core → Forwarding unit: uses forwarding (evidence: `README.md`)
- Pipelined core → Hazard detection: detects hazards (evidence: `README.md`)
- Memory interface → Data memory: routes RAM accesses (evidence: `README.md`)
- Memory interface → UART transmitter: routes UART writes (evidence: `README.md`)
- SoC wrapper → Single-cycle core: integrates core
- SoC wrapper → Pipelined core: integrates core
- Verilog building blocks → Single-cycle core: foundation for (evidence: `README.md`)
