# srekrishnas05/soc architecture

> Architecture diagram of the GitHub repository srekrishnas05/soc, 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/srekrishnas05/soc
- Repository: https://github.com/srekrishnas05/soc

## Overview

This VHDL-2008 SoC runs bare-metal software on a five-stage ARMv7 CPU and includes a heterogeneous INT8 NPU cluster. The principal workflow is CPU job submission over MMIO, static tile planning, schedule storage, dispatch across clock domains, and systolic-array computation. The graph preserves the documented CPU features, memory/fabric roles, and NPU control and CDC stages. Source excerpts were unavailable, so relationships are limited to those stated in the README; implementation details beyond it are not inferred.

Main entry points: [`rtl/cpu/datapath.vhd`](https://github.com/srekrishnas05/soc/blob/master/rtl/cpu/datapath.vhd) (CPU Datapath), [`rtl/npu/npu_wrapper.vhd`](https://github.com/srekrishnas05/soc/blob/master/rtl/npu/npu_wrapper.vhd) (NPU Wrapper), [`rtl/npu/controller_fsm.vhd`](https://github.com/srekrishnas05/soc/blob/master/rtl/npu/controller_fsm.vhd) (NPU Sequencer), [`rtl/npu/systolic_array.vhd`](https://github.com/srekrishnas05/soc/blob/master/rtl/npu/systolic_array.vhd) (Systolic Array)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cpu["ARMv7 CPU"]
  node_datapath["CPU Datapath<br/>[datapath.vhd]"]
  node_control["CPU Control<br/>[controlunit.vhd]"]
  node_hazards["Hazard Unit<br/>[hazardunit.vhd]"]
  node_alu["ALU<br/>[alu.vhd]"]
  node_multiplier["Wallace Multiplier<br/>[wallacemul.vhd]"]
  node_branch_predictor["Branch Predictor<br/>[branchp.vhd]"]
end

subgraph group_fabric_memory["Fabric and Memory"]
  node_mmio["MMIO Bus<br/>[mmiobus.vhd]"]
  node_dcache["Data Cache<br/>[dcache.vhd]"]
  node_imem["Instruction Memory<br/>[imem.vhd]"]
  node_buffers[("Ping-Pong Buffers")]
end

subgraph group_npu_control["NPU Scheduling"]
  node_wrapper["NPU Wrapper<br/>[npu_wrapper.vhd]"]
  node_planner["Tile Planner<br/>[tile_planner.vhd]"]
  node_schedule[("Schedule RAM<br/>[sched_ram.vhd]")]
  node_dispatch["Dispatch FSM<br/>[dispatch_fsm.vhd]"]
  node_command_fifo["Command FIFO<br/>[async_fifo.vhd]"]
  node_sequencer["NPU Sequencer<br/>[controller_fsm.vhd]"]
  node_done_sync["Done Synchronizer<br/>[cdc_pulse_sync.vhd]"]
end

subgraph group_npu_compute["NPU Compute"]
  node_cluster["NPU Cluster"]
  node_accelerator["Accelerator"]
  node_skew["Skew Injector<br/>[skew_injector.vhd]"]
  node_array["Systolic Array<br/>[systolic_array.vhd]"]
  node_pe["Processing Element<br/>[pe.vhd]"]
end

node_software(("Bare-metal Software"))
node_soc["SoC Top<br/>[top.vhd]"]

node_software -->|"submits job"| node_datapath
node_soc -->|"integrates CPU"| node_datapath
node_datapath -->|"routes memory access"| node_mmio
node_datapath -->|"uses data cache"| node_dcache
node_datapath -.->|"fetches instructions"| node_imem
node_datapath -.->|"uses control"| node_control
node_datapath -->|"checks hazards"| node_hazards
node_datapath -.->|"executes operations"| node_alu
node_datapath -->|"requests multiply"| node_multiplier
node_datapath -->|"uses prediction"| node_branch_predictor
node_mmio -->|"routes peripheral access"| node_wrapper
node_wrapper -->|"sequences tile loads"| node_buffers
node_wrapper -.->|"bridges NPU access"| node_cluster
node_cluster -->|"plans tiles"| node_planner
node_planner -->|"writes schedule"| node_schedule
node_dispatch -->|"reads schedule"| node_schedule
node_dispatch -->|"issues descriptors"| node_command_fifo
node_command_fifo -->|"delivers descriptors"| node_sequencer
node_sequencer -->|"starts computation"| node_accelerator
node_accelerator -->|"runs array"| node_array
node_array -->|"receives skewed operands"| node_skew
node_array -.->|"uses processing elements"| node_pe
node_sequencer -->|"synchronizes completion"| node_done_sync
node_done_sync -.->|"signals completion"| node_dispatch

click node_soc "https://github.com/srekrishnas05/soc/blob/master/top.vhd"
click node_datapath "https://github.com/srekrishnas05/soc/blob/master/rtl/cpu/datapath.vhd"
click node_control "https://github.com/srekrishnas05/soc/blob/master/rtl/cpu/controlunit.vhd"
click node_hazards "https://github.com/srekrishnas05/soc/blob/master/rtl/cpu/hazardunit.vhd"
click node_alu "https://github.com/srekrishnas05/soc/blob/master/rtl/cpu/alu.vhd"
click node_multiplier "https://github.com/srekrishnas05/soc/blob/master/rtl/cpu/wallacemul.vhd"
click node_branch_predictor "https://github.com/srekrishnas05/soc/blob/master/rtl/cpu/branchp.vhd"
click node_mmio "https://github.com/srekrishnas05/soc/blob/master/rtl/fabric/mmiobus.vhd"
click node_dcache "https://github.com/srekrishnas05/soc/blob/master/rtl/memory/dcache.vhd"
click node_imem "https://github.com/srekrishnas05/soc/blob/master/rtl/memory/imem.vhd"
click node_wrapper "https://github.com/srekrishnas05/soc/blob/master/rtl/npu/npu_wrapper.vhd"
click node_planner "https://github.com/srekrishnas05/soc/blob/master/rtl/npu/tile_planner.vhd"
click node_schedule "https://github.com/srekrishnas05/soc/blob/master/rtl/memory/sched_ram.vhd"
click node_dispatch "https://github.com/srekrishnas05/soc/blob/master/rtl/npu/dispatch_fsm.vhd"
click node_command_fifo "https://github.com/srekrishnas05/soc/blob/master/rtl/fabric/async_fifo.vhd"
click node_sequencer "https://github.com/srekrishnas05/soc/blob/master/rtl/npu/controller_fsm.vhd"
click node_done_sync "https://github.com/srekrishnas05/soc/blob/master/rtl/fabric/cdc_pulse_sync.vhd"
click node_cluster "https://github.com/srekrishnas05/soc/blob/master/rtl/npu/npu_cluster_top.vhd"
click node_accelerator "https://github.com/srekrishnas05/soc/blob/master/rtl/npu/accelerator_top.vhd"
click node_skew "https://github.com/srekrishnas05/soc/blob/master/rtl/npu/skew_injector.vhd"
click node_array "https://github.com/srekrishnas05/soc/blob/master/rtl/npu/systolic_array.vhd"
click node_pe "https://github.com/srekrishnas05/soc/blob/master/rtl/npu/pe.vhd"
click node_buffers "https://github.com/srekrishnas05/soc/blob/master/rtl/memory/ping_pong_buffer.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_datapath,node_control,node_hazards,node_alu,node_multiplier,node_branch_predictor toneBlue
class node_mmio,node_dcache,node_imem,node_buffers toneAmber
class node_wrapper,node_planner,node_schedule,node_dispatch,node_command_fifo,node_sequencer,node_done_sync toneMint
class node_cluster,node_accelerator,node_skew,node_array,node_pe toneRose
class node_software toneIndigo
class node_soc toneTeal
```

## Components

### ARMv7 CPU

- [CPU Datapath](https://github.com/srekrishnas05/soc/blob/master/rtl/cpu/datapath.vhd): `rtl/cpu/datapath.vhd`
- [CPU Control](https://github.com/srekrishnas05/soc/blob/master/rtl/cpu/controlunit.vhd): `rtl/cpu/controlunit.vhd`
- [Hazard Unit](https://github.com/srekrishnas05/soc/blob/master/rtl/cpu/hazardunit.vhd): `rtl/cpu/hazardunit.vhd`
- [ALU](https://github.com/srekrishnas05/soc/blob/master/rtl/cpu/alu.vhd): `rtl/cpu/alu.vhd`
- [Wallace Multiplier](https://github.com/srekrishnas05/soc/blob/master/rtl/cpu/wallacemul.vhd): `rtl/cpu/wallacemul.vhd`
- [Branch Predictor](https://github.com/srekrishnas05/soc/blob/master/rtl/cpu/branchp.vhd): `rtl/cpu/branchp.vhd`

### Fabric and Memory

- [MMIO Bus](https://github.com/srekrishnas05/soc/blob/master/rtl/fabric/mmiobus.vhd): `rtl/fabric/mmiobus.vhd`
- [Data Cache](https://github.com/srekrishnas05/soc/blob/master/rtl/memory/dcache.vhd): `rtl/memory/dcache.vhd`
- [Instruction Memory](https://github.com/srekrishnas05/soc/blob/master/rtl/memory/imem.vhd): `rtl/memory/imem.vhd`
- [Ping-Pong Buffers](https://github.com/srekrishnas05/soc/blob/master/rtl/memory/ping_pong_buffer.vhd): `rtl/memory/ping_pong_buffer.vhd`

### NPU Scheduling

- [NPU Wrapper](https://github.com/srekrishnas05/soc/blob/master/rtl/npu/npu_wrapper.vhd): `rtl/npu/npu_wrapper.vhd`
- [Tile Planner](https://github.com/srekrishnas05/soc/blob/master/rtl/npu/tile_planner.vhd): `rtl/npu/tile_planner.vhd`
- [Schedule RAM](https://github.com/srekrishnas05/soc/blob/master/rtl/memory/sched_ram.vhd): `rtl/memory/sched_ram.vhd`
- [Dispatch FSM](https://github.com/srekrishnas05/soc/blob/master/rtl/npu/dispatch_fsm.vhd): `rtl/npu/dispatch_fsm.vhd`
- [Command FIFO](https://github.com/srekrishnas05/soc/blob/master/rtl/fabric/async_fifo.vhd): `rtl/fabric/async_fifo.vhd`
- [NPU Sequencer](https://github.com/srekrishnas05/soc/blob/master/rtl/npu/controller_fsm.vhd): `rtl/npu/controller_fsm.vhd`
- [Done Synchronizer](https://github.com/srekrishnas05/soc/blob/master/rtl/fabric/cdc_pulse_sync.vhd): `rtl/fabric/cdc_pulse_sync.vhd`

### NPU Compute

- [NPU Cluster](https://github.com/srekrishnas05/soc/blob/master/rtl/npu/npu_cluster_top.vhd): `rtl/npu/npu_cluster_top.vhd`
- [Accelerator](https://github.com/srekrishnas05/soc/blob/master/rtl/npu/accelerator_top.vhd): `rtl/npu/accelerator_top.vhd`
- [Skew Injector](https://github.com/srekrishnas05/soc/blob/master/rtl/npu/skew_injector.vhd): `rtl/npu/skew_injector.vhd`
- [Systolic Array](https://github.com/srekrishnas05/soc/blob/master/rtl/npu/systolic_array.vhd): `rtl/npu/systolic_array.vhd`
- [Processing Element](https://github.com/srekrishnas05/soc/blob/master/rtl/npu/pe.vhd): `rtl/npu/pe.vhd`

### Other components

- **Bare-metal Software**
- [SoC Top](https://github.com/srekrishnas05/soc/blob/master/top.vhd): `top.vhd`

## Connections

- Bare-metal Software → CPU Datapath: submits job (evidence: `README.md`)
- SoC Top → CPU Datapath: integrates CPU (evidence: `README.md`)
- CPU Datapath → MMIO Bus: routes memory access (evidence: `README.md`)
- CPU Datapath → Data Cache: uses data cache (evidence: `README.md`)
- CPU Datapath → Instruction Memory: fetches instructions
- CPU Datapath → CPU Control: uses control
- CPU Datapath → Hazard Unit: checks hazards (evidence: `README.md`)
- CPU Datapath → ALU: executes operations
- CPU Datapath → Wallace Multiplier: requests multiply (evidence: `README.md`)
- CPU Datapath → Branch Predictor: uses prediction (evidence: `README.md`)
- MMIO Bus → NPU Wrapper: routes peripheral access (evidence: `README.md`)
- NPU Wrapper → Ping-Pong Buffers: sequences tile loads (evidence: `README.md`)
- NPU Wrapper → NPU Cluster: bridges NPU access
- NPU Cluster → Tile Planner: plans tiles (evidence: `README.md`)
- Tile Planner → Schedule RAM: writes schedule (evidence: `README.md`)
- Dispatch FSM → Schedule RAM: reads schedule (evidence: `README.md`)
- Dispatch FSM → Command FIFO: issues descriptors (evidence: `README.md`)
- Command FIFO → NPU Sequencer: delivers descriptors (evidence: `README.md`)
- NPU Sequencer → Accelerator: starts computation (evidence: `README.md`)
- Accelerator → Systolic Array: runs array (evidence: `README.md`)
- Systolic Array → Skew Injector: receives skewed operands (evidence: `README.md`)
- Systolic Array → Processing Element: uses processing elements
- NPU Sequencer → Done Synchronizer: synchronizes completion (evidence: `README.md`)
- Done Synchronizer → Dispatch FSM: signals completion
