# rkycodes/opencorex architecture

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

- Interactive diagram: https://gitdiagram.com/rkycodes/opencorex
- Repository: https://github.com/rkycodes/opencorex

## Overview

OpenCoreX is a simulation-focused multicycle RV32 subset CPU with scalar multiply and a blocking, single-lane digital matvec accelerator. Its runtime path executes program images on the CPU, uses a shared RAM interface, and can submit accelerator work; the repository also provides generation and study tooling for matvec, GEMM, scaling, cache, convolution, tiling, and latency experiments. RTL wiring is not excerpted here, so hardware links below rely on README-level descriptions; study-tool links use the supplied source index.

Main entry points: [`scripts/run_cache_study.py`](https://github.com/rkycodes/opencorex/blob/main/scripts/run_cache_study.py) (Cache Study), [`scripts/run_gemm_large.py`](https://github.com/rkycodes/opencorex/blob/main/scripts/run_gemm_large.py) (Large GEMM), [`docs/evaluation`](https://github.com/rkycodes/opencorex/tree/main/docs/evaluation) (Study Results), [`rtl/cpu/opencorex_core.sv`](https://github.com/rkycodes/opencorex/blob/main/rtl/cpu/opencorex_core.sv) (RV32 Core)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cpu["CPU Core"]
  node_core["RV32 Core<br/>[opencorex_core.sv]"]
  node_control["Decode Control<br/>[controller.sv]"]
  node_datapath["Execution Datapath<br/>[datapath.sv]"]
  node_alu["ALU<br/>[alu.sv]"]
  node_registers["Register File<br/>[register_file.sv]"]
end

subgraph group_memory["Memory System"]
  node_memorysub["Memory Subsystem"]
  node_router["Address Router"]
  node_ram[("Shared RAM<br/>[memory.sv]")]
  node_interconnect["Memory Interconnect"]
  node_icache["Instruction Cache"]
end

subgraph group_accelerator["PIM Accelerator"]
  node_pimsystem["PIM Subsystem"]
  node_accelerator["Matvec Accelerator<br/>[pim_accelerator.sv]"]
  node_command["Command Validation"]
  node_buffer["Vector Buffer"]
end

subgraph group_experiments["Benchmark Studies"]
  node_gemmstudy["GEMM Studies<br/>[run_gemm_study.py]"]
  node_largestudy["Large GEMM<br/>[run_gemm_large.py]"]
  node_scalingstudy["Scaling Study"]
  node_tilingstudy["Tiling Study"]
  node_cachestudy["Cache Study<br/>[run_cache_study.py]"]
  node_latency["Latency Sweep"]
  node_convstudy["Conv1 Study<br/>[run_conv1_study.py]"]
  node_results["Study Results"]
end

subgraph group_tooling["Generation and Replay"]
  node_programs["Program Images"]
  node_generator["Image Generator"]
  node_gemmgen["GEMM Generator<br/>[generate_gemm.py]"]
  node_convgen["Conv1 Generator<br/>[generate_conv1.py]"]
  node_trace["Independent Replay"]
end

node_engineer(("Engineer"))

node_engineer -->|"selects image"| node_programs
node_programs -->|"executes image"| node_core
node_core -.->|"runs instructions"| node_datapath
node_core -.->|"decodes instructions"| node_control
node_datapath -.->|"reads registers"| node_registers
node_datapath -.->|"performs arithmetic"| node_alu
node_core -->|"accesses memory"| node_memorysub
node_memorysub -.->|"routes addresses"| node_router
node_memorysub -->|"uses shared port"| node_interconnect
node_interconnect -->|"accesses RAM"| node_ram
node_memorysub -.->|"fetches instructions"| node_icache
node_core -->|"launches work"| node_pimsystem
node_pimsystem -.->|"dispatches commands"| node_accelerator
node_accelerator -.->|"validates commands"| node_command
node_accelerator -->|"uses vector buffer"| node_buffer
node_engineer -->|"generates inputs"| node_generator
node_generator -.->|"writes images"| node_programs
node_gemmgen -->|"reuses encoders"| node_generator
node_gemmgen -->|"generates GEMM images"| node_programs
node_engineer -->|"runs study"| node_gemmstudy
node_gemmstudy -->|"generates programs"| node_gemmgen
node_gemmstudy -->|"runs cache cases"| node_cachestudy
node_gemmstudy -->|"uses latency fields"| node_latency
node_largestudy -->|"generates programs"| node_gemmgen
node_largestudy -->|"runs cache cases"| node_cachestudy
node_largestudy -->|"uses latency sweep"| node_latency
node_largestudy -->|"replays traces"| node_trace
node_scalingstudy -->|"runs cache study"| node_cachestudy
node_scalingstudy -->|"uses latency sweep"| node_latency
node_tilingstudy -->|"runs cache study"| node_cachestudy
node_tilingstudy -->|"uses latency sweep"| node_latency
node_convstudy -->|"generates cases"| node_convgen
node_convstudy -->|"uses cache study"| node_cachestudy
node_gemmstudy -->|"records evidence"| node_results
node_engineer -->|"runs study"| node_largestudy
node_engineer -->|"runs study"| node_scalingstudy
node_engineer -->|"runs study"| node_tilingstudy
node_engineer -.->|"runs study"| node_convstudy
node_engineer -->|"runs study"| node_cachestudy
node_engineer -.->|"runs sweep"| node_latency
node_largestudy -->|"records evidence"| node_results
node_scalingstudy -->|"records evidence"| node_results
node_tilingstudy -->|"records evidence"| node_results
node_cachestudy -->|"records evidence"| node_results
node_convstudy -->|"records evidence"| node_results

click node_programs "https://github.com/rkycodes/opencorex/tree/main/programs"
click node_core "https://github.com/rkycodes/opencorex/blob/main/rtl/cpu/opencorex_core.sv"
click node_control "https://github.com/rkycodes/opencorex/blob/main/rtl/cpu/controller.sv"
click node_datapath "https://github.com/rkycodes/opencorex/blob/main/rtl/cpu/datapath.sv"
click node_alu "https://github.com/rkycodes/opencorex/blob/main/rtl/cpu/alu.sv"
click node_registers "https://github.com/rkycodes/opencorex/blob/main/rtl/cpu/register_file.sv"
click node_memorysub "https://github.com/rkycodes/opencorex/blob/main/rtl/system/opencorex_memory_subsystem.sv"
click node_router "https://github.com/rkycodes/opencorex/blob/main/rtl/system/cpu_address_router.sv"
click node_ram "https://github.com/rkycodes/opencorex/blob/main/rtl/memory/memory.sv"
click node_interconnect "https://github.com/rkycodes/opencorex/blob/main/rtl/memory/memory_interconnect.sv"
click node_icache "https://github.com/rkycodes/opencorex/blob/main/rtl/memory/instruction_cache.sv"
click node_pimsystem "https://github.com/rkycodes/opencorex/blob/main/rtl/system/opencorex_pim_subsystem.sv"
click node_accelerator "https://github.com/rkycodes/opencorex/blob/main/rtl/pim/pim_accelerator.sv"
click node_command "https://github.com/rkycodes/opencorex/blob/main/rtl/pim/pim_command_validator.sv"
click node_buffer "https://github.com/rkycodes/opencorex/blob/main/rtl/pim/pim_vector_buffer.sv"
click node_generator "https://github.com/rkycodes/opencorex/blob/main/scripts/generate_matvec_1x16_16x32.py"
click node_gemmgen "https://github.com/rkycodes/opencorex/blob/main/scripts/generate_gemm.py"
click node_gemmstudy "https://github.com/rkycodes/opencorex/blob/main/scripts/run_gemm_study.py"
click node_largestudy "https://github.com/rkycodes/opencorex/blob/main/scripts/run_gemm_large.py"
click node_scalingstudy "https://github.com/rkycodes/opencorex/blob/main/scripts/run_scaling_study.py"
click node_tilingstudy "https://github.com/rkycodes/opencorex/blob/main/scripts/run_tiling_study.py"
click node_cachestudy "https://github.com/rkycodes/opencorex/blob/main/scripts/run_cache_study.py"
click node_latency "https://github.com/rkycodes/opencorex/blob/main/scripts/run_memory_latency_sweep.py"
click node_convgen "https://github.com/rkycodes/opencorex/blob/main/scripts/generate_conv1.py"
click node_convstudy "https://github.com/rkycodes/opencorex/blob/main/scripts/run_conv1_study.py"
click node_trace "https://github.com/rkycodes/opencorex/blob/main/scripts/gemm_large_trace.py"
click node_results "https://github.com/rkycodes/opencorex/tree/main/docs/evaluation"

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_core,node_control,node_datapath,node_alu,node_registers toneBlue
class node_memorysub,node_router,node_ram,node_interconnect,node_icache toneAmber
class node_pimsystem,node_accelerator,node_command,node_buffer toneMint
class node_gemmstudy,node_largestudy,node_scalingstudy,node_tilingstudy,node_cachestudy,node_latency,node_convstudy,node_results toneRose
class node_programs,node_generator,node_gemmgen,node_convgen,node_trace,node_engineer toneIndigo
```

## Components

### CPU Core

- [RV32 Core](https://github.com/rkycodes/opencorex/blob/main/rtl/cpu/opencorex_core.sv): `rtl/cpu/opencorex_core.sv`
- [Decode Control](https://github.com/rkycodes/opencorex/blob/main/rtl/cpu/controller.sv): `rtl/cpu/controller.sv`
- [Execution Datapath](https://github.com/rkycodes/opencorex/blob/main/rtl/cpu/datapath.sv): `rtl/cpu/datapath.sv`
- [ALU](https://github.com/rkycodes/opencorex/blob/main/rtl/cpu/alu.sv): `rtl/cpu/alu.sv`
- [Register File](https://github.com/rkycodes/opencorex/blob/main/rtl/cpu/register_file.sv): `rtl/cpu/register_file.sv`

### Memory System

- [Memory Subsystem](https://github.com/rkycodes/opencorex/blob/main/rtl/system/opencorex_memory_subsystem.sv): `rtl/system/opencorex_memory_subsystem.sv`
- [Address Router](https://github.com/rkycodes/opencorex/blob/main/rtl/system/cpu_address_router.sv): `rtl/system/cpu_address_router.sv`
- [Shared RAM](https://github.com/rkycodes/opencorex/blob/main/rtl/memory/memory.sv): `rtl/memory/memory.sv`
- [Memory Interconnect](https://github.com/rkycodes/opencorex/blob/main/rtl/memory/memory_interconnect.sv): `rtl/memory/memory_interconnect.sv`
- [Instruction Cache](https://github.com/rkycodes/opencorex/blob/main/rtl/memory/instruction_cache.sv): `rtl/memory/instruction_cache.sv`

### PIM Accelerator

- [PIM Subsystem](https://github.com/rkycodes/opencorex/blob/main/rtl/system/opencorex_pim_subsystem.sv): `rtl/system/opencorex_pim_subsystem.sv`
- [Matvec Accelerator](https://github.com/rkycodes/opencorex/blob/main/rtl/pim/pim_accelerator.sv): `rtl/pim/pim_accelerator.sv`
- [Command Validation](https://github.com/rkycodes/opencorex/blob/main/rtl/pim/pim_command_validator.sv): `rtl/pim/pim_command_validator.sv`
- [Vector Buffer](https://github.com/rkycodes/opencorex/blob/main/rtl/pim/pim_vector_buffer.sv): `rtl/pim/pim_vector_buffer.sv`

### Benchmark Studies

- [GEMM Studies](https://github.com/rkycodes/opencorex/blob/main/scripts/run_gemm_study.py): `scripts/run_gemm_study.py`
- [Large GEMM](https://github.com/rkycodes/opencorex/blob/main/scripts/run_gemm_large.py): `scripts/run_gemm_large.py`
- [Scaling Study](https://github.com/rkycodes/opencorex/blob/main/scripts/run_scaling_study.py): `scripts/run_scaling_study.py`
- [Tiling Study](https://github.com/rkycodes/opencorex/blob/main/scripts/run_tiling_study.py): `scripts/run_tiling_study.py`
- [Cache Study](https://github.com/rkycodes/opencorex/blob/main/scripts/run_cache_study.py): `scripts/run_cache_study.py`
- [Latency Sweep](https://github.com/rkycodes/opencorex/blob/main/scripts/run_memory_latency_sweep.py): `scripts/run_memory_latency_sweep.py`
- [Conv1 Study](https://github.com/rkycodes/opencorex/blob/main/scripts/run_conv1_study.py): `scripts/run_conv1_study.py`
- [Study Results](https://github.com/rkycodes/opencorex/tree/main/docs/evaluation): `docs/evaluation`

### Generation and Replay

- [Program Images](https://github.com/rkycodes/opencorex/tree/main/programs): `programs`
- [Image Generator](https://github.com/rkycodes/opencorex/blob/main/scripts/generate_matvec_1x16_16x32.py): `scripts/generate_matvec_1x16_16x32.py`
- [GEMM Generator](https://github.com/rkycodes/opencorex/blob/main/scripts/generate_gemm.py): `scripts/generate_gemm.py`
- [Conv1 Generator](https://github.com/rkycodes/opencorex/blob/main/scripts/generate_conv1.py): `scripts/generate_conv1.py`
- [Independent Replay](https://github.com/rkycodes/opencorex/blob/main/scripts/gemm_large_trace.py): `scripts/gemm_large_trace.py`

### Other components

- **Engineer**

## Connections

- Engineer → Program Images: selects image (evidence: `README.md`)
- Program Images → RV32 Core: executes image (evidence: `README.md`)
- RV32 Core → Execution Datapath: runs instructions
- RV32 Core → Decode Control: decodes instructions
- Execution Datapath → Register File: reads registers
- Execution Datapath → ALU: performs arithmetic
- RV32 Core → Memory Subsystem: accesses memory (evidence: `README.md`)
- Memory Subsystem → Address Router: routes addresses
- Memory Subsystem → Memory Interconnect: uses shared port (evidence: `README.md`)
- Memory Interconnect → Shared RAM: accesses RAM (evidence: `README.md`)
- Memory Subsystem → Instruction Cache: fetches instructions
- RV32 Core → PIM Subsystem: launches work (evidence: `README.md`)
- PIM Subsystem → Matvec Accelerator: dispatches commands
- Matvec Accelerator → Command Validation: validates commands
- Matvec Accelerator → Vector Buffer: uses vector buffer (evidence: `README.md`)
- Engineer → Image Generator: generates inputs (evidence: `README.md`)
- Image Generator → Program Images: writes images
- GEMM Generator → Image Generator: reuses encoders (evidence: `scripts/generate_gemm.py`)
- GEMM Generator → Program Images: generates GEMM images (evidence: `scripts/generate_gemm.py`)
- Engineer → GEMM Studies: runs study (evidence: `README.md`)
- GEMM Studies → GEMM Generator: generates programs (evidence: `scripts/run_gemm_study.py`)
- GEMM Studies → Cache Study: runs cache cases (evidence: `scripts/run_gemm_study.py`)
- GEMM Studies → Latency Sweep: uses latency fields (evidence: `scripts/run_gemm_study.py`)
- Large GEMM → GEMM Generator: generates programs (evidence: `scripts/run_gemm_large.py`)
- Large GEMM → Cache Study: runs cache cases (evidence: `scripts/run_gemm_large.py`)
- Large GEMM → Latency Sweep: uses latency sweep (evidence: `scripts/run_gemm_large.py`)
- Large GEMM → Independent Replay: replays traces (evidence: `scripts/run_gemm_large.py`)
- Scaling Study → Cache Study: runs cache study (evidence: `scripts/run_scaling_study.py`)
- Scaling Study → Latency Sweep: uses latency sweep (evidence: `scripts/run_scaling_study.py`)
- Tiling Study → Cache Study: runs cache study (evidence: `scripts/run_tiling_study.py`)
- Tiling Study → Latency Sweep: uses latency sweep (evidence: `scripts/run_tiling_study.py`)
- Conv1 Study → Conv1 Generator: generates cases (evidence: `scripts/run_conv1_study.py`)
- Conv1 Study → Cache Study: uses cache study (evidence: `scripts/run_conv1_study.py`)
- GEMM Studies → Study Results: records evidence (evidence: `README.md`)
- Engineer → Large GEMM: runs study (evidence: `README.md`)
- Engineer → Scaling Study: runs study (evidence: `README.md`)
- Engineer → Tiling Study: runs study (evidence: `README.md`)
- Engineer → Conv1 Study: runs study
- Engineer → Cache Study: runs study (evidence: `README.md`)
- Engineer → Latency Sweep: runs sweep
- Large GEMM → Study Results: records evidence (evidence: `README.md`)
- Scaling Study → Study Results: records evidence (evidence: `README.md`)
- Tiling Study → Study Results: records evidence (evidence: `README.md`)
- Cache Study → Study Results: records evidence (evidence: `README.md`)
- Conv1 Study → Study Results: records evidence (evidence: `README.md`)