在成本敏感的 Xilinx Kintex-7 FPGA 上运行的端到端 YOLOv26m 目标检测系统：GigE 工业相机进，HDMI 实时画框出，全程无 PC 参与。

End-to-end YOLOv26m object detection on a cost-sensitive Xilinx Kintex-7 FPGA: GigE industrial camera in, HDMI bounding boxes out — no PC involved.

English README 见文末 / English version at the bottom

TridentVision 把 YOLOv26m 检测网络完整部署到一块 Kintex-7 K325T 自定义板上：

海泰 HT-GE34GC 相机（GigE Vision，640×480）
   │ GVSP UDP → FPGA gige/（GVCP 控制器：Discovery/配流/心跳/自愈）
   ▼
GVSP 解包 → DDR3 三 bank 帧缓冲（MIG x32）
   ▼
MicroBlaze 固件（fpga/stage3_hdmi/fw/src/main.c）
   ├─ crop PL（96×96 检测输入窗）
   ├─ 推理引擎（rtl/：85 job 静态程序表，AXI4 主控 + MAC 阵列 + ROM DMA 直灌）
   ├─ snap_pp PL：CLS 直灌 + BOX 位精确整数乘
   ├─ finish：topK/NMS/decode（可切块增量堆排序，藏进引擎等待环）
   └─ stamp_dets：白框 + FPS OSD 叠加
   ▼
frame_reader → TMDS（rgb2dvi）→ HDMI 640×480@60

• 模型：yolo26m 的 FPGA 友好重构版（REARCH-v1）——92 层 / 85 job，全部层落入引擎六种原生算子闭集（3×3/1×1 conv、conv s2、ADD、FC、maxpool5）；403.3M MACs（较官方 26m -65%），int8 权重 10.19MB（-67%），mAP@0.5 = 0.2066（96² 口径，教师 0.2229）
• 训练：int8 QAT 从第一天介入（禁后训练量化），COCO 118,287 图 / 100 epochs / ~11.5h
• 部署：QSPI flash 固化位流+固件，TF 卡存权重与 ROM 表，上电自启，断电解缆产线形态
• 验证：每一级提速后硅上 82/82 点 bit-exact；C 参考模型与 RTL 逐位一致；四帧闸门 134 点 ×4 帧全绿

自定义板	识别输出

• 纯 FPGA 推理：无 GPU、无电脑、无外挂 CPU 板；MicroBlaze 仅做调度与画框
• 上电自启：QSPI flash 自配置 ~2.6s → TF loader 读卡（v3 镜像 11.4MB，超级块+区段表+CRC32）→ 检测流水线
• 链路自愈：GVSP 看门狗（流静默 3s 检出，复电 ~10.3s 零干预自愈）；GUARD 固件病态防护（相机楔死时冻结画框防误导，见 §10 故障案例）
• 位精确可信：FPGA 定点推理与 C 参考模型逐位一致，全部验证套件 100% 通过（见 §3）
• IP 保护参考实现：芯片 DNA 绑定 license（dna_license.v + keygen），教学向全量公开（见 §9）
• 可复现：全部构建脚本、测试台、资产生成器、实测报告入库；图表由 docs/scripts/gen_charts.py 一键再生

时序：rrC 基线 WNS +0.088 / WHS +0.051 / 0 失败端点（impl 实测，见 docs/reports/hdmi_timing_impl.rpt）。

环境：Vivado 2024.1（含 Vitis/xsct）、Python 3（训练需 CUDA + PyTorch + ultralytics，见 training/README.md）、Icarus Verilog（仿真，可选）。

:: 1) FPGA 友好重构模型训练 / QAT int8（~11.5h，可 ckpt 续跑）
cd training && python qat.py
:: 2) 导出 int8 权重镜像 + 6 门禁验证（C vs numpy bit-exact、MACs 对账、ISA 检查…）
cd export && python rearch_export.py
:: 产物：rearch_int8.bin（10.19MB，已入库一份在 training/export/）

详见 docs/training_export_guide.md。

:: 由 export 产物生成 assets/（mem_weights.bin / rom_blob.bin / rom_rle.bin / mem_input.bin）
python tools/stage3_legacy/gen_stage3_assets_rearch.py
:: 生成 TF 卡镜像并用 Win32DiskImager 刷入（详版：docs/deploy_guide.md 与 docs/tf_card_flash.md）

cd fpga/stage3_hdmi
"C:\Xilinx\Vivado\2024.1\bin\vivado.bat" -mode tcl -source build_stage3_hdmi.tcl
:: 工程从零重建（BD + MIG + 引擎 RTL 引用 rtl/），耗时约 78min

