Vivado FPGA Flow (vivado-flow)
让 AI Agent 通过一个稳定的命令行工具驱动 Xilinx Vivado 完成 FPGA 设计全流程，
并自动解析时序 / 资源报告。Agent 无需手工编写 TCL，按本文档调用
scripts/vivado_cli.py 即可。
何时使用
用户出现以下任一意图时触发本 Skill：
- 新建 / 打开 Vivado 工程，添加 RTL 或约束文件
- 综合（synthesis）或布局布线（implementation / place & route）
- 生成比特流（bitstream / .bit）
- 查看时序报告（WNS / TNS / 时序收敛）或资源利用率（LUT / FF / BRAM / DSP）
环境要求
| 依赖 | 要求 |
|---|---|
| Python | 3.10+（纯标准库，无第三方依赖） |
| Vivado | 2019.2 ~ 2025.2（Windows / Linux 均可） |
| VIVADO_PATH | 环境变量，指向 vivado.bat / vivado；未设置时自动探测 C:/Xilinx、D:/Xilinx 及 PATH |
首次使用前检查环境：
python scripts/vivado_cli.py status --workdir <工程目录>
若提示未找到 Vivado：设置 VIVADO_PATH，或先用 --mock 模式验证流程。
命令速查
所有命令输出 JSON（便于 Agent 解析），退出码 0=成功 / 1=失败。
--workdir 指向会话状态文件（session.json）所在目录，默认当前目录；
同一工程的连续命令需使用相同 --workdir。
| 命令 | 用途 | 必需参数 | 最低阶段 |
|---|---|---|---|
create_project |
新建工程 | --name --dir --part |
- |
open_project |
打开 .xpr 工程 | --xpr |
- |
add_sources |
添加 RTL/XDC 并设顶层 | --top --rtl |
created |
synth |
综合 | - | sources_added |
impl |
布局布线 | - | synthesized |
bitstream |
生成比特流 | - | implemented |
report_timing |
时序摘要 WNS/TNS/WHS/THS | - | synthesized |
report_utilization |
资源利用率 | - | synthesized |
status |
查看会话状态 | - | - |
tcl |
透传任意 TCL | --script |
- |
通用参数：--workdir <目录>、--mock（模拟执行，无需真实 Vivado）、
--human（人类可读输出）、--timeout <秒>（默认 7200）。
标准流程（必须按此顺序）
# 1. 新建工程（part 例: xc7a35tcsg324-1 / xcu250-figd2104-2L-e）
python scripts/vivado_cli.py create_project --name myproj \
--dir D:/work/myproj --part xc7a35tcsg324-1 --workdir D:/work/myproj
# 2. 添加源文件（--rtl 可多个；--constraints 可选）
python scripts/vivado_cli.py add_sources --top top_module \
--rtl D:/work/myproj/top.v D:/work/myproj/sub.v \
--constraints D:/work/myproj/top.xdc --workdir D:/work/myproj
# 3. 综合 → 4. 布局布线 → 5. 比特流
python scripts/vivado_cli.py synth --workdir D:/work/myproj
python scripts/vivado_cli.py impl --workdir D:/work/myproj
python scripts/vivado_cli.py bitstream --workdir D:/work/myproj
# 6. 报告（WNS 为负表示时序违例，需用户处理）
python scripts/vivado_cli.py report_timing --workdir D:/work/myproj
python scripts/vivado_cli.py report_utilization --workdir D:/work/myproj
流程约束：工具内部有阶段状态机，未综合直接 impl / bitstream 会返回错误并提示缺失步骤，按提示补跑即可。报告命令在综合后即可运行（用综合网表）。
输出解析要点
synth/impl返回timing（wns/tns/whs/ths）与utilization（lut/ff/bram/dsp 的 used/available/percent）report_timing返回timing对象；WNS < 0 即存在时序违例，应提示用户并提供常见处置建议（降时钟频率 / 加流水线 / 约束修正）- 所有命令的
workdir/report_file字段给出产物落盘位置（.dcp / .bit / .rpt）
注意事项
- Vivado 冷启动慢（10~30 秒），综合/实现大工程耗时可达数分钟，属正常；必要时调大
--timeout - 路径统一用绝对路径；Windows 用
D:/...正斜杠格式 --mock模式：不调用真实 Vivado，返回模拟报告，用于测试/演示流程- 所有文件操作均由工具内部以参数方式传入 subprocess，不使用 shell 拼接，无注入风险
- 若用户有已存在的 .xpr 工程，用
open_project而非重建
验证示例
examples/adder4.v 为 4 位加法器示例，可用 --mock 快速验证安装：
python scripts/vivado_cli.py create_project --name demo --dir C:/tmp/demo \
--part xc7a35tcsg324-1 --mock
python scripts/vivado_cli.py add_sources --top adder4 \
--rtl examples/adder4.v --mock
python scripts/vivado_cli.py synth --mock
目录结构
vivado-skill/
├── SKILL.md # 本手册
├── scripts/
│ ├── vivado_cli.py # 主工具（所有命令入口）
│ ├── tcl_builder.py # TCL 脚本构建（内部）
│ └── report_parser.py # 报告解析（内部）
└── examples/
└── adder4.v # 示例源文件
