# 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": "输入文件列表",
    "part": "FPGA 芯片型号（必须从用户获取）",
    "constraints": "约束文件路径（可选）"
  }
}
```

#### 3.6.2 后端交互流程

**关键点**：后端必须先收集必要参数，再调用工具

1. **用户发起请求**："打开 Vivado" 或 "用 Vivado 综合"
2. **后端识别意图**：需要调用 runVivado 工具
3. **后端询问参数**：
   - FPGA 芯片型号（必须）
   - 约束文件（可选）
   - 确认顶层模块名
4. **用户提供参数**
5. **后端调用工具**：传递完整参数给前端
6. **前端执行**：VivadoRunner 执行命令
7. **返回结果**：后端接收结果并展示给用户

#### 3.6.3 调用示例（完整交互）

```
用户：帮我用 Vivado 综合一下 counter.v

AI：好的，我将使用 Vivado 进行综合。请提供以下信息：
    1. FPGA 芯片型号（例如：xc7a35tcpg236-1）
    2. 是否有约束文件（.xdc）？

用户：xc7a35tcpg236-1，没有约束文件

AI：收到，开始综合...
    [调用工具] runVivado
    参数：
    - command: synthesis
    - topModule: counter
    - files: ["counter.v"]
    - part: "xc7a35tcpg236-1"

    [执行中...]
    Vivado 综合完成！
    - 芯片型号：xc7a35tcpg236-1
    - 执行时间：45 秒
    - 资源使用：LUT: 32/20800 (0.15%), FF: 8/41600 (0.02%)
    - 产出文件：counter_synth.dcp, utilization_synth.rpt
    - 已自动导入到：vivado_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，触发器