sreansh-sudo/mnist-fpga

How sreansh-sudo/mnist-fpga works

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 Initialized memories · train.py PyTorch training · fc2.v FC2 compute · mnist_tang_nano20k.v Tang Nano wrapper

Components 22

Model and quantization

PyTorch training python/train.py
Integer quantization python/phase2/experiment_full_integer.py

Parameter export

FC1 parameter export python/phase3/generate_fc1_mem.py
FC2 parameter export python/phase3/generate_fc2_mem.py
Bias export python/phase3
Test-vector export python/phase3/generate_fc1_test_vector.py
FC1 BRAM packing python/phase4/create_fc1_bram_mem.py
Initialized memories data

RTL inference

FC1 compute rtl/fc1.v
FC1 control and MAC rtl/fc1_controller.v
Requantize and ReLU rtl/fc1_requant_relu.v
Activation memory rtl/fc1_activation_mem.v
FC2 compute rtl/fc2.v
FC2 control and MAC rtl/fc2_controller.v
Digit argmax rtl/argmax10.v
Inference integration rtl/mnist_top.v

Board integration

Tang Nano wrapper gowin/mnist_fpga_phase4/mnist_fpga_phase4/src/mnist_tang_nano20k.v
Clock generation gowin/mnist_fpga_phase4/mnist_fpga_phase4/src/gowin_rpll/gowin_rpll.v

Validation

RTL verification tb

Other components

MNIST samples
Tang Nano 20K
Predicted digit

Connections 29

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

More Verilog diagrams: thedatabusdotio/fpga-ml-accelerator · ash-olakangal/risc-v-processor · excessivemotion/controller-software · kasirga-kizil/tekno-kizil · neelkshah/mips-processor

Drawn by GitDiagram on September 30, 2026 from the repository's file tree, README and source files. Read as Markdown ·