# sreansh-sudo/mnist-fpga architecture

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

- Interactive diagram: https://gitdiagram.com/sreansh-sudo/mnist-fpga
- Repository: https://github.com/sreansh-sudo/mnist-fpga

## Overview

MNIST-FPGA is an end-to-end quantized MNIST inference project targeting the Tang Nano 20K. Its main workflow trains a PyTorch model, establishes and validates integer quantization, exports parameters and test vectors as memory files, runs an RTL inference datapath, and presents the predicted digit on the board. Major hardware stages include FC1, ReLU/requantization, FC2, and argmax; a Tang Nano wrapper integrates the design. The README documents the broader verification and physical-validation flow, but sampled source does not show all RTL wiring or board-level behavior, so those relationships are cited to the README.

Main entry points: [`data`](https://github.com/sreansh-sudo/mnist-fpga/tree/main/data) (Initialized memories), [`python/train.py`](https://github.com/sreansh-sudo/mnist-fpga/blob/main/python/train.py) (PyTorch training), [`rtl/fc2.v`](https://github.com/sreansh-sudo/mnist-fpga/blob/main/rtl/fc2.v) (FC2 compute), [`gowin/mnist_fpga_phase4/mnist_fpga_phase4/src/mnist_tang_nano20k.v`](https://github.com/sreansh-sudo/mnist-fpga/blob/main/gowin/mnist_fpga_phase4/mnist_fpga_phase4/src/mnist_tang_nano20k.v) (Tang Nano wrapper)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_software["Model and quantization"]
  node_trainer["PyTorch training<br/>[train.py]"]
  node_quantization["Integer quantization"]
end

subgraph group_export["Parameter export"]
  node_fc1_export["FC1 parameter export"]
  node_fc2_export["FC2 parameter export"]
  node_bias_export["Bias export"]
  node_vector_export["Test-vector export"]
  node_bram_pack["FC1 BRAM packing"]
  node_memories["Initialized memories"]
end

subgraph group_inference["RTL inference"]
  node_fc1["FC1 compute<br/>[fc1.v]"]
  node_fc1_support["FC1 control and MAC<br/>[fc1_controller.v]"]
  node_fc1_activation["Requantize and ReLU<br/>[fc1_requant_relu.v]"]
  node_activation_memory["Activation memory"]
  node_fc2["FC2 compute<br/>[fc2.v]"]
  node_fc2_support["FC2 control and MAC<br/>[fc2_controller.v]"]
  node_argmax["Digit argmax<br/>[argmax10.v]"]
  node_top["Inference integration<br/>[mnist_top.v]"]
end

subgraph group_integration["Board integration"]
  node_board_wrapper["Tang Nano wrapper"]
  node_pll["Clock generation<br/>[gowin_rpll.v]"]
end

subgraph group_validation["Validation"]
  node_verification["RTL verification"]
end

node_mnist_data(("MNIST samples"))
node_fpga["Tang Nano 20K"]
node_prediction(("Predicted digit"))

node_mnist_data -->|"trains on"| node_trainer
node_trainer -->|"provides model"| node_quantization
node_quantization -->|"sets integer parameters"| node_fc1_export
node_trainer -->|"exports weights"| node_fc1_export
node_trainer -->|"exports weights"| node_fc2_export
node_trainer -->|"exports biases"| node_bias_export
node_mnist_data -->|"selects test image"| node_vector_export
node_vector_export -->|"writes vectors"| node_memories
node_fc1_export -->|"writes banks"| node_memories
node_fc2_export -->|"writes banks"| node_memories
node_bias_export -->|"writes biases"| node_memories
node_memories -->|"provides FC1 banks"| node_bram_pack
node_bram_pack -->|"writes packed weights"| node_memories
node_memories -->|"initializes parameters"| node_fc1
node_fc1 -->|"uses control and MAC"| node_fc1_support
node_fc1 -->|"requantizes output"| node_fc1_activation
node_fc1_activation -->|"stores activations"| node_activation_memory
node_activation_memory -->|"supplies activations"| node_fc2
node_memories -->|"initializes parameters"| node_fc2
node_fc2 -->|"uses control and MAC"| node_fc2_support
node_fc2 -->|"produces logits"| node_argmax
node_argmax -->|"returns prediction"| node_top
node_top -->|"integrated by"| node_board_wrapper
node_board_wrapper -->|"uses clock"| node_pll
node_board_wrapper -->|"runs on"| node_fpga
node_fpga -->|"displays digit"| node_prediction
node_memories -->|"provides test vectors"| node_verification
node_top -->|"verified by"| node_verification
node_verification -->|"simulates wrapper"| node_board_wrapper

click node_trainer "https://github.com/sreansh-sudo/mnist-fpga/blob/main/python/train.py"
click node_quantization "https://github.com/sreansh-sudo/mnist-fpga/blob/main/python/phase2/experiment_full_integer.py"
click node_fc1_export "https://github.com/sreansh-sudo/mnist-fpga/blob/main/python/phase3/generate_fc1_mem.py"
click node_fc2_export "https://github.com/sreansh-sudo/mnist-fpga/blob/main/python/phase3/generate_fc2_mem.py"
click node_bias_export "https://github.com/sreansh-sudo/mnist-fpga/tree/main/python/phase3"
click node_vector_export "https://github.com/sreansh-sudo/mnist-fpga/blob/main/python/phase3/generate_fc1_test_vector.py"
click node_bram_pack "https://github.com/sreansh-sudo/mnist-fpga/blob/main/python/phase4/create_fc1_bram_mem.py"
click node_memories "https://github.com/sreansh-sudo/mnist-fpga/tree/main/data"
click node_fc1 "https://github.com/sreansh-sudo/mnist-fpga/blob/main/rtl/fc1.v"
click node_fc1_support "https://github.com/sreansh-sudo/mnist-fpga/blob/main/rtl/fc1_controller.v"
click node_fc1_activation "https://github.com/sreansh-sudo/mnist-fpga/blob/main/rtl/fc1_requant_relu.v"
click node_activation_memory "https://github.com/sreansh-sudo/mnist-fpga/blob/main/rtl/fc1_activation_mem.v"
click node_fc2 "https://github.com/sreansh-sudo/mnist-fpga/blob/main/rtl/fc2.v"
click node_fc2_support "https://github.com/sreansh-sudo/mnist-fpga/blob/main/rtl/fc2_controller.v"
click node_argmax "https://github.com/sreansh-sudo/mnist-fpga/blob/main/rtl/argmax10.v"
click node_top "https://github.com/sreansh-sudo/mnist-fpga/blob/main/rtl/mnist_top.v"
click node_board_wrapper "https://github.com/sreansh-sudo/mnist-fpga/blob/main/gowin/mnist_fpga_phase4/mnist_fpga_phase4/src/mnist_tang_nano20k.v"
click node_pll "https://github.com/sreansh-sudo/mnist-fpga/blob/main/gowin/mnist_fpga_phase4/mnist_fpga_phase4/src/gowin_rpll/gowin_rpll.v"
click node_verification "https://github.com/sreansh-sudo/mnist-fpga/tree/main/tb"

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_trainer,node_quantization toneBlue
class node_fc1_export,node_fc2_export,node_bias_export,node_vector_export,node_bram_pack,node_memories toneAmber
class node_fc1,node_fc1_support,node_fc1_activation,node_activation_memory,node_fc2,node_fc2_support,node_argmax,node_top toneMint
class node_board_wrapper,node_pll toneRose
class node_verification,node_mnist_data,node_fpga,node_prediction toneIndigo
```

## Components

### Model and quantization

- [PyTorch training](https://github.com/sreansh-sudo/mnist-fpga/blob/main/python/train.py): `python/train.py`
- [Integer quantization](https://github.com/sreansh-sudo/mnist-fpga/blob/main/python/phase2/experiment_full_integer.py): `python/phase2/experiment_full_integer.py`

### Parameter export

- [FC1 parameter export](https://github.com/sreansh-sudo/mnist-fpga/blob/main/python/phase3/generate_fc1_mem.py): `python/phase3/generate_fc1_mem.py`
- [FC2 parameter export](https://github.com/sreansh-sudo/mnist-fpga/blob/main/python/phase3/generate_fc2_mem.py): `python/phase3/generate_fc2_mem.py`
- [Bias export](https://github.com/sreansh-sudo/mnist-fpga/tree/main/python/phase3): `python/phase3`
- [Test-vector export](https://github.com/sreansh-sudo/mnist-fpga/blob/main/python/phase3/generate_fc1_test_vector.py): `python/phase3/generate_fc1_test_vector.py`
- [FC1 BRAM packing](https://github.com/sreansh-sudo/mnist-fpga/blob/main/python/phase4/create_fc1_bram_mem.py): `python/phase4/create_fc1_bram_mem.py`
- [Initialized memories](https://github.com/sreansh-sudo/mnist-fpga/tree/main/data): `data`

### RTL inference

- [FC1 compute](https://github.com/sreansh-sudo/mnist-fpga/blob/main/rtl/fc1.v): `rtl/fc1.v`
- [FC1 control and MAC](https://github.com/sreansh-sudo/mnist-fpga/blob/main/rtl/fc1_controller.v): `rtl/fc1_controller.v`
- [Requantize and ReLU](https://github.com/sreansh-sudo/mnist-fpga/blob/main/rtl/fc1_requant_relu.v): `rtl/fc1_requant_relu.v`
- [Activation memory](https://github.com/sreansh-sudo/mnist-fpga/blob/main/rtl/fc1_activation_mem.v): `rtl/fc1_activation_mem.v`
- [FC2 compute](https://github.com/sreansh-sudo/mnist-fpga/blob/main/rtl/fc2.v): `rtl/fc2.v`
- [FC2 control and MAC](https://github.com/sreansh-sudo/mnist-fpga/blob/main/rtl/fc2_controller.v): `rtl/fc2_controller.v`
- [Digit argmax](https://github.com/sreansh-sudo/mnist-fpga/blob/main/rtl/argmax10.v): `rtl/argmax10.v`
- [Inference integration](https://github.com/sreansh-sudo/mnist-fpga/blob/main/rtl/mnist_top.v): `rtl/mnist_top.v`

### Board integration

- [Tang Nano wrapper](https://github.com/sreansh-sudo/mnist-fpga/blob/main/gowin/mnist_fpga_phase4/mnist_fpga_phase4/src/mnist_tang_nano20k.v): `gowin/mnist_fpga_phase4/mnist_fpga_phase4/src/mnist_tang_nano20k.v`
- [Clock generation](https://github.com/sreansh-sudo/mnist-fpga/blob/main/gowin/mnist_fpga_phase4/mnist_fpga_phase4/src/gowin_rpll/gowin_rpll.v): `gowin/mnist_fpga_phase4/mnist_fpga_phase4/src/gowin_rpll/gowin_rpll.v`

### Validation

- [RTL verification](https://github.com/sreansh-sudo/mnist-fpga/tree/main/tb): `tb`

### Other components

- **MNIST samples**
- **Tang Nano 20K**
- **Predicted digit**

## Connections

- MNIST samples → PyTorch training: trains on (evidence: `README.md`)
- PyTorch training → Integer quantization: provides model (evidence: `README.md`)
- Integer quantization → FC1 parameter export: sets integer parameters (evidence: `README.md`)
- PyTorch training → FC1 parameter export: exports weights (evidence: `README.md`)
- PyTorch training → FC2 parameter export: exports weights (evidence: `README.md`)
- PyTorch training → Bias export: exports biases (evidence: `README.md`)
- MNIST samples → Test-vector export: selects test image (evidence: `README.md`)
- Test-vector export → Initialized memories: writes vectors (evidence: `python/phase3/generate_fc1_test_vector.py`)
- FC1 parameter export → Initialized memories: writes banks (evidence: `python/phase3/generate_fc1_mem.py`)
- FC2 parameter export → Initialized memories: writes banks (evidence: `python/phase3/generate_fc2_mem.py`)
- Bias export → Initialized memories: writes biases (evidence: `README.md`)
- Initialized memories → FC1 BRAM packing: provides FC1 banks (evidence: `python/phase4/create_fc1_bram_mem.py`)
- FC1 BRAM packing → Initialized memories: writes packed weights (evidence: `python/phase4/create_fc1_bram_mem.py`)
- Initialized memories → FC1 compute: initializes parameters (evidence: `README.md`)
- FC1 compute → FC1 control and MAC: uses control and MAC (evidence: `README.md`)
- FC1 compute → Requantize and ReLU: requantizes output (evidence: `README.md`)
- Requantize and ReLU → Activation memory: stores activations (evidence: `README.md`)
- Activation memory → FC2 compute: supplies activations (evidence: `README.md`)
- Initialized memories → FC2 compute: initializes parameters (evidence: `README.md`)
- FC2 compute → FC2 control and MAC: uses control and MAC (evidence: `README.md`)
- FC2 compute → Digit argmax: produces logits (evidence: `README.md`)
- Digit argmax → Inference integration: returns prediction (evidence: `README.md`)
- Inference integration → Tang Nano wrapper: integrated by (evidence: `README.md`)
- Tang Nano wrapper → Clock generation: uses clock (evidence: `README.md`)
- Tang Nano wrapper → Tang Nano 20K: runs on (evidence: `README.md`)
- Tang Nano 20K → Predicted digit: displays digit (evidence: `README.md`)
- Initialized memories → RTL verification: provides test vectors (evidence: `README.md`)
- Inference integration → RTL verification: verified by (evidence: `README.md`)
- RTL verification → Tang Nano wrapper: simulates wrapper (evidence: `README.md`)