# 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 配置项

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

#### 3.3.2 各工具的参数定义

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

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

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

**runVivadoBitstream**
```typescript
{
  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 个独立工具：

```json
{
  "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，触发器