• 开发期（JTAG）：tools/ 下 run_xsct.py + 烧板脚本；每次换 bit 必走全量重灌流程（见 §8 已知坑 #1）
• 产线（QSPI 固化）：write_cfgmem 生成 mcs → program_flash → 上电自配置 ~2.6s
• 上电时序锚点（V1.0 固化版实测，REARCH 版链路相同）：0–26s 黑屏自举（正常）→ ~26s 相机画面上屏 → ~33s 识别画框叠加

上电后读 FP0/FP1/FP2 得 96bit 指纹 → ip_core/deliverable/vendor/keygen/keygen.bat <指纹hex> → 写 KEY0/KEY1/KEY2。详版见 §9 与 ip_core/deliverable/customer/doc/TridentVision_IP核客户集成指南.md。

KC705 构建路径（D5 说明）：ip_core/deliverable/customer/example_kc705/ 的构建脚本以 DCP 例化 IP 核。本仓库不带 dcp——两条路：① 从 Release 页下载 tv3_ip_core.dcp；② 用 ip_core/rtl/ 源码在 Vivado 中自行 package_ip 生成。

1. "换 bit 必踢相机"：烧板瞬态 MIG 刷新中断 → DDR 权重/ROM 区 14~16% bit 翻转，且相机错过 GVCP 发现窗会楔死。每次 JTAG 换 bit 后必须全量重灌资产并重启/踢相机（烧板 SOP 见 docs/deploy_guide.md §5）。
2. JTAG 轮询污染：高频采样挤占 AXI 把帧 417→495ms——观测者效应真实存在，墙钟测量只能稀疏采样。
3. Windows 路径上限：Vivado 工程深路径 + 长中文目录名易触 MAX_PATH——工程放短路径根目录。
4. XDC 大小写敏感：get_ports 名与 HDL 大小写不一致时静默不生效，时序约束形同虚设——elab 后必查约束覆盖率。
5. DCI 级联：多 bank DCI 级联链配置错误会导致 IO 标准隐式降级——布板与约束需交叉核对。
6. 写后读回要在另一个地址空间做（MMU 冤案教训）：LMB 自洽的"读回校验通过"全是假象。
7. 采集类判据先验活再判读：相机死掉时全同帧会让"三判据全绿"（空绿陷阱）。

本仓库全量公开一套芯片 DNA 绑定 license 体系，作为 FPGA IP 保护的教学样本：

芯片 DNA(57bit, 不可读改写)
   │  硬件上电自动（约 1µs）:
   ▼
指纹 FP = PRF₂₄(DNA ⊕ SALT1)        ← 96bit，锁定态也可读
   ├─ 正式 key  = PRF₂₄(FP ⊕ SALT2 ⊕ 0xF1)
   └─ 试用 key  = PRF₂₄(FP ⊕ SALT2 ⊕ 0x7E)  （4000 帧配额，帧完成自动 -1，支持持久化）

• RTL：ip_core/rtl/dna_license.v（PRF ARX 24 轮 + 种子构造 + 比对门控）
• 钥匙机：ip_core/deliverable/vendor/keygen/（prf_ref.py 与 RTL 逐位一致，仿真对拍验证）
• 流程文档：ip_core/deliverable/vendor/厂商操作手册.md、客户侧 TridentVision_IP核客户集成指南.md
• 说明：文档与示例中的指纹/key 值均已替换为占位符（如 0123456789ABCDEF01234567）；本体系防君子不防有资源对手，公开目的是教学参考。

相机半锁死案（docs/gige_debug_summary.md 第十九章）：消费端消失 → 相机流引擎楔死为 1.3fps 涓流（PC 直连 98fps 满血，排除相机硬件）。固件侧落地 GUARD 病态防护：停驻率 EMA（>2048 进入 / <1024 解除回差）→ 病态期冻结画框（SCRATCH[32/35/36] 可观测），实测病态期 shown=0、输入框消退、识别维持 10.2fps 不雪崩。完整案例索引见 docs/troubleshooting_index.md。

详版：docs/optimization_roadmap.md。

本项目整体以 AGPL-3.0 发布（见 LICENSE），包括全部自研 RTL、固件、C 模型与训练脚本。

Release 附件（不入 git 树）：yolo26m.pt（44MB）、tv3_ip_core.dcp（14MB，KC705 集成用）。

见 CITATION.cff。引用格式：

TridentVision: End-to-end YOLOv26m object detection on Kintex-7 FPGA (2026). AGPL-3.0.

