Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

EG4S20 INT4 Digit Recognition Accelerator

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.

Current Status

  • 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.py reports max_logits_err = 0 and pred 不一致 = 0 with the committed weights.
  • Board bring-up verified: tools/verify_board_uart.py ran 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.
  • $readmemh block-RAM init confirmed on hardware: the weight ROM uses a behavioral block RAM (rtl/int8/bram_rom_w.v) to avoid the TangDynasty SYN-2594 combinatorial-address weight-ROM collapse. The board returns correct digits, so BRAM init loads as expected.
  • Input quantization constant SX0 = 0.022216 is written to mem/quant_params.txt (required when sending real MNIST images from the PC; see Board Test).

Repository Map

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),当前主链路用

Quick Verification

Run all software + RTL checks:

cd D:\path\to\repo
.\scripts\run_verification.ps1

If Icarus Verilog is not installed:

.\scripts\run_verification.ps1 -SkipVerilog

Expected result:

RTL static safety check: PASS
RTL/golden consistency: PASS
All enabled verification gates passed.

Board bring-up verification (real hardware)

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 COM8

Expected: 板级对拍: 200/200 通过 (every回显 matches the golden model).

Build with TangDynasty

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:

  1. Create a new EG4S20BG256 project.
  2. Add all Verilog files under rtl/ and rtl/int8/.
  3. Set top module to mnist_uart_board_top.
  4. Add constraints/hx4s20_digit_demo.adc.
  5. Add constraints/hx4s20_digit_demo.sdc.
  6. mem/ is referenced by an absolute path in bram_rom_w.v ($readmemh); make sure the path in mnist_config.MEM_DIR / the ROM points at dsp_projects/mem. After editing _p4.hex, re-run synthesis + P&R + bitgen (weights are embedded at synthesis time).
  7. 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

Board Test

Install the Python serial dependency once:

python -m pip install pyserial

Send one demo image (48x48 frame, 2304 bytes):

python tools\send_digit_uart.py --port COM8 --digit 3

Replace 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

PC photo capture (preprocessing + send)

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:

  1. Grayscale;
  2. Otsu threshold to auto-detect polarity (black-on-white is inverted to MNIST-style white-on-black);
  3. Crop the digit bounding box, center it by centroid, scale to 48x48;
  4. Normalize (pixel/255 - 0.1307)/0.3081 + INT8 quantize x_q = clip(round(x/SX0), -128, 127);
  5. 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 UART

Note: 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).

Double-click GUI (no terminal)

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

Key Engineering Fixes (already applied)

  • 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", $readmemh absolute path), which follows the normal BRAM-inference path and is not collapsed.
  • _p4.hex per-lane width bug: an early interleaver emitted each weight using (P*W_W)//4 hex chars instead of W_W//4, bloating each line P× and causing TD to truncate 75% of the weights to zero (board only recognized digit 0). Fixed by tools/repack_p4.py (re-interleave from the flat l1_w.hex/l2_w.hex; no retraining needed) and caught earlier by tools/verify_p4_hex.py.
  • Hold false violation (red error): the default set_clock_uncertainty 0.100 applies to both setup and hold; with only ~+14 ps raw hold margin this produced a -86 ps false violation. Changed to set_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.

Known Limitations

  • 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-interleaved l1_w_p4.hex/l2_w_p4.hex (used by fc_layer.v on the FPGA). Both are generated together by tools/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.

License

MIT License.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages