IC-Coder-Plugin/docs/EDA联动功能需求文档.md

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 命令工具，不控制流程
• 后端AI控制流程：所有执行顺序、依赖检查由后端AI决策
• 工具职责单一：每个工具只负责执行一个具体命令
• 结果透明返回：执行结果完整返回给后端，由后端决定下一步

2.2 设计原则

• 前端不做流程判断，只执行命令
• 前端不检查依赖关系，由后端保证顺序
• 前端返回详细的执行结果，包括成功/失败、输出、报告等
• 后端AI根据结果智能决策是否继续

3. 功能详细需求

3.1 前端提供的工具

前端提供 4 个独立的工具，每个工具只负责执行一个命令：

3.1.1 createVivadoProject - 创建工程

• 输入：项目名称、芯片型号、源文件列表、约束文件（可选）
• 输出：工程文件（.xpr）
• 说明：创建 Vivado 工程，不执行任何构建操作

3.1.2 runVivadoSynthesis - 综合

• 输入：工程路径或源文件、芯片型号、顶层模块
• 输出：.dcp 文件、综合报告
• 说明：执行综合，前端不检查工程是否存在

3.1.3 runVivadoImplementation - 实现

• 输入：综合后的 .dcp 文件路径
• 输出：实现后的 .dcp 文件、时序报告
• 说明：执行实现，前端不检查 .dcp 是否存在

3.1.4 runVivadoBitstream - 生成比特流

• 输入：实现后的 .dcp 文件路径
• 输出：.bit 文件
• 说明：生成比特流，前端不检查 .dcp 是否存在

3.2 配置管理

3.2.1 配置项