An end-to-end object detection pipeline on a cost-sensitive Xilinx Kintex-7 (xc7k325t) board: GigE Vision camera in, HDMI with real-time bounding boxes out — fully standalone, no PC.

• Model: FPGA-friendly re-architecture of yolo26m (REARCH-v1) — 92 layers / 85 jobs, all ops inside the engine's six-op ISA (3×3/1×1 conv, conv-s2, ADD, FC, maxpool5). 403.3M MACs (-65% vs official 26m), 10.19MB int8 weights (-67%), mAP@0.5 = 0.2066 @96² (teacher 0.2229).
• Training: int8 QAT from day one (no post-training quantization), COCO 118k images, 100 epochs, ~11.5h.
• Deployment: bitstream+firmware in QSPI flash, weights on TF card, power-on self-start (~2.6s self-configuration), offline production-line form factor.
• Verification: silicon bit-exact 82/82 after every speedup lever; C reference model bit-identical to RTL; 4-frame gate 134 points ×4 frames all green.

All charts live in docs/images/ and regenerate via python docs/scripts/gen_charts.py (measured data hard-coded with per-value source annotations; QAT curve from docs/scripts/qat_epoch_log.csv).

rtl/ accelerator engine RTL · fpga/stage3_hdmi/ main project (top/display/gige/tfload RTL, constraints, firmware, sim testbenches, Vivado tcl, board-debug tools) · ip_core/ packageable IP core (incl. dna_license.v, KC705 example, keygen) · training/ training/QAT/export chain · c_model/ bit-exact C reference + tb vectors · assets/ deployment binaries · tools/ misc + asset generators · hardware/gw2ar_pcb/ custom board Altium sources · docs/ all design docs, tutorials, reports, charts · specs/ MACs accounting.

Prerequisites: Vivado 2024.1 (with Vitis/xsct), Python 3 (PyTorch + CUDA + ultralytics for training), Icarus Verilog (optional, for simulation).

1. Train & export: cd training && python qat.py → cd export && python rearch_export.py (6-gate verification: C-vs-numpy bit-exact, per-layer MACs, ISA check…).
2. Assets & TF image: python tools/stage3_legacy/gen_stage3_assets_rearch.py, then flash the TF image (details: docs/deploy_guide.md, docs/tf_card_flash.md).
3. Build bitstream: vivado -mode tcl -source fpga/stage3_hdmi/build_stage3_hdmi.tcl (~78 min full build).
4. Burn & boot: JTAG for development (full asset re-flash after every bit change — see known pitfall #1); write_cfgmem → QSPI mcs for production. Power-on timeline anchor (V1.0 fixed image): ~26s camera picture, ~33s detection boxes.
5. License (educational): read FP0/1/2 → keygen.bat <fp-hex> → write KEY0/1/2 (see ip_core/deliverable/ docs).

Deploy guide · training/export guide · debug guide (ILA, UART fields, status-page polling, GUARD bits) · optimization roadmap with ROI estimates · troubleshooting case index (19-chapter GigE debug summary) — all under docs/, bilingual (Chinese primary, English summaries).

1. "Every bit change must kick the camera": configuration transients corrupt 14–16% of DDR weight/ROM bits and the camera misses the GVCP discovery window → full asset re-flash + camera power-cycle required.
2. JTAG polling pollutes AXI (observer effect: frame 417→495ms under dense sampling) — sample sparsely.
3. Windows MAX_PATH with deep Vivado paths; XDC case-sensitivity silently voids constraints; DCI cascade misconfig silently degrades IO standards.
4. Verify write-backs in a different address space (the "MMU wrongful-conviction" lesson).

add/ups burst-ification +0.4~0.5 fps (2–3 person-days) · display-tax residue ~15ms · engine 73.6ms becomes the next wall · multi-outstanding AXI master deferred (marginal ROI after histogram decomposition) · pure-logic v2 (−1.25K LUT, −16 BRAM36) · A200T cost-down path evaluated (96.9% slice median, conditional). Details: docs/optimization_roadmap.md.

Overall AGPL-3.0 (see LICENSE), covering all original RTL, firmware, C model and training code. Third parties: ultralytics (AGPL-3.0, used unmodified via runtime monkey-patching in training/patches.py), yolo26m.pt weights (AGPL-3.0, Release asset), stb_image (public domain), rgb2dvi (Digilent, see license header in fpga/stage3_hdmi/tmds_ip/). Release assets (not in git): yolo26m.pt (44MB), tv3_ip_core.dcp (14MB).

The DNA-bound license protection (ip_core/rtl/dna_license.v + keygen) is published for educational purposes; all fingerprint/key values in docs are placeholders.