- Windows PowerShell
- Python 3.8及以上版本
- PyTorch、torchvision、NumPy（见
software/requirements.txt） - Icarus Verilog（提供
iverilog和vvp） - Vivado 2018.1或兼容版本
所有命令默认从仓库根目录执行。
bnn_accelerator/
├── README.md
├── LICENSE
├── .gitignore
├── docs/
│ └── BNN_FPGA_ACCELERATOR.md # 项目介绍文章
├── params/
│ ├── w1.mem / w2.mem / w3.mem # 三层二值权重
│ ├── th1.mem / th2.mem # BN折叠阈值
│ ├── test_images.mem # 1,000张RTL测试图像
│ ├── test_labels.mem # 1,000个标签
│ └── golden_preds.mem # Golden Reference预测
├── rtl_v2_ppa/ # PE复用源RTL
├── rtlv2_ppa_syth/ # 固定权重的可综合PE RTL
├── sim2/
│ ├── bnn_tb_reuse.v
│ └── run_sim.ps1 # 一键Icarus仿真
├── software/
│ ├── train_bnn.py
│ ├── export_params.py
│ ├── golden_reference.py
│ ├── gen_v2_ppa_synth_rtl.py
│ ├── bnn_model.pth
│ └── requirements.txt
└── vivado/
└── run_ooc.tcl # 一键综合、布局和路由
仓库已经包含模型参数和1,000张测试数据，不需要重新训练即可验证RTL。
确认Icarus Verilog可用：
iverilog -V
vvp -V从仓库根目录运行：
powershell -ExecutionPolicy Bypass -File .\sim2\run_sim.ps1 -Images 1000短测试可以改为：
powershell -ExecutionPolicy Bypass -File .\sim2\run_sim.ps1 -Images 10完整回归应看到：
Accuracy : 947 / 1000 = 94.70%
Golden agreement: 1000 / 1000
PASS: RTL matches the Phase 1 golden reference on every image.
仿真会在 sim2/ 下生成 bnn_pe_sim.vvp 和 bnn_tb_reuse.vcd，它们已加入 .gitignore。
cd software
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt如果PowerShell禁止激活虚拟环境，可先执行：
Set-ExecutionPolicy -Scope Process Bypasspython train_bnn.py `
--epochs 50 `
--batch-size 128 `
--lr 3e-3 `
--lr-schedule cosine `
--data-dir ./data `
--out bnn_model.pth脚本会自动下载MNIST，并把测试准确率最高的一轮保存为 software/bnn_model.pth。
仍在 software/ 目录中执行：
python export_params.py `
--model bnn_model.pth `
--data-dir ./data `
--out-dir ../params `
--num-images 1000成功标志：
All .mem files written and verified.
该步骤会覆盖 params/ 中的权重、阈值、测试图像和标签。
python golden_reference.py `
--model bnn_model.pth `
--data-dir ./data `
--params-dir ../params `
--dump-preds ../params/golden_preds.mem必须确认完整测试集逐张一致：
per-image agreement float vs integer: 10000/10000
python gen_v2_ppa_synth_rtl.py
cd ..生成文件位于 rtlv2_ppa_syth/。每次重新训练和导出参数后，都必须重新运行该脚本，否则Vivado综合的仍是旧权重。
powershell -ExecutionPolicy Bypass -File .\sim2\run_sim.ps1 -Images 1000重新训练后，Accuracy 可能变化，但 Golden agreement 必须为 1000 / 1000。
确保当前终端能够执行 vivado，然后从仓库根目录运行：
vivado -mode batch -source .\vivado\run_ooc.tcl如果普通PowerShell找不到 vivado，请打开安装目录中的 Vivado 2018.1 Tcl Shell/Command Prompt，切换到仓库根目录后执行同一命令。
脚本会自动完成：
读取最终PE RTL和XDC
→ OOC综合
→ 逻辑优化
→ 布局
→ 物理优化
→ 路由
→ 生成DCP和报告
输出位于：
build/vivado/post_synth.dcp
build/vivado/post_route.dcp
build/vivado/utilization_post_route.rpt
build/vivado/timing_summary_post_route.rpt
build/vivado/route_status.rpt
build/vivado/drc_post_route.rpt
完成后重点检查：
route_status.rpt中nets with routing errors是否为0；timing_summary_post_route.rpt中WNS是否大于等于0；utilization_post_route.rpt中LUT、FF、BRAM和DSP使用量。
当前设计可以完成路由，但100 MHz约束下WNS仍为负值，因此“脚本运行完成”不代表时序已经通过。
如果不使用Tcl脚本，按下面配置新建RTL Project：
Part : xc7a200tfbv484-2
Design Top : bnn_top_v2_synth
Constraint : rtl_v2_ppa/bnn_top.xdc
Synthesis More Options : -mode out_of_context
只添加以下Design Sources：
rtl_v2_ppa/xnor_popcount.v
rtl_v2_ppa/threshold_compare.v
rtl_v2_ppa/argmax.v
rtlv2_ppa_syth/bnn_layer1_v2_synth.v
rtlv2_ppa_syth/bnn_layer2_v2_synth.v
rtlv2_ppa_syth/bnn_output_v2_synth.v
rtlv2_ppa_syth/bnn_top_v2_synth.v
随后添加 rtl_v2_ppa/bnn_top.xdc，依次运行 Run Synthesis 和 Run Implementation。
当前顶层直接暴露784-bit图像端口，因此只适合OOC核心PPA分析。若需要生成bitstream并上板，必须先改为串行、AXI Stream或存储器接口，并补充真实时钟和引脚约束。
训练完成并生成 bnn_model.pth
→ export_params.py 回读验证通过
→ Golden Reference达到10000/10000
→ gen_v2_ppa_synth_rtl.py重新生成硬编码RTL
→ RTL仿真达到1000/1000 Golden agreement
→ Vivado综合、布局和路由完成
→ 检查资源报告、路由状态和WNS