# TridentVision

**Repository Path**: axbx/TridentVision

## Basic Information

- **Project Name**: TridentVision
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-19
- **Last Updated**: 2026-09-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TridentVision

**在成本敏感的 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](#english-version)

---

## 1. 项目简介

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 帧全绿

### 演示效果

![HDMI 屏摄：检测画框 + FPS OSD](docs/images/cap_hdmi_final.png)

| 自定义板 | 识别输出 |
|---|---|
| ![板卡照片 1](docs/images/board_p1.png) | ![板卡照片 2](docs/images/board_p2.png) |

---

## 2. 特性

- **纯 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` 一键再生

---

## 3. 实测性能（全部为板上实测值，出处逐图标注）

### 产线帧率演进

![产线 fps 演进](docs/images/fps_evolution_production.png)

### REARCH 引擎提速六杠杆（验证线 0.831 → 12.897 fps，15.5×）

![六杠杆](docs/images/fps_levers_validation.png)

### 显示税归因与逐项收益（0 收益项如实保留）

![显示税战役](docs/images/opt_attribution.png)

### 帧耗时分解（优化前后）

![帧耗时分解](docs/images/frame_breakdown.png)

### K325T 资源占用（数据源：docs/reports/hdmi_utilization_impl.rpt）

![资源占用](docs/images/resources_k325t.png)

| 资源 | 用量 | 利用率 |
|---|---:|---:|
| Slice LUTs | 113,808 / 203,800 | 55.84% |
| Slice Registers | 98,740 / 407,600 | 24.22% |
| BRAM Tile | 346.5 / 445 | **77.87%** |
| DSP48 | 387 / 840 | 46.07% |
| Slice | 41,596 / 50,950 | **81.64%** |

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

### 验证与回归套件

![回归套件](docs/images/regression_suites.png)

### QAT 训练收敛

![QAT 收敛](docs/images/qat_convergence.png)

### 相机病态案例与 GUARD 防护

![相机病态案例](docs/images/camera_pathology.png)

---

## 4. 硬件清单

| 件 | 型号/规格 | 必需性 |
|---|---|---|
| FPGA 板 | 自定义 Kintex-7 板（xc7k325tffg676-2），原理图/PCB 见 `hardware/gw2ar_pcb/`（GW2AR 评估板）与 `docs/GW2AR_*.md`；或 KC705 + `ip_core/`（见 §7 构建路径） | 必需 |
| 相机 | 海泰 HT-GE34GC-T1-C（GigE Vision，640×480），网线**直连**板上网口（勿经交换机） | 必需 |
| TF 卡 | ≥4GB SDHC，刷 TF 镜像（权重+ROM 表） | 必需 |
| 显示器 | HDMI 640×480@60 | 必需 |
| 采集卡 | 任意 HDMI 采集卡（抓屏取证用） | 可选 |
| JTAG | Xilinx 下载器（开发/烧录用；产线运行不需要） | 开发期 |

---

## 5. 仓库导览

| 目录 | 内容 |
|---|---|
| `rtl/` | 加速器引擎 RTL（现行构建 11 个模块 + legacy 4 个）+ romdma 单元测试台与测试向量 |
| `fpga/stage3_hdmi/` | 主工程：顶层/display/gige/tfload 源码、约束、tmds_ip（rgb2dvi）、固件 src、仿真测试台、Vivado 构建 tcl、板级调试工具 |
| `ip_core/` | 可封装 IP 核形态：`rtl/`（含 dna_license.v）、`sim/`（结构审计 + license 测试台）、`deliverable/`（客户集成指南、KC705 例程、keygen 与厂商操作手册——教学向公开） |
| `training/` | 训练/QAT/导出全链 Python（patches.py 运行时 monkey-patch 实现全部模型改动，不改 ultralytics 本体） |
| `c_model/` | C 参考模型与 bit-exact 验证链（yolo26.c 等）、量化分析脚本、RTL 对拍向量 `tb_vectors/` |
| `assets/` | 部署资产（int8 权重镜像 mem_weights.bin 10MB、rom_blob/rom_rle、输入帧 mem_input.bin） |
| `tools/` | 相机模拟器、ILA/pcap 分析、流实验脚本；`stage3_legacy/`（含 gen_stage3_assets 资产生成器与 run_xsct 基建）；`sim_gvsp/` |
| `hardware/gw2ar_pcb/` | GW2AR-LV18-QN88C8 自定义板 Altium 源文件（4×SchDoc + PcbDoc） |
| `docs/` | 全部设计文档、教程、实测报告、图表（`docs/images/`）与图表生成器（`docs/scripts/`） |
| `specs/` | MACs 核算脚本与输出 |

---

## 6. 快速开始

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

### 6.1 训练 → 导出（PC）

```bat
:: 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](docs/training_export_guide.md)。

### 6.2 生成部署资产与 TF 卡镜像（PC）

```bat
:: 由 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）
```

### 6.3 构建位流（Vivado）

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

### 6.4 烧录与启动

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

### 6.5 license 解锁（dna_license 教学流程）

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

---

## 7. 教程与文档索引

| 文档 | 内容 |
|---|---|
| [docs/deploy_guide.md](docs/deploy_guide.md) | **部署指南**：接线、TF 卡烧录、QSPI 固化、上电时序、验收 |
| [docs/training_export_guide.md](docs/training_export_guide.md) | **训练与导出指南**：依赖、QAT、6 门禁导出验证链 |
| [docs/debug_guide.md](docs/debug_guide.md) | **调试指南**：ILA、UART 日志字段、状态页轮询、GUARD 状态位 |
| [docs/optimization_roadmap.md](docs/optimization_roadmap.md) | **优化路线图与收益估算**（见 §11 摘要） |
| [docs/troubleshooting_index.md](docs/troubleshooting_index.md) | **故障案例集索引**（GigE 调试总结 19 章 + 各文档坑记录） |
| [ip_core/deliverable/customer/doc/TridentVision_IP核客户集成指南.md](ip_core/deliverable/customer/doc/TridentVision_IP核客户集成指南.md) | KC705/IP 核集成指南（脱敏版） |
| [docs/gige_debug_summary.md](docs/gige_debug_summary.md) | GigE Vision 调试总结（19 章，含相机病态案与 GUARD 设计） |
| [docs/REARCH_V1_OPTIMIZATION_SUMMARY.md](docs/REARCH_V1_OPTIMIZATION_SUMMARY.md) | REARCH-v1 优化全程（六杠杆 + 显示税战役数据源） |
| [docs/REARCH_FPS_DISSECTION.md](docs/REARCH_FPS_DISSECTION.md) | 帧率解剖（含固化手册、A200T 降档评估） |
| [docs/YoloV26M_FPGA_V1.0_总结.md](docs/YoloV26M_FPGA_V1.0_总结.md) | V1.0 全程总结（0.2→3.2fps 十六跳、验证方法学、坑与教训） |

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

---

## 8. 已知坑（精选，详录见 docs/ 各文档）

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. **采集类判据先验活再判读**：相机死掉时全同帧会让"三判据全绿"（空绿陷阱）。

---

## 9. IP 保护参考实现（教学向）

本仓库全量公开一套芯片 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`）；本体系防君子不防有资源对手，公开目的是教学参考。

---

## 10. 故障案例精选

相机半锁死案（[docs/gige_debug_summary.md](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/troubleshooting_index.md)。

---

## 11. 优化路线图与收益估算

| 项 | 预计收益 | 工作量 | 依据 |
|---|---|---|---|
| add/ups 通路 burst 化 | **+0.4~0.5 fps** | 2-3 人天 | REARCH 总结 §6#3，已评估未实施 |
| 显示税残量回收（snapshot/stamp 调度） | 残量 ~15ms 中的部分 | 待评估 | §7.7 |
| 引擎 73.6ms 本体（下一瓶颈） | 上限取决方案 | 大 | §7.7：显示税打完后只剩引擎 |
| 杠杆 F：AXI master 多 outstanding | 射程内 ~34.5ms 已被预吃大半，ROI 边际 | 暂缓 | §2.3 裁决记录（64 态直方图分解） |
| 纯逻辑化 v2（去 MicroBlaze） | 省 ~1.25K LUT + 16 BRAM36 | 待拍板 | §6#5 |
| A200T 降档（砍 GigE 栈 + 瘦身） | slice 122.7% → 中值 96.9%，**有条件可部署** | 需实跑 impl 终验 | FPS_DISSECTION 附录 E |

详版：[docs/optimization_roadmap.md](docs/optimization_roadmap.md)。

---

## 12. License 与第三方致谢

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

| 第三方 | 许可 | 使用方式 |
|---|---|---|
| [ultralytics](https://github.com/ultralytics/ultralytics)（yolo26） | AGPL-3.0 | 训练依赖，**未修改其源码**——全部模型改动由 `training/patches.py` 运行时 monkey-patch 实现；请自行按其许可获取 |
| yolo26m.pt 预训练权重 | AGPL-3.0 | 不入 git 树，随 Release 附件分发 |
| stb_image / stb_image_write | Public Domain | `c_model/` 内图片读写 |
| rgb2dvi（Digilent） | 见 `fpga/stage3_hdmi/tmds_ip/` 内版权头 | HDMI TMDS 输出 IP |

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

---

## 13. CITATION

见 [CITATION.cff](CITATION.cff)。引用格式：

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

---
---

# English Version

## TridentVision — YOLOv26m on Kintex-7 FPGA

**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.**

### 1. Overview

- **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.

### 2. Measured Performance (all on-board measurements; sources annotated per figure)

| Metric | Value |
|---|---|
| Production fps (HDMI + boxes + OSD) | **9.679 fps** (baseline 7.756 → +24.8%, display-tax campaign) |
| Validation-line fps (no display) | **12.897 fps** (0.831 → 15.5× via six levers) |
| Engine time | 73.6 ms/frame (5.524M cyc @75MHz) |
| K325T utilization | LUT 55.84% / FF 24.22% / BRAM 77.87% / DSP 46.07% / Slice 81.64% |
| Timing (rrC) | WNS +0.088 / WHS +0.051 / 0 failing endpoints |
| Boot chain | QSPI self-config ~2.6s → TF loader (v3 image 11.4MB) → detection |

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`).

### 3. Repository Layout

`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.

### 4. Quick Start

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

### 5. Documentation

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

### 6. Known Pitfalls (selection)

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

### 7. Optimization Roadmap (ROI-estimated, from measured accounts)

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`.

### 8. License & Third Parties

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.