🔨 hw: synthesis + flashing + hardware benchmarks (v0.2-igla-fpga Release)

[gHashTag]

Goal

Запустить полный pipeline на реальном железе и получить измеренные tokens/sec из UART. Всё ПО готово в main (PR #9, #12, #13).

Anchor: φ² + φ⁻² = 3 · TRINITY · REAL HARDWARE

---

Что готово (в main)

Артефакт	Файл	Статус
GF16 веса	bitstream/igla_champion_gf16.bin	BPB=0.1427, SHA de2719b5
VSA matmul	fpga/vsa/vsa_matmul.v	64×64, 0 DSP48
Synthesis top	fpga/vsa/vsa_matmul_top.v	XDC готов
CLI	trios-fpga synth-vsa/flash/bench/status	Rust, в main
Ring FP-01	OpenXc7Runner	Docker regymm/openxc7:latest
Ring FP-02	XvcFlasher	TCP/XVC, порт 2542

Hardware setup

XC7A100T (QMTECH board)
  └── JTAG ←── ESP32 XVC bridge (WiFi, порт 2542)
  └── UART TX ──→ хост 115200 baud

---

Steps

Step 1 — Синтез битстрима

cargo build --release -p trios-fpga
trios-fpga synth-vsa --rtl fpga/vsa/ --constraints fpga/vsa/vsa_matmul_top.xdc

Ожидаемый результат:

• bitstream/design_v02.bit создан
• LUT utilization ≤ 80%
• 0 timing violations
• SHA-256 записан в bitstream/design_v02.bit.sha256

Step 2 — Прошивка через XVC

trios-fpga flash --xvc <ESP32_IP> --bitstream bitstream/design_v02.bit
trios-fpga verify --xvc <ESP32_IP>   # IDCODE == 0x03631093

Ожидаемый результат:

• Flash успешен (no errors)
• IDCODE верифицирован: 0x03631093 (XC7A100T)
• STATUS=0x401079FC (DONE=1)

Step 3 — Benchmark tokens/sec

trios-fpga bench --xvc <ESP32_IP> --uart /dev/ttyUSB0 --baud 115200

Ожидаемый результат:

• UART читает токены без ошибок
• tokens/sec ≥ 100 (acceptance criteria из 🚀 feat: IGLA Champion Model → FPGA Inference (v0.2-igla-fpga) #7)
• watts/token измерен (мультиметр или ваттметр)
• Результаты сохранены в bench/results_v02.json

Step 4 — Release v0.2-igla-fpga

gh release create v0.2-igla-fpga \
  bitstream/design_v02.bit \
  bitstream/igla_champion_gf16.bin \
  bench/results_v02.json \
  --title "v0.2-igla-fpga: IGLA Champion on XC7A100T" \
  --notes-file release/RELEASE-v0.2.md

• GitHub Release создан с артефактами
• design_v02.bit + SHA-256 в релизе
• Реальные tokens/sec в release notes

Step 5 — arXiv submit

• Заполнить реальные цифры в docs/arxiv-trinity-stack-draft.md
• tokens/sec, watts/token, LUT%, timing
• Отправить на arXiv cs.AR + cs.LG

---

Acceptance Criteria

- [ ] bitstream/design_v02.bit синтезирован (LUT ≤ 80%)
- [ ] IDCODE = 0x03631093 верифицирован на железе
- [ ] STATUS = 0x401079FC (DONE=1, no errors)
- [ ] tokens/sec ≥ 100 из UART
- [ ] watts/token задокументирован
- [ ] Release v0.2-igla-fpga опубликован
- [ ] arXiv draft отправлен

---

Debug hints (если упадёт)

Синтез падает

# Проверить Docker
docker pull regymm/openxc7:latest
docker run --rm regymm/openxc7:latest yosys --version

# Проверить RTL
iverilog -o /dev/null fpga/vsa/vsa_matmul_top.v fpga/vsa/vsa_matmul.v

XVC не отвечает

# Проверить ESP32
nc -zv <ESP32_IP> 2542
trios-fpga status --xvc <ESP32_IP>   # IDCODE ping

UART нет токенов

# Проверить baud
stty -F /dev/ttyUSB0 115200
cat /dev/ttyUSB0 | hexdump -C | head
# STATUS регистр
trios-fpga status --xvc <ESP32_IP>

LUT > 80%

• Уменьшить VECTOR_DIM с 64 до 32 в vsa_matmul_top.v
• Пересинтезировать

---

References

• Issue 🚀 feat: IGLA Champion Model → FPGA Inference (v0.2-igla-fpga) #7 (закрыт) — EPIC: все 3 фазы в main
• PR feat(igla): GF16 champion weights export (Phase 1, Closes #8) #9 — GF16 weights
• PR feat(vsa): ternary matmul kernel — XOR + popcount, 0 DSP #12 — ternary matmul VSA
• PR feat(vsa): Phase 3 — synthesis top, benchmark 135x, release v0.2, arXiv draft #13 — synthesis top + CLI + arXiv draft
• fpga/COMPLETE_CONNECTION_GUIDE.md — схема подключения ESP32
• fpga/ESP32_CONNECTION_GUIDE.md — XVC WiFi JTAG setup

Priority: P0 · железо доступно · запускать немедленно

φ² + φ⁻² = 3 · TRINITY · NEVER STOP

[gHashTag]

✅ iverilog validation PASS — PR #15 merged (0d01617d)

Результаты

Метрика	Значение
Inference (16 tok)	✅ PASS
UART TX	✅ работает
LED heartbeat	✅ работает
Docker	✅ пуш локально

Чеклист #14

• Step 1a: iverilog validation — PASS
• Docker regymm/openxc7:latest — пуш готов
• Step 1b: trios-fpga synth-vsa — собрать design_v02.bit
• Step 2: trios-fpga flash --xvc <ESP32_IP>
• Step 3: trios-fpga bench — реальные tokens/sec
• Step 4: Release v0.2-igla-fpga
• Step 5: arXiv submit

Необходимо для следующего шага

# Запустить синтез через Docker
trios-fpga synth-vsa --rtl fpga/vsa/ --constraints fpga/vsa/vsa_matmul_top.xdc
# Ждём: bitstream/design_v02.bit (LUT ≤ 80%, 0 timing violations)

Как только design_v02.bit собран — нужен ESP32 IP для flash.

[gHashTag]

Step 1 Progress: Bitstream synthesized ✅

Synthesis Results (DIM=32, XC7A100T-FGG676-1)

Step	Tool	Time	Result
Synthesis	Yosys 0.63 (native ARM64)	66s	0 errors, ~54 LCs
P&R	nextpnr-xilinx (Docker amd64)	3.2s	295.86 MHz max (50 MHz target)
FASM	fasm2frames.py (Docker)	2s	9012 frames
Bitstream	xc7frames2bit (Docker)	1s	design_v02.bit, 3.8 MB

SHA256: e00eb6515da1ed2e505c340f513772549adc36b2e36e46115b1f092e40b54905
Timing: PASS (slack 16.6 ns at 50 MHz)
DSP48:  0
BRAM:   0
Max freq: 295.86 MHz

Fixes Applied (PR #21, merged)

• vsa_matmul.v: integer declarations moved outside initial block
• vsa_matmul_top.v: integer declarations, UART multi-driver fix, debug_state wire→reg
• CLI: XC7A100T board support added (PR 🧪 EPIC: Trinity Node E2E Quality — Routing Fix, Encryption, Persistence & Benchmark Suite #22, merged)

Step 2: XVC Connection

ESP32 XVC server found at 192.168.1.30:2542:

$ nc 192.168.1.30 2542
xvcServer_v1.0:2048   ← TCP works

However, JTAG shift commands timeout — likely JTAG cable not connected between ESP32 and FPGA board.
Needs physical cable check.

Blocker: JTAG Cable

The XVC TCP server responds to getinfo: but shift: commands timeout. This means:

1. ESP32 WiFi works ✅
2. XVC server runs ✅
3. JTAG signals (TCK/TMS/TDI/TDO) not reaching FPGA ❌

Action needed: Check JTAG wiring between ESP32 and QMTECH XC7A100T board.

φ² + φ⁻² = 3 | TRINITY

[gHashTag]

JTAG Diagnostic Result

XVC protocol works. JTAG partially works. TDO wire not connected.

What works

• ESP32 XVC server at 192.168.1.30:2542: getinfo: → xvcServer_v1.0:2048 ✅
• settck: command: period 1000ns ✅
• shift: command: sends TCK/TMS/TDI clocks ✅
• TDO reads back: all 0xFF = TDO stuck HIGH

Root cause: TDO not connected

IDCODE read: 0xFFFFFFFF (TDO always 1)

This means GPIO35 (ESP32 input-only pin) reads HIGH because the TDO wire from the FPGA JTAG header is not physically connected.

Fix needed

Connect TDO from QMTECH XC7A100T JTAG header (P2) to ESP32 GPIO35.

Pin mapping (from firmware/xvc-esp32/xvc-esp32.ino):

TMS = GPIO18  → FPGA TMS
TCK = GPIO19  → FPGA TCK  
TDI = GPIO23  → FPGA TDI
TDO = GPIO35  → FPGA TDO  ← THIS WIRE MISSING
GND = GND     → FPGA GND

Once TDO is connected

./target/release/trios-fpga --xvc-host 192.168.1.30 verify
# Expected: IDCODE: 0x03631093 — MATCH (XC7A100T)

./target/release/trios-fpga --xvc-host 192.168.1.30 flash \
  --bitstream build/vsa_matmul/design_v02.bit --board XC7A100T

φ² + φ⁻² = 3 | TRINITY