Skip to content

Commit b6bea8e

Browse files
committed
feat(fpga): add uart/power/synth-validate CLI commands + fpga_tools MCP module
Unblocks Issue #128 BLOCKER #2 (power measurement with CH340 cables) and BLOCKER #1 (synthesis validation via Docker openXC7). Changes: - src/tri/tri_fpga.zig: +runFpgaUartCommand, +runFpgaPowerCommand, +runFpgaSynthValidateCommand - src/tri/tri_register.zig: +3 dispatch cases for uart/power/synth-validate - tools/mcp/trinity_mcp/fpga_tools.zig: NEW - 6 MCP wrapper functions - tools/mcp/trinity_mcp/server.zig: +6 tool defs + routing Pin reference: uart_tx=K20, uart_rx=L20, GND required Baud: 115200 (CLK_DIV=27 @ 50MHz)
1 parent 6c04b9c commit b6bea8e

3 files changed

Lines changed: 1015 additions & 0 deletions

File tree

docs/fpga-uart-power-workflow.md

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# Trinity FPGA: UART Bridge + Power Measurement Workflow
2+
3+
> **Unblocks Issue #128 BLOCKER #2** — CH340 USB-UART cables arrived
4+
5+
## Hardware Setup
6+
7+
### Wiring (CH340 to QMTech XC7A100T)
8+
9+
| FPGA Pin | Signal | CH340 Wire | Notes |
10+
|----------|--------|-----------|-------|
11+
| K20 | uart_tx | RX (green) | FPGA → Host |
12+
| L20 | uart_rx | TX (white) | Host → FPGA |
13+
| GND | GND | GND (black) | **Must connect** |
14+
| U22 | clk || 50 MHz onboard |
15+
16+
### Mode Selection (DIP Switches)
17+
18+
| Mode | sw[1] sw[0] | Description | Expected W |
19+
|------|------------|-------------|------------|
20+
| 0 | 0 0 | IDLE (all gated) | ~0.45W |
21+
| 1 | 0 1 | BLINK (LED only) | ~0.50W |
22+
| 2 | 1 0 | 1-BLOCK | ~0.60W |
23+
| 3 | 1 1 | 4-BLOCK (full pipeline) | ~0.75W |
24+
| 4 | btn | AUTO-CYCLE (1s each) | varies |
25+
26+
Pin assignments: sw[0]=K21, sw[1]=J21, btn=P23
27+
28+
## Workflow
29+
30+
### Step 1: Discover Device
31+
32+
```bash
33+
tri fpga uart scan
34+
# → /dev/tty.wchusbserial10 [CH340]
35+
```
36+
37+
### Step 2: Flash Firmware
38+
39+
```bash
40+
tri fpga power flash
41+
# Synthesizes power_modes.v via Docker openXC7
42+
# Programs FPGA via JTAG (openFPGALoader)
43+
```
44+
45+
### Step 3: Verify UART Link
46+
47+
```bash
48+
tri fpga uart ping /dev/tty.wchusbserial10
49+
# → ✅ PONG OK (0x83)
50+
```
51+
52+
### Step 4: Measure Power
53+
54+
```bash
55+
tri fpga power measure /dev/tty.wchusbserial10
56+
# Cycles modes 0-4, reads watt values from UART
57+
# Saves to /tmp/trinity_power_results.json
58+
```
59+
60+
### Step 5: Generate Report
61+
62+
```bash
63+
tri fpga power report
64+
# Writes papers/trinity-fpga/power_results.md
65+
```
66+
67+
### Step 6: Synthesis Validation (BLOCKER #1)
68+
69+
```bash
70+
# Requires Docker + hdlc/ghdl:yosys
71+
tri fpga synth-validate
72+
# Runs all 10 targets from Makefile.validate
73+
# Writes fpga/openxc7-synth/benchmarks/synthesis_results.md
74+
75+
# Or single module:
76+
tri fpga synth-validate matvec_243x729
77+
```
78+
79+
## MCP Tools (Claude Code)
80+
81+
After `tri serve --mcp`, these tools are available in Claude Code:
82+
83+
| Tool | Description |
84+
|------|-------------|
85+
| `fpga_uart_scan` | Discover CH340/FTDI devices |
86+
| `fpga_uart_ping` | Verify UART link to FPGA |
87+
| `fpga_power_flash` | Flash power_modes.v bitstream |
88+
| `fpga_power_measure` | Collect 5-mode power data |
89+
| `fpga_power_report` | Generate markdown table |
90+
| `fpga_synth_validate` | Run Yosys via Docker |
91+
92+
## Protocol Reference
93+
94+
### UART Commands (115200 8-N-1)
95+
96+
| Byte | Command | Response |
97+
|------|---------|----------|
98+
| 0x03 | PING | 0x83 PONG |
99+
| 0x00-0x04 | Set mode N ||
100+
| 0x0E | Query power | `W:X.XX\n` |
101+
| 0x0F | Query mode | mode byte |
102+
| 0xAA 0x10 lo hi | Infer token | 4-byte u32 |
103+
104+
Baud divisor: CLK_DIV = 27 @ 50 MHz → 115200 baud
105+
106+
## Expected Results for Paper
107+
108+
After running `measure + report`, update **Table 3** in `papers/trinity-fpga/draft.md`:
109+
110+
```
111+
IDLE: ~0.45W
112+
BLINK: ~0.50W (+0.05W LED)
113+
1-BLOCK: ~0.60W (+0.15W one TrinityBlock)
114+
4-BLOCK: ~0.75W (+0.30W full pipeline)
115+
```
116+
117+
Efficiency claim: **$0.86/tok/s/W** requires real power measurement.

0 commit comments

Comments
 (0)