{
  "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 通用响应格式

所有工具返回统一的响应格式：

interface VivadoToolResponse {
  success: boolean;           // 是否成功
  command: string;            // 执行的命令
  executionTime: number;      // 执行时间（毫秒）
  output: string;             // 完整输出日志
  error?: string;             // 错误信息（如果失败）
  outputFiles?: string[];     // 产出文件路径列表
  reports?: {
    resources?: string;       // 资源使用摘要
    timing?: string;          // 时序信息摘要
  };
}

3.3.2 各工具的参数定义

createVivadoProject

{
  projectName: string;        // 项目名称
  part: string;               // 芯片型号
  topModule: string;          // 顶层模块
  files: string[];            // 源文件列表
  constraints?: string;       // 约束文件（可选）
  mode: 'gui' | 'batch';      // 执行模式
}

runVivadoSynthesis

{
  projectPath?: string;       // 工程路径（可选，如果有工程）
  part: string;               // 芯片型号
  topModule: string;          // 顶层模块
  files?: string[];           // 源文件（如果没有工程）
  constraints?: string;       // 约束文件（可选）
  mode: 'gui' | 'batch';      // 执行模式
}

runVivadoImplementation

{
  dcpFile: string;            // 综合后的 .dcp 文件路径
  mode: 'gui' | 'batch';      // 执行模式
}

runVivadoBitstream

{
  dcpFile: string;            // 实现后的 .dcp 文件路径
  mode: 'gui' | 'batch';      // 执行模式
}

3.4 后端AI的职责

后端AI负责：

1. 询问用户必要参数（芯片型号、执行模式等）
2. 理解用户意图，决定调用哪些工具
3. 按正确顺序调用工具（遵循依赖关系）
4. 检查每步执行结果，决定是否继续
5. 汇总结果并展示给用户

3.4.1 询问用户参数

后端必须询问：

• 芯片型号（必需）："请提供 FPGA 芯片型号（例如：xc7a35tcpg236-1）"
• 执行模式（必需）："选择执行模式：1) 图形化 2) 后端执行"
• 约束文件（可选）："是否有约束文件（.xdc）？"

3.4.2 理解依赖关系

后端AI需要理解：

创建工程 → 综合 → 实现 → 生成比特流

如果用户说"做实现"，后端应该：

1. 先调用 createVivadoProject 创建工程
2. 再调用 runVivadoSynthesis 执行综合
3. 最后调用 runVivadoImplementation 执行实现

3.4.3 逐步调用工具

步骤1: 调用 createVivadoProject
       检查 response.success
       如果失败 → 停止并报错

步骤2: 调用 runVivadoSynthesis
       检查 response.success
       如果失败 → 停止并报错

步骤3: 调用 runVivadoImplementation
       检查 response.success
       返回最终结果

3.5 UI 交互

3.5.1 配置界面

• 在设置页面添加 "Vivado 配置" 选项
• 支持配置 Vivado 路径、FPGA 型号
• 支持测试 Vivado 可用性（点击按钮测试）

3.5.2 调用界面

• 在聊天面板中，AI 可以建议使用 Vivado
• 用户确认后，显示执行进度对话框
• 实时显示日志输出（可折叠）
• 显示执行状态：准备中 → 执行中 → 完成/失败

3.5.3 结果展示

• 执行成功：显示执行时间、资源使用、时序信息
• 执行失败：显示错误信息、建议解决方案
• 导入文件：高亮显示已导入的文件，支持点击打开报告

3.6 后端集成

3.6.1 工具定义

后端注册 4 个独立工具：

{
  "name": "createVivadoProject",
  "description": "创建 Vivado 工程。需要先询问用户芯片型号和执行模式。",
  "parameters": {
    "projectName": "项目名称",
    "part": "芯片型号（必须从用户获取）",
    "topModule": "顶层模块名",
    "files": "源文件列表",
    "constraints": "约束文件（可选）",
    "mode": "执行模式（gui/batch）"
  }
},
{
  "name": "runVivadoSynthesis",
  "description": "执行 Vivado 综合。前端不检查依赖，后端需确保工程已创建。",
  "parameters": {
    "projectPath": "工程路径（可选）",
    "part": "芯片型号",
    "topModule": "顶层模块",
    "files": "源文件（如果没有工程）",
    "constraints": "约束文件（可选）",
    "mode": "执行模式（gui/batch）"
  }
},
{
  "name": "runVivadoImplementation",
  "description": "执行 Vivado 实现。前端不检查依赖，后端需确保综合已完成。",
  "parameters": {
    "dcpFile": "综合后的 .dcp 文件路径",
    "mode": "执行模式（gui/batch）"
  }
},
{
  "name": "runVivadoBitstream",
  "description": "生成比特流。前端不检查依赖，后端需确保实现已完成。",
  "parameters": {
    "dcpFile": "实现后的 .dcp 文件路径",
    "mode": "执行模式（gui/batch）"
  }
}

3.6.2 后端调用示例

场景：用户要求完整流程

用户: 用 Vivado 跑完整流程

AI: 请提供芯片型号和执行模式
用户: xc7a35tcpg236-1，后端执行

AI 执行:
1. [调用] createVivadoProject({ projectName: "counter", part: "xc7a35tcpg236-1", ... })
   [结果] { success: true, outputFiles: ["counter.xpr"] }

2. [调用] runVivadoSynthesis({ projectPath: "counter.xpr", ... })
   [结果] { success: true, outputFiles: ["counter_synth.dcp"], reports: {...} }

3. [调用] runVivadoImplementation({ dcpFile: "counter_synth.dcp", ... })
   [结果] { success: true, outputFiles: ["counter_impl.dcp"], reports: {...} }

4. [调用] runVivadoBitstream({ dcpFile: "counter_impl.dcp", ... })
   [结果] { success: true, outputFiles: ["counter.bit"] }

AI 回复: 完成！已生成 counter.bit 文件

4. 用户场景

4.1 场景一：完整流程执行

用户输入："用 Vivado 跑完整个 FPGA 流程"

AI 交互：

AI: 好的，我将使用 Vivado 执行完整的 FPGA 开发流程。请提供以下信息：

1. FPGA 芯片型号（例如：xc7a35tcpg236-1）
2. 请选择要执行的步骤（可多选）：
   - 综合（Synthesis）
   - 实现（Implementation）
   - 生成比特流（Bitstream）
3. 执行模式：
   - 图形化模式：打开 Vivado GUI
   - 后端执行：自动在后台执行
4. 是否有约束文件（.xdc）？

用户: xc7a35tcpg236-1，全部步骤，后端执行，没有约束文件

AI: 收到！执行计划：
1. 创建工程
2. 综合
3. 实现
4. 生成比特流

开始执行...

[步骤 1/4] 创建工程...
✓ 工程创建成功（耗时 2s）

[步骤 2/4] 综合中...
✓ 综合完成（耗时 45s）
  资源使用：LUT 32/20800 (0.15%), FF 8/41600 (0.02%)

[步骤 3/4] 实现中...
✓ 实现完成（耗时 120s）
  时序：WNS 5.234ns, TNS 0.000ns（满足要求）

[步骤 4/4] 生成比特流...
✓ 比特流生成完成（耗时 15s）

所有步骤执行完毕！产出文件已导入到 vivado_output/ 目录。

4.2 场景二：只执行实现（自动补充依赖）

用户输入："用 Vivado 做实现"

AI 交互：

AI: 请提供以下信息：
1. FPGA 芯片型号
2. 执行模式（图形化/后端执行）

用户: xc7a35tcpg236-1，后端执行

AI: 注意：实现依赖综合，我将自动执行以下步骤：
1. 创建工程
2. 综合（前置依赖）
3. 实现（您选择的步骤）

是否继续？

用户: 是

AI: 开始执行...
[自动执行创建工程 → 综合 → 实现]

4.3 场景三：图形化模式

用户输入："打开 Vivado 图形界面做综合"

AI 交互：

AI: 请提供芯片型号：
用户: xc7a35tcpg236-1

AI: 正在创建工程并打开 Vivado GUI...
✓ 工程已创建
✓ Vivado 图形界面已启动

您现在可以在 Vivado 中手动操作。完成后，产出文件将保存在工程目录中。

4.4 场景四：执行中断处理

执行过程：

[步骤 1/3] 创建工程...
✓ 成功

[步骤 2/3] 综合中...
✗ 综合失败
错误：ERROR: [Synth 8-439] module 'counter' not found

AI: 综合失败，发现以下问题：
- 找不到模块 'counter'

建议检查：
1. 模块名是否正确
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，触发器