# cshieldsce/riscv-5i architecture

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

- Interactive diagram: https://gitdiagram.com/cshieldsce/riscv-5i
- Repository: https://github.com/cshieldsce/riscv-5i

## Overview

riscv-5i is an RV32I processor implemented as a five-stage SystemVerilog pipeline and integrated with a PYNQ-Z2 FPGA board. Its principal workflow fetches instructions, decodes and executes them, accesses memory, and writes results back; documented pipeline features include forwarding, load-use stalling, and early JAL branch resolution. The README establishes the stages and major modules, but no RTL excerpts were provided, so the graph shows only relationships documented there, not detailed signal-level connections.

Main entry points: [`src/id_stage.sv`](https://github.com/cshieldsce/riscv-5i/blob/main/src/id_stage.sv) (Decode and register read), [`src/if_stage.sv`](https://github.com/cshieldsce/riscv-5i/blob/main/src/if_stage.sv) (Instruction fetch), [`src/pipelined_cpu.sv`](https://github.com/cshieldsce/riscv-5i/blob/main/src/pipelined_cpu.sv) (Pipeline controller), [`src/ex_stage.sv`](https://github.com/cshieldsce/riscv-5i/blob/main/src/ex_stage.sv) (Execute)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pipeline["CPU Pipeline"]
  node_if["Instruction fetch<br/>[if_stage.sv]"]
  node_id["Decode and register read<br/>[id_stage.sv]"]
  node_ex["Execute<br/>[ex_stage.sv]"]
  node_memstage["Memory access<br/>[mem_stage.sv]"]
  node_wb["Writeback<br/>[wb_stage.sv]"]
  node_cpu["Pipeline controller<br/>[pipelined_cpu.sv]"]
end

subgraph group_support["Pipeline Support"]
  node_imem["Instruction memory"]
  node_pc["Program counter<br/>[pc.sv]"]
  node_decoder["Control decoder<br/>[control_unit.sv]"]
  node_regfile[("Register file<br/>[reg_file.sv]")]
  node_imm["Immediate generator<br/>[imm_gen.sv]"]
  node_alu["Arithmetic logic unit<br/>[alu.sv]"]
  node_hazard["Hazard handling<br/>[hazard_unit.sv]"]
  node_forward["Forwarding logic<br/>[forwarding_unit.sv]"]
  node_dmem[("Data memory<br/>[data_memory.sv]")]
end

subgraph group_platform["FPGA Platform"]
  node_board["PYNQ-Z2 integration<br/>[pynq_z2_top.sv]"]
end

node_program(("Program instructions"))
node_led["Memory-mapped LEDs"]

node_program -->|"provides instructions"| node_if
node_if -->|"pipeline stage"| node_id
node_id -->|"pipeline stage"| node_ex
node_ex -->|"pipeline stage"| node_memstage
node_memstage -->|"pipeline stage"| node_wb
node_cpu -->|"coordinates pipeline"| node_if
node_if -.->|"fetches from"| node_imem
node_if -.->|"uses"| node_pc
node_id -.->|"decodes with"| node_decoder
node_id -.->|"reads registers"| node_regfile
node_id -.->|"generates immediates"| node_imm
node_ex -.->|"executes with"| node_alu
node_cpu -->|"handles stalls"| node_hazard
node_cpu -->|"forwards values"| node_forward
node_memstage -.->|"accesses memory"| node_dmem
node_board -.->|"integrates core"| node_cpu
node_board -->|"drives via mapped register"| node_led

click node_if "https://github.com/cshieldsce/riscv-5i/blob/main/src/if_stage.sv"
click node_id "https://github.com/cshieldsce/riscv-5i/blob/main/src/id_stage.sv"
click node_ex "https://github.com/cshieldsce/riscv-5i/blob/main/src/ex_stage.sv"
click node_memstage "https://github.com/cshieldsce/riscv-5i/blob/main/src/mem_stage.sv"
click node_wb "https://github.com/cshieldsce/riscv-5i/blob/main/src/wb_stage.sv"
click node_cpu "https://github.com/cshieldsce/riscv-5i/blob/main/src/pipelined_cpu.sv"
click node_imem "https://github.com/cshieldsce/riscv-5i/blob/main/src/instruction_memory.sv"
click node_pc "https://github.com/cshieldsce/riscv-5i/blob/main/src/pc.sv"
click node_decoder "https://github.com/cshieldsce/riscv-5i/blob/main/src/control_unit.sv"
click node_regfile "https://github.com/cshieldsce/riscv-5i/blob/main/src/reg_file.sv"
click node_imm "https://github.com/cshieldsce/riscv-5i/blob/main/src/imm_gen.sv"
click node_alu "https://github.com/cshieldsce/riscv-5i/blob/main/src/alu.sv"
click node_hazard "https://github.com/cshieldsce/riscv-5i/blob/main/src/hazard_unit.sv"
click node_forward "https://github.com/cshieldsce/riscv-5i/blob/main/src/forwarding_unit.sv"
click node_dmem "https://github.com/cshieldsce/riscv-5i/blob/main/src/data_memory.sv"
click node_board "https://github.com/cshieldsce/riscv-5i/blob/main/src/pynq_z2_top.sv"

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_if,node_id,node_ex,node_memstage,node_wb,node_cpu toneBlue
class node_imem,node_pc,node_decoder,node_regfile,node_imm,node_alu,node_hazard,node_forward,node_dmem toneAmber
class node_board toneMint
class node_program,node_led toneIndigo
```

## Components

### CPU Pipeline

- [Instruction fetch](https://github.com/cshieldsce/riscv-5i/blob/main/src/if_stage.sv): `src/if_stage.sv`
- [Decode and register read](https://github.com/cshieldsce/riscv-5i/blob/main/src/id_stage.sv): `src/id_stage.sv`
- [Execute](https://github.com/cshieldsce/riscv-5i/blob/main/src/ex_stage.sv): `src/ex_stage.sv`
- [Memory access](https://github.com/cshieldsce/riscv-5i/blob/main/src/mem_stage.sv): `src/mem_stage.sv`
- [Writeback](https://github.com/cshieldsce/riscv-5i/blob/main/src/wb_stage.sv): `src/wb_stage.sv`
- [Pipeline controller](https://github.com/cshieldsce/riscv-5i/blob/main/src/pipelined_cpu.sv): `src/pipelined_cpu.sv`

### Pipeline Support

- [Instruction memory](https://github.com/cshieldsce/riscv-5i/blob/main/src/instruction_memory.sv): `src/instruction_memory.sv`
- [Program counter](https://github.com/cshieldsce/riscv-5i/blob/main/src/pc.sv): `src/pc.sv`
- [Control decoder](https://github.com/cshieldsce/riscv-5i/blob/main/src/control_unit.sv): `src/control_unit.sv`
- [Register file](https://github.com/cshieldsce/riscv-5i/blob/main/src/reg_file.sv): `src/reg_file.sv`
- [Immediate generator](https://github.com/cshieldsce/riscv-5i/blob/main/src/imm_gen.sv): `src/imm_gen.sv`
- [Arithmetic logic unit](https://github.com/cshieldsce/riscv-5i/blob/main/src/alu.sv): `src/alu.sv`
- [Hazard handling](https://github.com/cshieldsce/riscv-5i/blob/main/src/hazard_unit.sv): `src/hazard_unit.sv`
- [Forwarding logic](https://github.com/cshieldsce/riscv-5i/blob/main/src/forwarding_unit.sv): `src/forwarding_unit.sv`
- [Data memory](https://github.com/cshieldsce/riscv-5i/blob/main/src/data_memory.sv): `src/data_memory.sv`

### FPGA Platform

- [PYNQ-Z2 integration](https://github.com/cshieldsce/riscv-5i/blob/main/src/pynq_z2_top.sv): `src/pynq_z2_top.sv`

### Other components

- **Program instructions**
- **Memory-mapped LEDs**

## Connections

- Program instructions → Instruction fetch: provides instructions (evidence: `README.md`)
- Instruction fetch → Decode and register read: pipeline stage (evidence: `README.md`)
- Decode and register read → Execute: pipeline stage (evidence: `README.md`)
- Execute → Memory access: pipeline stage (evidence: `README.md`)
- Memory access → Writeback: pipeline stage (evidence: `README.md`)
- Pipeline controller → Instruction fetch: coordinates pipeline (evidence: `README.md`)
- Instruction fetch → Instruction memory: fetches from
- Instruction fetch → Program counter: uses
- Decode and register read → Control decoder: decodes with
- Decode and register read → Register file: reads registers
- Decode and register read → Immediate generator: generates immediates
- Execute → Arithmetic logic unit: executes with
- Pipeline controller → Hazard handling: handles stalls (evidence: `README.md`)
- Pipeline controller → Forwarding logic: forwards values (evidence: `README.md`)
- Memory access → Data memory: accesses memory
- PYNQ-Z2 integration → Pipeline controller: integrates core
- PYNQ-Z2 integration → Memory-mapped LEDs: drives via mapped register (evidence: `README.md`)
