docs: 添加 Vivado 联动功能文档

- 添加 EDA 联动功能需求文档 - 添加 Vivado 联动前后端对接文档 - 添加 Vivado 联动功能技术设计文档
2026-03-12 18:01:31 +08:00
parent 11c408ce0f
commit 81717dc84f
3 changed files with 1645 additions and 0 deletions
--- a/docs/EDA联动功能需求文档.md
+++ b/docs/EDA联动功能需求文档.md
@ -0,0 +1,368 @@
+# Vivado 联动功能需求文档
+
+## 1. 项目背景
+
+### 1.1 当前状态
+
+IC Coder Plugin 目前支持：
+
+- iverilog 仿真（内置 Windows 版本）
+- VCD 波形查看
+- Verilog 代码生成和文件操作
+
+### 1.2 需求来源
+
+用户需要在 VS Code 中直接调用本地 Vivado 工具，并将产出文件自动导入到项目中，完成从仿真到 FPGA 部署的完整流程。
+
+### 1.3 Vivado 是什么？
+
+**Vivado** 是 Xilinx（现 AMD）的 FPGA 开发工具，用于将 Verilog 代码部署到 FPGA 硬件：
+
+- **综合（Synthesis）**：将 RTL 代码转换为门级网表
+- **实现（Implementation）**：布局布线，映射到具体 FPGA 芯片
+- **生成比特流（Bitstream）**：生成 .bit 配置文件用于烧录
+
+**与 iverilog 的区别**：
+
+- iverilog：只做**仿真验证**（软件层面验证逻辑）
+- Vivado：做**综合+实现+生成配置文件**（真正部署到硬件）
+
+**典型开发流程**：
+
+```
+编写 Verilog → iverilog 仿真验证 → Vivado 综合 → Vivado 实现 → 生成 .bit 文件 → 烧录到 FPGA
+```
+
+## 2. 功能目标
+
+### 2.1 核心目标
+
+- **前端工具封装**：在插件前端实现 Vivado 调用的完整逻辑
+- **后端简化调用**：后端只需调用一个工具接口
+- **文件自动导入**：Vivado 执行完成后，自动将产出文件导入到项目
+- **流程可视化**：执行进度、日志实时显示
+
+### 2.2 非功能目标
+
+- 配置简单，用户友好
+- 执行过程可视化（进度、日志）
+- 错误处理完善，提示清晰
+
+## 3. 功能详细需求
+
+### 3.1 Vivado 支持的操作
+
+#### 3.1.1 综合（Synthesis）
+
+- **输入**：Verilog/VHDL 源文件、约束文件（.xdc）
+- **输出**：设计检查点（.dcp）、综合报告（.rpt）
+- **用途**：将 RTL 代码转换为门级网表，检查资源使用情况
+
+#### 3.1.2 实现（Implementation）
+
+- **输入**：综合后的 .dcp 文件
+- **输出**：实现后的 .dcp 文件、时序报告、布局布线报告
+- **用途**：完成布局布线，检查时序是否满足要求
+
+#### 3.1.3 生成比特流（Generate Bitstream）
+
+- **输入**：实现后的 .dcp 文件
+- **输出**：比特流文件（.bit）
+- **用途**：生成可烧录到 FPGA 的配置文件
+
+### 3.2 配置管理
+
+#### 3.2.1 配置项
+
+```json
+{
+  "vivado": {
+    "enabled": true,
+    "executablePath": "C:/Xilinx/Vivado/2023.1/bin/vivado.bat",
+    "workingDir": "${workspaceFolder}/vivado_project",
+    "part": "xc7a35tcpg236-1", // FPGA 型号
+    "commands": {
+      "synthesis": "vivado -mode batch -source synth.tcl",
+      "implementation": "vivado -mode batch -source impl.tcl",
+      "bitstream": "vivado -mode batch -source bitstream.tcl"
+    },
+    "outputFiles": {
+      "synthesis": ["*.dcp", "*_synth.rpt"],
+      "implementation": ["*.dcp", "*_timing.rpt", "*_utilization.rpt"],
+      "bitstream": ["*.bit"]
+    }
+  }
+}
+```
+
+#### 3.2.2 存储位置
+
+- 全局配置：VS Code Settings（`settings.json`）
+- 项目配置：`.vscode/ic-coder-vivado.json`（优先级更高）
+
+### 3.3 工具调用接口
+
+#### 3.3.1 接口定义
+
+```typescript
+interface VivadoToolRequest {
+  command: string; // 命令类型：synthesis | implementation | bitstream
+  parameters?: {
+    topModule?: string; // 顶层模块名
+    files?: string[]; // 输入文件列表
+    part?: string; // FPGA 型号（可选，使用配置中的默认值）
+    constraints?: string; // 约束文件路径（.xdc）
+    outputDir?: string; // 输出目录
+  };
+  importOutput?: {
+    enabled: boolean; // 是否自动导入
+    targetDir: string; // 目标目录
+  };
+}
+
+interface VivadoToolResponse {
+  success: boolean;
+  command: string;
+  executionTime: number; // 执行时间（毫秒）
+  output: string; // 标准输出
+  error?: string; // 错误信息
+  importedFiles?: string[]; // 已导入的文件列表
+  reports?: {
+    // 报告摘要
+    resources?: string; // 资源使用情况
+    timing?: string; // 时序信息
+  };
+}
+```
+
+### 3.4 执行流程
+
+#### 3.4.1 参数验证
+
+- 检查 Vivado 是否已配置
+- 检查可执行文件是否存在
+- 检查输入文件是否存在
+- 检查工作目录是否存在
+
+#### 3.4.2 TCL 脚本生成
+
+根据命令类型自动生成 TCL 脚本：
+
+**综合脚本示例（synth.tcl）**：
+
+```tcl
+# 读取源文件
+read_verilog counter.v
+read_xdc constraints.xdc
+
+# 设置顶层模块
+set_property top counter [current_fileset]
+
+# 综合
+synth_design -part xc7a35tcpg236-1 -top counter
+
+# 生成报告
+report_utilization -file utilization_synth.rpt
+report_timing -file timing_synth.rpt
+
+# 保存检查点
+write_checkpoint -force counter_synth.dcp
+```
+
+#### 3.4.3 命令执行
+
+- 启动子进程执行 Vivado 命令
+- 实时捕获标准输出和错误输出
+- 向前端推送进度信息（解析日志中的进度标记）
+
+#### 3.4.4 结果处理
+
+- 检查执行结果（退出码）
+- 解析报告文件，提取关键信息（资源使用、时序）
+- 查找产出文件
+
+#### 3.4.5 文件导入
+
+- 根据配置的文件模式查找产出文件
+- 复制文件到目标目录
+- 通知用户导入结果
+
+### 3.5 UI 交互
+
+#### 3.5.1 配置界面
+
+- 在设置页面添加 "Vivado 配置" 选项
+- 支持配置 Vivado 路径、FPGA 型号
+- 支持测试 Vivado 可用性（点击按钮测试）
+
+#### 3.5.2 调用界面
+
+- 在聊天面板中，AI 可以建议使用 Vivado
+- 用户确认后，显示执行进度对话框
+- 实时显示日志输出（可折叠）
+- 显示执行状态：准备中 → 执行中 → 完成/失败
+
+#### 3.5.3 结果展示
+
+- 执行成功：显示执行时间、资源使用、时序信息
+- 执行失败：显示错误信息、建议解决方案
+- 导入文件：高亮显示已导入的文件，支持点击打开报告
+
+### 3.6 后端集成
+
+#### 3.6.1 工具定义
+
+后端在工具列表中添加 Vivado 工具：
+
+```json
+{
+  "name": "runVivado",
+  "description": "调用 Vivado 执行综合、实现或生成比特流",
+  "parameters": {
+    "command": "命令类型（synthesis/implementation/bitstream）",
+    "topModule": "顶层模块名",
+    "files": "输入文件列表",
+    "constraints": "约束文件路径（可选）"
+  }
+}
+```
+
+#### 3.6.2 调用示例
+
+```
+用户：帮我用 Vivado 综合一下 counter.v
+AI：好的，我将使用 Vivado 进行综合。
+    [调用工具] runVivado
+    参数：
+    - command: synthesis
+    - topModule: counter
+    - files: ["counter.v"]
+    - constraints: "constraints.xdc"
+
+    [执行中...]
+    Vivado 综合完成！
+    - 执行时间：45 秒
+    - 资源使用：LUT: 32/20800 (0.15%), FF: 8/41600 (0.02%)
+    - 产出文件：counter_synth.dcp, utilization_synth.rpt
+    - 已自动导入到：vivado_project/output/
+```
+
+## 4. 用户场景
+
+### 4.1 场景一：单步综合
+
+1. 用户编写完 Verilog 代码
+2. 在聊天中输入："用 Vivado 综合一下 counter.v"
+3. AI 调用 `runVivado` 工具
+4. 插件执行 Vivado 综合
+5. 综合完成后，显示资源使用情况，自动导入报告文件
+
+### 4.2 场景二：完整流程
+
+1. 用户输入："用 Vivado 跑完整个流程"
+2. AI 依次调用：
+   - 综合（Synthesis）
+   - 实现（Implementation）
+   - 生成比特流（Bitstream）
+3. 每个步骤完成后显示结果
+4. 最终生成 .bit 文件，用户可以烧录到 FPGA
+
+### 4.3 场景三：查看报告
+
+1. Vivado 执行完成后
+2. 用户点击导入的报告文件
+3. 在编辑器中查看资源使用、时序分析等信息
+
+## 5. 技术约束
+
+### 5.1 平台兼容性
+
+- Windows：支持 `.bat` 可执行文件
+- Linux：支持 shell 脚本
+- 路径分隔符自动适配
+
+### 5.2 性能要求
+
+- 命令执行不阻塞 UI
+- 综合时间可能较长（分钟级），需要进度提示
+- 日志输出实时更新，限制缓冲区大小
+
+### 5.3 安全性
+
+- 工作目录限制在项目范围内
+- 许可证路径不记录到日志
+
+## 6. 验收标准
+
+### 6.1 功能验收
+
+- [ ] 用户可以配置 Vivado 路径和 FPGA 型号
+- [ ] AI 可以通过工具调用成功执行 Vivado 综合
+- [ ] 产出文件自动导入到指定目录
+- [ ] 执行过程有清晰的进度提示
+- [ ] 报告文件可以正常打开查看
+
+### 6.2 性能验收
+
+- [ ] 小型项目综合时间 < 1 分钟
+- [ ] UI 响应流畅，不卡顿
+- [ ] 日志输出实时更新（延迟 < 500ms）
+
+### 6.3 用户体验验收
+
+- [ ] 配置界面直观易用
+- [ ] 首次使用有引导提示
+- [ ] 错误提示清晰，有解决建议
+- [ ] 导入的文件可以直接打开查看
+
+## 7. 风险和依赖
+
+### 7.1 风险
+
+- **Vivado 版本差异**：不同版本的命令行参数可能不同
+- **许可证问题**：Vivado 需要许可证才能运行
+- **路径问题**：Windows 路径中的空格和特殊字符
+- **执行时间长**：大型项目可能需要数十分钟
+
+### 7.2 依赖
+
+- 用户需要自行安装 Vivado
+- 用户需要配置正确的 Vivado 路径
+- 需要设置环境变量（如 `XILINX_VIVADO`）
+- 需要有效的 Vivado 许可证
+
+## 8. 后续扩展
+
+### 8.1 短期扩展
+
+- 支持自定义 TCL 脚本模板
+- 支持批量处理多个设计
+- 支持时序约束编辑器
+
+### 8.2 长期扩展
+
+- 支持其他 FPGA 工具（Quartus）
+- 云端 Vivado 服务集成
+- 结果对比和版本管理
+- 性能分析和优化建议
+
+---
+
+## 附录
+
+### A. Vivado 命令行参考
+
+- 官方文档：https://docs.xilinx.com/
+- TCL 命令参考：UG835
+- 设计流程参考：UG892
+
+### B. 术语表
+
+- **RTL**：Register Transfer Level，寄存器传输级
+- **综合**：Synthesis，将 RTL 代码转换为门级网表
+- **实现**：Implementation，布局布线
+- **比特流**：Bitstream，FPGA 配置文件
+- **DCP**：Design Checkpoint，Vivado 设计检查点文件
+- **XDC**：Xilinx Design Constraints，约束文件
+- **LUT**：Look-Up Table，查找表（FPGA 基本逻辑单元）
+- **FF**：Flip-Flop，触发器