An open-source FPGA learning project for the Anlogic EG4S20 / HX4S20 board.
The current milestone implements a small INT4-weight MLP inference core:
2304 x INT8 input (48x48) -> FC1 32 hidden activations (ReLU) -> FC2 10 logits -> argmax
Weights are INT4 (W_W = 4, range [-8, 7]); activations/inputs stay INT8 to keep
the byte-stream UART interface simple. It is not intended to train a large neural network on
FPGA. The goal is to show a complete, resource-feasible hardware inference path on a
resource-limited FPGA: INT4 post-training quantization, parallel MAC, fully-connected layer
scheduling, UART input, UART result output, constraints, simulation, and board bring-up
that has been verified end-to-end on real MNIST.
- Real MNIST INT4 weights committed: trained on the real MNIST dataset with INT4
post-training quantization. Software reference accuracy:
- INT8 golden baseline: 96.57% (9657/10000 test images);
- INT4 deployed golden: ~94.87% (the model actually shipped to the bitstream).
- RTL vs golden consistency: PASS —
verify_mnist.pyreportsmax_logits_err = 0andpred 不一致 = 0with the committed weights. - Board bring-up verified:
tools/verify_board_uart.pyran 200/200 real MNIST frames on the HX4S20 and every回显 matched the golden model. The hardware path is proven, not just simulated. - Timing confirmed (no longer "to be re-confirmed"): with
set_clock_uncertainty -setup 0.100, synthesis reports Setup WNS ≈ +1045 ps and Hold WNS ≈ +14 ps (FEP = 0). The earlier "Too much hold violation" red error was a false violation caused by applying clock uncertainty to hold; it is fixed in the SDC. $readmemhblock-RAM init confirmed on hardware: the weight ROM uses a behavioral block RAM (rtl/int8/bram_rom_w.v) to avoid the TangDynastySYN-2594combinatorial-address weight-ROM collapse. The board returns correct digits, so BRAM init loads as expected.- Input quantization constant
SX0 = 0.022216is written tomem/quant_params.txt(required when sending real MNIST images from the PC; see Board Test).
rtl/
int8/
mac_array.v # 参数化并行 INT4/INT8 MAC 阵列(P=4,占 4 个 DSP)
fc_layer.v # 全连接层(行为级权重 ROM + 输入缓冲 + MAC 阵列 FSM)
bram_rom_w.v # 行为级 block RAM 权重 ROM($readmemh,避开 SYN-2594 塌缩)
relu.v # 组合 ReLU
argmax.v # 组合最大值索引
mnist_top.v # 顶层:FC1 -> FC2 -> argmax
mnist_stream_top.v # 字节流打包/解包接口
mnist_uart_board_top.v # UART 收发 + 板级顶层
uart_rx.v / uart_tx.v # 115200 8N1 串口
seg7_scan.v # 数码管扫描显示
mem/
l1_w.hex, l1_b.hex, l2_w.hex, l2_b.hex # 扁平权重(Python/golden 模型用)
l1_w_p4.hex, l2_w_p4.hex # P 交错 INT4 权重(fc_layer.v 上板用)
quant_params.txt # SX0 等量化常数(唯一真源)
constraints/
hx4s20_digit_demo.adc # 引脚约束
hx4s20_digit_demo.sdc # 时序约束(50MHz, -setup 0.100)
sim/
mnist_tb.v, mnist_stream_tb.v, mnist_uart_board_tb.v
tools/
mnist_config.py # 全局参数(Verilog 与 Python 的唯一真源)
int8_golden.py # 整型真值参考(与 RTL recipe 逐位一致)
int8_rtl_sim.py # 周期精确 RTL 模型
verify_mnist.py # 端到端对拍验证(主门禁)
verify_rtl_static.py # 静态 RTL 安全检查
verify_p4_hex.py # _p4.hex 字宽/自洽性静态审查(填补仿真盲区)
check_syn_log.py # 解析 TD run.log:检测 SYN-2594 / #bram9k / HDL-5007
repack_p4.py # 从扁平权重重交织生成正确的 _p4.hex(修复字宽 bug)
verify_board_uart.py # 板级对拍(真实 MNIST 200 帧,COM8/115200)
train_export_mnist.py # PyTorch 训练 + INT4 导出(真实可识别权重)
train_export_mnist_np.py # 纯 numpy 训练+导出(无需 torch)
gen_mnist_weights.py # 确定性演示权重生成
gen_board_test_bins.py / gen_board_test_bins_mnist.py # 生成板测帧
make_test_images.py # 合成数字测试图(无图也能跑)
capture_send.py # PC 采集/图片 -> 预处理 -> UART 发送(2304 字节)
capture_gui.pyw # 上述功能的可视化版本(tkinter,含打开/发送图片)
install_deps.bat # 一键安装依赖(opencv-python/pyserial/Pillow/numpy)
scripts/
run_verification.ps1 # 一键验证批处理
docs/
ARCHITECTURE.md, UART_BOARD_DEMO.md, BOARD_HX4S20.md,
PROJECT_DESCRIPTION.md, STREAM_INTERFACE.md, VERIFICATION_REPORT.md,
FPGA_MNIST_实验报告.docx, figures/
demo_inputs/ # 28x28 演示帧(早期 INT8 验证用,保留兼容)
demo_inputs48/ # 48x48 测试图(bin / png),当前主链路用
Run all software + RTL checks:
cd D:\path\to\repo
.\scripts\run_verification.ps1If Icarus Verilog is not installed:
.\scripts\run_verification.ps1 -SkipVerilogExpected result:
RTL static safety check: PASS
RTL/golden consistency: PASS
All enabled verification gates passed.
With the bitstream burned and the board powered, run the 200-frame real-MNIST
closed-loop check (defaults to COM8, 115200/8N1):
python tools\verify_board_uart.py --port COM8Expected: 板级对拍: 200/200 通过 (every回显 matches the golden model).
Target board/device:
Board: HX4S20
Device: EG4S20BG256
Clock: 50 MHz
UART: 115200 8N1
Top: mnist_uart_board_top
Weight bit-width: W_W = 4 (INT4), input IN_W = 8 (INT8)
Frame: 48x48 = 2304 bytes per inference
TangDynasty setup:
- Create a new EG4S20BG256 project.
- Add all Verilog files under
rtl/andrtl/int8/. - Set top module to
mnist_uart_board_top. - Add
constraints/hx4s20_digit_demo.adc. - Add
constraints/hx4s20_digit_demo.sdc. mem/is referenced by an absolute path inbram_rom_w.v($readmemh); make sure the path inmnist_config.MEM_DIR/ the ROM points atdsp_projects/mem. After editing_p4.hex, re-run synthesis + P&R + bitgen (weights are embedded at synthesis time).- Run synthesis, place and route, then generate bitstream.
Relevant pins:
| Top Port | Board Signal | FPGA Pin |
|---|---|---|
clk_50m |
50 MHz clock | R7 |
rst_n |
KEY1, active low | A2 |
uart_rx |
CH340 RXD | F12 |
uart_tx |
CH340 TXD | D12 |
led[0] |
LED1 | A4 |
led[1] |
LED2 | A3 |
led[2] |
LED3 | C10 |
led[3] |
LED4 | B12 |
Install the Python serial dependency once:
python -m pip install pyserialSend one demo image (48x48 frame, 2304 bytes):
python tools\send_digit_uart.py --port COM8 --digit 3Replace COM8 with the CH340 serial port shown by Windows Device Manager.
Expected response:
sent: ...digit_3_int8.hex (2304 bytes)
received: b'3\r\n'
prediction: 3
The bundled demo frames in demo_inputs48/ are real MNIST images pre-quantized with
SX0 (see mem/quant_params.txt), so sending them returns the correct digit. To send your
own image, normalize each pixel as (pixel/255 - 0.1307)/0.3081, then quantize to INT8 with
x_q = clip(round(x / SX0), -128, 127) and send those 2304 bytes (48x48).
When using a serial assistant, send the 48x48 frame (2304 bytes) as raw bytes. The FPGA returns ASCII digit + CR + LF, for example:
33 0D 0A
tools/capture_send.py completes the "PC photo -> preprocess -> FPGA recognize ->
seven-segment display" chain. It opens a camera or a local image and automatically:
- Grayscale;
- Otsu threshold to auto-detect polarity (black-on-white is inverted to MNIST-style white-on-black);
- Crop the digit bounding box, center it by centroid, scale to 48x48;
- Normalize
(pixel/255 - 0.1307)/0.3081+ INT8 quantizex_q = clip(round(x/SX0), -128, 127); - Send 2304 bytes over UART; FPGA echoes the digit, the on-board seven-segment (SW6 up) shows it synchronously.
Dependencies and usage (see tools/README.md):
python -m pip install opencv-python pyserial numpy
python tools\capture_send.py --port COM8 # camera, press c to capture+send
python tools\capture_send.py --port COM8 --live # auto continuous send
python tools\capture_send.py --image photo.png --simulate # local image + golden model (no HW)
python tools\capture_send.py --image photo.png --port COM8 # local image -> real UARTNote: the model is trained on clean, centered MNIST, so real photos need even lighting and a clear digit. If accuracy is low, first check whether the preprocessed 48x48 image resembles MNIST (white-on-black, centered).
For a mouse-only workflow, double-click 启动数字识别.vbs at the project root to launch
tools/capture_gui.pyw (tkinter, no console window). It supports:
- 打开图片: pick a digit photo, preview the 48x48 preprocessing and the local prediction;
- 发送图片: upload the image to the FPGA and show the board's回显 (select COM port first);
- 串口 / 极性 selectors, 拍照发送, and 实时发送 (camera) — same functions as
capture_send.py.
One-time dependency install (no terminal): double-click tools/install_deps.bat.
python -m pip install opencv-python pyserial Pillow numpy- SYN-2594 weight-ROM collapse: TangDynasty's ERAM ROM IP collapses a weight ROM under a
combinational address into a 2-deep tiny BRAM, so weights never load. Fixed by using a
behavioral block RAM (
rtl/int8/bram_rom_w.v,ram_style="block",$readmemhabsolute path), which follows the normal BRAM-inference path and is not collapsed. _p4.hexper-lane width bug: an early interleaver emitted each weight using(P*W_W)//4hex chars instead ofW_W//4, bloating each line P× and causing TD to truncate 75% of the weights to zero (board only recognized digit 0). Fixed bytools/repack_p4.py(re-interleave from the flatl1_w.hex/l2_w.hex; no retraining needed) and caught earlier bytools/verify_p4_hex.py.- Hold false violation (red error): the default
set_clock_uncertainty 0.100applies to both setup and hold; with only ~+14 ps raw hold margin this produced a -86 ps false violation. Changed toset_clock_uncertainty -setup 0.100(matches Anlogic's DDR IP SDC style); hold now reports +14 ps, FEP = 0. - INT8 -> INT4 resource convergence: 48x48 + INT8 needs ~86 × 9K BRAM and overflows the
EG4S20 (64 × 9K,
PHY-9013). Switching weights to INT4 halves L1 ROM to ~32 × 9K (measured#bram9k = 37/64), making the design physically feasible.
- INT4 trades ~1.7 points of accuracy for the BRAM budget (94.87% vs the 96.57% INT8 baseline). This is an expected post-training-quantization cost, not a bug.
- Two weight formats are committed and must stay in sync: flat
l1_w.hex/l2_w.hex(used by the Python tools / golden model) and P-interleavedl1_w_p4.hex/l2_w_p4.hex(used byfc_layer.von the FPGA). Both are generated together bytools/train_export_mnist*.py; never edit one without the other. After changing_p4.hex, re-run synthesis + P&R + bitgen. - EG4S20 has no hard ARM core (it is a pure FPGA, "EAGLE" family). The whole recognition runs in RTL fabric; there is no software processor on the chip.
- This is a learning/demo accelerator, not a production neural-network IP core.
MIT License.