178 lines
9.6 KiB
Markdown
178 lines
9.6 KiB
Markdown
---
|
||
name: fpga-imx6-flow
|
||
description: >
|
||
Run the fpga-imx6-flow LangGraph workflow at E:\LangGraph_Design\FPGA-imx6-flow —
|
||
the closed-loop SMOD (FPGA + i.MX6) hardware-in-the-loop design/debug pipeline:
|
||
power on the board, connect JTAG, program bitstream/flash, restart the imx6 app,
|
||
analyze (ILA + COM6 serial), judge against design requirements, and iterate by
|
||
modifying RTL/imx6 code. It drives the graph in-process (no langgraph dev) and
|
||
hands the 5 interrupts (analyze / meets-requirement / propose / modify-FPGA /
|
||
modify-imx6) back to this Claude session to execute.
|
||
|
||
ALWAYS use this skill whenever the user wants to run, start, drive, resume, or
|
||
continue the fpga-imx6-flow workflow / SMOD FPGA+imx6 design loop, or says things
|
||
like "启动 fpga-imx6-flow", "跑 imx6 设计流程", "run the imx6 FPGA flow", "执行
|
||
SMOD 设计任务", "继续 imx6 工作流", "resume the imx6 design loop", even if they
|
||
don't name the project path. Before driving the workflow this skill first confirms
|
||
the langgraph conda environment from /langgraph-vivado-install is in place.
|
||
---
|
||
|
||
## What this skill does
|
||
|
||
Drives the **fpga-imx6-flow** graph (24 nodes / 34 flow-edges, 1:1 with
|
||
`Notes/fpga-imx6-flow.excalidraw`). The graph's deterministic hardware/check nodes
|
||
(power, JTAG, program, restart) run in-process; its **5 interrupt nodes** pause and
|
||
hand control to **this Claude session**, which performs the real work (analysis,
|
||
judgment, RTL/app edits) and resumes the same thread. Persistence is a SqliteSaver
|
||
file, so `start`/`resume` survive across separate process calls.
|
||
|
||
| Item | Value |
|
||
|---|---|
|
||
| Project root | `E:\LangGraph_Design\FPGA-imx6-flow` |
|
||
| Conda env | `langgraph` (`C:\Users\bowei\.conda\envs\langgraph`) |
|
||
| Graph | `app.main_graph:build_graph` (in-process; no langgraph dev) |
|
||
| Driver | `C:\Users\bowei\.claude\skills\fpga-imx6-flow\scripts\run_imx6_flow.py` |
|
||
| Checkpoint | `<project>\runs\skill_checkpoint.sqlite` (keyed by `--thread-id`) |
|
||
| Design source | `Notes/fpga-imx6-flow.excalidraw`, plan `Notes/Task00.md` |
|
||
|
||
## ⚠️ 硬件时序铁律（上电 / USB-Blast / 烧写，务必遵守）
|
||
|
||
**每次给 SMOD 上电之前，USB-Blast 必须先断开；上电完成之后再重新连接。** 绝不在
|
||
USB-Blast 处于连接状态时给板卡上电或断电（保护 JTAG 适配器与板卡）。
|
||
|
||
标准时序（图拓扑已按此实现，手动操作或写 `tools_*` / 真机脚本时也必须遵守）：
|
||
|
||
```
|
||
断电(COM8 power_off) → 确认已断电 → 断开USB-Blast(COM4 blast_off) → 确认已断开
|
||
→ 上电(COM8 power_on) → 确认已上电 → 连接USB-Blast(COM4 blast_on) → 连接JTAG/烧写/抓ILA
|
||
```
|
||
|
||
**烧写 flash 的完整闭环**（固化后必须断电重启从 flash 加载再验证）：
|
||
|
||
```
|
||
断电 → 断开USB-Blast → 上电 → 连接USB-Blast → 用 /fpga_flash 烧写flash
|
||
→ 断电 → 断开USB-Blast → 上电 → 连接USB-Blast → 通过ILA验证flash内容正确
|
||
```
|
||
|
||
- 在 LangGraph 图里：`power_off → check_power_off →(是) blast_off_a → check_blast_off
|
||
→(是) power_on → check_power →(是) blast_on → check_hw`。`flash_burn` 烧写后回到
|
||
`power_off` 做整机断电重启，再次走完上述上电时序后才 `analyze`(抓ILA验证)。
|
||
- **强化确认**：`power_on` 节点在上电前调用 `_ensure_blast_off_before_power()` 兜底确认
|
||
USB-Blast 已断开；若发现仍连接会强制断开并在 `history` 标记 `rule_violation=True`。
|
||
- vivado-mcp 工具：`power_on`/`power_off`(COM8 继电器)、`USB_Blast_on`/`USB_Blast_off`(COM4)。
|
||
|
||
> **Run via the env python directly** (not bare `conda run`): on this Windows GBK
|
||
> console, `conda run` re-prints the child's UTF-8 stdout through a GBK codec and
|
||
> **crashes on the Chinese interrupt payloads**. Use the env `python.exe`, or
|
||
> `conda run --no-capture-output`. The driver also re-configures its stdout to UTF-8.
|
||
|
||
```
|
||
PY = C:\Users\bowei\.conda\envs\langgraph\python.exe
|
||
RUN = C:\Users\bowei\.claude\skills\fpga-imx6-flow\scripts\run_imx6_flow.py
|
||
```
|
||
|
||
## Step 0 — Confirm the environment (REQUIRED before driving)
|
||
|
||
The workflow runs in the `langgraph` conda env created by **`/langgraph-vivado-install`**.
|
||
Verify it before starting, so a missing env surfaces as a clear instruction rather
|
||
than a cryptic import error mid-run:
|
||
|
||
```powershell
|
||
$py = "C:\Users\bowei\.conda\envs\langgraph\python.exe"
|
||
if (-not (Test-Path $py)) { Write-Host "[MISSING] langgraph env" } else {
|
||
& $py -c "import langgraph; from langgraph.checkpoint.sqlite import SqliteSaver; from langgraph.types import Command; print('[OK] langgraph + checkpoint-sqlite')"
|
||
}
|
||
```
|
||
|
||
- **If `[OK]`** → proceed to Step 1.
|
||
- **If missing / import fails** → tell the user the env isn't ready and to run
|
||
**`/langgraph-vivado-install`** first (it creates the `langgraph` env with
|
||
`langgraph` + `langgraph-checkpoint-sqlite` and the Vivado link). Do not proceed
|
||
until it succeeds.
|
||
|
||
**For a real-hardware run** (`--real`), additionally confirm: `env_config.json`'s
|
||
`VIVADO_BIN_PATH` is valid; the vivado-mcp `power_on`/`USB_Blast_on` tools are
|
||
available; COM4/COM6/COM8 are present (`[System.IO.Ports.SerialPort]::GetPortNames()`).
|
||
**Default runs are MOCK** (dry-run of the design loop with no hardware), because the
|
||
workflow's `tools_*` real-hardware paths are still TODO — see "Mock vs real" below.
|
||
|
||
## Step 1 — Start the workflow
|
||
|
||
Ask the user (or infer) the first-pass program mode (`bitstream` default, or `flash`)
|
||
and any `--bit-path`/`--flash-path`. Then start:
|
||
|
||
```powershell
|
||
& $py $RUN start --project-dir "E:\LangGraph_Design\FPGA-imx6-flow" `
|
||
--thread-id "imx6-<short-task-name>" --program-mode bitstream
|
||
# add --real only when hardware tools are wired and the board is connected
|
||
```
|
||
|
||
The driver prints **one JSON line** and exits:
|
||
|
||
| Exit | `status` | Meaning |
|
||
|---|---|---|
|
||
| 0 | `done` | Workflow finished (符合设计要求 / 迭代到上限) → Step 3 |
|
||
| 1 | `error` | Read `error`, diagnose, report to user |
|
||
| 2 | `interrupt` | An interrupt fired → read `interrupt.action` → Step 2 |
|
||
|
||
## Step 2 — Handle the interrupt, then resume
|
||
|
||
On exit 2, the JSON's `interrupt.action` tells you what the session must do. Perform
|
||
it, then resume the **same `--thread-id`** with a JSON payload. Repeat until exit 0.
|
||
|
||
| `action` | excalidraw node | What you (the session) do | Resume JSON |
|
||
|---|---|---|---|
|
||
| `analyze` | 通过ila/串口分析 | Grab COM6 serial log + pull ILA waveform (vivado-mcp); summarize | `{"analysis_log":"<摘要/路径>"}` |
|
||
| `meets_requirement` | 符合设计要求? | Judge the analysis against the design requirement | `{"meets": true}` or `{"meets": false}` |
|
||
| `propose` | 分析原因，提出修改方案 | Diagnose root cause; decide what to change + next program mode | `{"reason":"...","need_fpga": true/false,"need_imx6": true/false,"program_mode":"bitstream"或"flash"}` |
|
||
| `modify_fpga` | 改 RTL→综合→出 bit/flash | Edit RTL, run Vivado synth/impl, produce bit + flash files | `{"bit_path":"...","flash_path":"...","program_mode":"flash"}` |
|
||
| `modify_imx6` | VM 改 app→交叉编译 | In the Ubuntu VM (`bowei@192.168.223.128`) edit app + cross-compile | `{"app_path":"..."}` |
|
||
|
||
Resume command:
|
||
|
||
```powershell
|
||
& $py $RUN resume --project-dir "E:\LangGraph_Design\FPGA-imx6-flow" `
|
||
--thread-id "imx6-<short-task-name>" --resume-json '{"meets": false}'
|
||
```
|
||
|
||
Notes:
|
||
- Always pass the **same `--thread-id`** used at `start` — that's how the sqlite
|
||
checkpoint reattaches to the run (concurrency-safe: different tasks → different
|
||
thread ids → isolated state).
|
||
- `propose` fans out to BOTH `decide_fpga` and `decide_imx6`; with `need_fpga:false`
|
||
and `need_imx6:false` the loop goes straight to `round_done` → re-program. Setting
|
||
either true fires the corresponding `modify_*` interrupt next.
|
||
- After `round_done` the graph re-asks the program-mode decision; `program_mode` you
|
||
set in `propose`/`modify_fpga` chooses bitstream (download bit) vs flash (re-burn +
|
||
full power/connect re-sequence). This is the big closed loop.
|
||
|
||
## Step 3 — Finish
|
||
|
||
On exit 0 (`status: done`), report to the user: iterations completed and that the
|
||
design met requirements (or hit the iteration cap). Offer to inspect
|
||
`<project>\runs\` artifacts or the per-step `history`.
|
||
|
||
To abandon a paused run and start clean, delete `<project>\runs\skill_checkpoint.sqlite`
|
||
(or use a fresh `--thread-id`).
|
||
|
||
## Mock vs real
|
||
|
||
- **MOCK (default)** — `FPGA_IMX6_MOCK=1`; hardware/check nodes return success
|
||
immediately. Use this to dry-run the *design-loop logic* and the 5 interrupts with
|
||
no board attached. Great for demonstrating/validating the flow.
|
||
- **Real (`--real`)** — drives actual hardware. Requires the project's
|
||
`app/tools_hw.py` / `tools_vivado.py` / `tools_imx6.py` real paths to be implemented
|
||
(they currently raise `NotImplementedError` as TODO — they will reuse the proven
|
||
vivado-mcp serial/Vivado logic). Until then, `--real` fails at the first hardware
|
||
node; tell the user to wire the tools first (see `Notes/Task00.md` §7).
|
||
|
||
## Troubleshooting
|
||
|
||
| Symptom | Fix |
|
||
|---|---|
|
||
| `UnicodeEncodeError: 'gbk' ...` | Don't use bare `conda run`; use the env `python.exe` or `conda run --no-capture-output`. |
|
||
| `import failed ... Run /langgraph-vivado-install` | The `langgraph` env is missing/incomplete → run `/langgraph-vivado-install`. |
|
||
| Exit 1 `NotImplementedError ... tools_*` | A `--real` run hit an unwired hardware tool. Run without `--real` (mock), or implement `tools_*`. |
|
||
| `resume` seems to start over | You passed a different `--thread-id` than `start`. Use the same one. |
|
||
| Need to see the graph visually | Optional: `langgraph dev` via the project's `langgraph.json` opens Studio — not required to run. |
|