# mpimienta/risc-v architecture

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

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

## Overview

This repository implements an 8-bit, 16-bit-instruction RISC-V-inspired CPU for an FPGA, plus a Python assembler. The principal workflow is assembling instructions into machine-code output and executing them in a multicycle fetch-high, fetch-low, execute design. The documented ISA and MMIO map define the CPU’s instruction and I/O domains; the tree also includes display, keypad, and OLED modules. Source excerpts cover only the assembler, so hardware wiring beyond the README’s documented stages and memory map is left unverified.

Main entry points: [`modules/riscv.vhd`](https://github.com/mpimienta/risc-v/blob/CPU-16-bit-pipeline/modules/riscv.vhd) (CPU Core), [`modules/io_memory`](https://github.com/mpimienta/risc-v/tree/CPU-16-bit-pipeline/modules/io_memory) (Memory-Mapped I/O), [`modules/display/display_subsystem.vhd`](https://github.com/mpimienta/risc-v/blob/CPU-16-bit-pipeline/modules/display/display_subsystem.vhd) (Display Subsystem), [`modules/top_level.vhd`](https://github.com/mpimienta/risc-v/blob/CPU-16-bit-pipeline/modules/top_level.vhd) (FPGA Top Level)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_software["Assembly Software"]
  node_assembler["Assembler<br/>[assembler.py]"]
end

subgraph group_cpu["CPU Core"]
  node_top_level["FPGA Top Level<br/>[top_level.vhd]"]
  node_cpu_core["CPU Core<br/>[riscv.vhd]"]
  node_fetch_high["Fetch High"]
  node_fetch_low["Fetch Low"]
  node_execute["Execute"]
  node_instruction_decode["Instruction Decode<br/>[decoder.vhd]"]
  node_control_unit["Control Unit<br/>[control_unit.vhd]"]
  node_datapath["Datapath"]
  node_hazard_forwarding["Hazard and Forwarding"]
end

subgraph group_memory["Memory and I/O"]
  node_instruction_rom[("Instruction ROM")]
  node_data_ram[("Data RAM<br/>[ram_data.vhd]")]
  node_mmio["Memory-Mapped I/O"]
end

subgraph group_peripherals["Board Peripherals"]
  node_keypad["Keypad Controller"]
  node_display_subsystem["Display Subsystem"]
  node_display_manager["Display Manager"]
  node_lcd_controller["LCD Controller<br/>[lcd_controller.vhd]"]
  node_i2c_master["I2C Master<br/>[i2c_master.vhd]"]
  node_oled_mmio["OLED SPI MMIO<br/>[oled_spi_mmio.vhd]"]
end

node_assembly_source["Assembly Source"]
node_machine_code["Machine Code"]
node_board(("Basys 3 Board"))

node_assembly_source -->|"reads"| node_assembler
node_assembler -->|"writes"| node_machine_code
node_top_level -.->|"integrates"| node_cpu_core
node_cpu_core -.->|"fetches"| node_fetch_high
node_fetch_high -->|"continues fetch"| node_fetch_low
node_fetch_low -->|"then executes"| node_execute
node_cpu_core -.->|"decodes"| node_instruction_decode
node_cpu_core -.->|"controls"| node_control_unit
node_cpu_core -.->|"uses"| node_datapath
node_cpu_core -.->|"uses"| node_hazard_forwarding
node_cpu_core -.->|"fetches instructions"| node_instruction_rom
node_cpu_core -.->|"accesses data"| node_data_ram
node_cpu_core -.->|"maps I/O"| node_mmio
node_mmio -.->|"routes input"| node_keypad
node_mmio -.->|"routes output"| node_display_subsystem
node_display_subsystem -.->|"uses"| node_display_manager
node_display_subsystem -.->|"uses"| node_lcd_controller
node_lcd_controller -.->|"uses"| node_i2c_master
node_mmio -.->|"routes output"| node_oled_mmio
node_top_level -.->|"targets"| node_board

click node_assembler "https://github.com/mpimienta/risc-v/blob/CPU-16-bit-pipeline/compiler/assembler.py"
click node_top_level "https://github.com/mpimienta/risc-v/blob/CPU-16-bit-pipeline/modules/top_level.vhd"
click node_cpu_core "https://github.com/mpimienta/risc-v/blob/CPU-16-bit-pipeline/modules/riscv.vhd"
click node_fetch_high "https://github.com/mpimienta/risc-v/tree/CPU-16-bit-pipeline/modules"
click node_fetch_low "https://github.com/mpimienta/risc-v/tree/CPU-16-bit-pipeline/modules"
click node_execute "https://github.com/mpimienta/risc-v/tree/CPU-16-bit-pipeline/modules"
click node_instruction_decode "https://github.com/mpimienta/risc-v/blob/CPU-16-bit-pipeline/modules/control/decoder.vhd"
click node_control_unit "https://github.com/mpimienta/risc-v/blob/CPU-16-bit-pipeline/modules/control/control_unit.vhd"
click node_datapath "https://github.com/mpimienta/risc-v/tree/CPU-16-bit-pipeline/modules/datapath"
click node_hazard_forwarding "https://github.com/mpimienta/risc-v/tree/CPU-16-bit-pipeline/modules/control"
click node_instruction_rom "https://github.com/mpimienta/risc-v/blob/CPU-16-bit-pipeline/modules/io_memory/rom_instructions.vhd"
click node_data_ram "https://github.com/mpimienta/risc-v/blob/CPU-16-bit-pipeline/modules/io_memory/ram_data.vhd"
click node_mmio "https://github.com/mpimienta/risc-v/tree/CPU-16-bit-pipeline/modules/io_memory"
click node_keypad "https://github.com/mpimienta/risc-v/blob/CPU-16-bit-pipeline/modules/io_memory/keypad_controller.vhd"
click node_display_subsystem "https://github.com/mpimienta/risc-v/blob/CPU-16-bit-pipeline/modules/display/display_subsystem.vhd"
click node_display_manager "https://github.com/mpimienta/risc-v/blob/CPU-16-bit-pipeline/modules/display/display_manager.vhd"
click node_lcd_controller "https://github.com/mpimienta/risc-v/blob/CPU-16-bit-pipeline/modules/display/lcd_controller.vhd"
click node_i2c_master "https://github.com/mpimienta/risc-v/blob/CPU-16-bit-pipeline/modules/display/i2c_master.vhd"
click node_oled_mmio "https://github.com/mpimienta/risc-v/blob/CPU-16-bit-pipeline/modules/oled_noRGB/oled_spi_mmio.vhd"

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_assembler toneBlue
class node_top_level,node_cpu_core,node_fetch_high,node_fetch_low,node_execute,node_instruction_decode,node_control_unit,node_datapath,node_hazard_forwarding toneAmber
class node_instruction_rom,node_data_ram,node_mmio toneMint
class node_keypad,node_display_subsystem,node_display_manager,node_lcd_controller,node_i2c_master,node_oled_mmio toneRose
class node_assembly_source,node_machine_code,node_board toneIndigo
```

## Components

### Assembly Software

- [Assembler](https://github.com/mpimienta/risc-v/blob/CPU-16-bit-pipeline/compiler/assembler.py): `compiler/assembler.py`

### CPU Core

- [FPGA Top Level](https://github.com/mpimienta/risc-v/blob/CPU-16-bit-pipeline/modules/top_level.vhd): `modules/top_level.vhd`
- [CPU Core](https://github.com/mpimienta/risc-v/blob/CPU-16-bit-pipeline/modules/riscv.vhd): `modules/riscv.vhd`
- [Fetch High](https://github.com/mpimienta/risc-v/tree/CPU-16-bit-pipeline/modules): `modules`
- [Fetch Low](https://github.com/mpimienta/risc-v/tree/CPU-16-bit-pipeline/modules): `modules`
- [Execute](https://github.com/mpimienta/risc-v/tree/CPU-16-bit-pipeline/modules): `modules`
- [Instruction Decode](https://github.com/mpimienta/risc-v/blob/CPU-16-bit-pipeline/modules/control/decoder.vhd): `modules/control/decoder.vhd`
- [Control Unit](https://github.com/mpimienta/risc-v/blob/CPU-16-bit-pipeline/modules/control/control_unit.vhd): `modules/control/control_unit.vhd`
- [Datapath](https://github.com/mpimienta/risc-v/tree/CPU-16-bit-pipeline/modules/datapath): `modules/datapath`
- [Hazard and Forwarding](https://github.com/mpimienta/risc-v/tree/CPU-16-bit-pipeline/modules/control): `modules/control`

### Memory and I/O

- [Instruction ROM](https://github.com/mpimienta/risc-v/blob/CPU-16-bit-pipeline/modules/io_memory/rom_instructions.vhd): `modules/io_memory/rom_instructions.vhd`
- [Data RAM](https://github.com/mpimienta/risc-v/blob/CPU-16-bit-pipeline/modules/io_memory/ram_data.vhd): `modules/io_memory/ram_data.vhd`
- [Memory-Mapped I/O](https://github.com/mpimienta/risc-v/tree/CPU-16-bit-pipeline/modules/io_memory): `modules/io_memory`

### Board Peripherals

- [Keypad Controller](https://github.com/mpimienta/risc-v/blob/CPU-16-bit-pipeline/modules/io_memory/keypad_controller.vhd): `modules/io_memory/keypad_controller.vhd`
- [Display Subsystem](https://github.com/mpimienta/risc-v/blob/CPU-16-bit-pipeline/modules/display/display_subsystem.vhd): `modules/display/display_subsystem.vhd`
- [Display Manager](https://github.com/mpimienta/risc-v/blob/CPU-16-bit-pipeline/modules/display/display_manager.vhd): `modules/display/display_manager.vhd`
- [LCD Controller](https://github.com/mpimienta/risc-v/blob/CPU-16-bit-pipeline/modules/display/lcd_controller.vhd): `modules/display/lcd_controller.vhd`
- [I2C Master](https://github.com/mpimienta/risc-v/blob/CPU-16-bit-pipeline/modules/display/i2c_master.vhd): `modules/display/i2c_master.vhd`
- [OLED SPI MMIO](https://github.com/mpimienta/risc-v/blob/CPU-16-bit-pipeline/modules/oled_noRGB/oled_spi_mmio.vhd): `modules/oled_noRGB/oled_spi_mmio.vhd`

### Other components

- **Assembly Source**
- **Machine Code**
- **Basys 3 Board**

## Connections

- Assembly Source → Assembler: reads (evidence: `compiler/assembler.py`)
- Assembler → Machine Code: writes (evidence: `compiler/assembler.py`)
- FPGA Top Level → CPU Core: integrates
- CPU Core → Fetch High: fetches
- Fetch High → Fetch Low: continues fetch (evidence: `README.md`)
- Fetch Low → Execute: then executes (evidence: `README.md`)
- CPU Core → Instruction Decode: decodes
- CPU Core → Control Unit: controls
- CPU Core → Datapath: uses
- CPU Core → Hazard and Forwarding: uses
- CPU Core → Instruction ROM: fetches instructions
- CPU Core → Data RAM: accesses data
- CPU Core → Memory-Mapped I/O: maps I/O
- Memory-Mapped I/O → Keypad Controller: routes input
- Memory-Mapped I/O → Display Subsystem: routes output
- Display Subsystem → Display Manager: uses
- Display Subsystem → LCD Controller: uses
- LCD Controller → I2C Master: uses
- Memory-Mapped I/O → OLED SPI MMIO: routes output
- FPGA Top Level → Basys 3 Board: targets
