docs: 完善 Vivado 联动文档
- 添加后端工具调用控制前端的详细说明 - 新增 mode 参数（batch/gui）支持批处理和图形界面模式 - 补充参数询问流程和验证规则 - 添加完整实现示例：生成比特流和布局布线 - 更新所有调用示例包含必需参数
This commit is contained in:
Roe-xin
@ -29,7 +29,7 @@ VivadoRunner
|
||||
```json
|
||||
{
|
||||
"name": "runVivado",
|
||||
"description": "调用本地 Vivado 工具执行 FPGA 综合、实现或生成比特流。用于将 Verilog 代码部署到 FPGA 硬件。",
|
||||
"description": "调用本地 Vivado 工具执行 FPGA 综合、实现或生成比特流。用于将 Verilog 代码部署到 FPGA 硬件。使用前必须先询问用户必要的参数（如芯片型号、执行模式）。",
|
||||
"inputSchema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
@ -53,17 +53,48 @@ VivadoRunner
|
||||
},
|
||||
"part": {
|
||||
"type": "string",
|
||||
"description": "FPGA 型号，可选，默认使用配置中的型号"
|
||||
"description": "FPGA 芯片型号（如 xc7a35tcpg236-1），必须从用户处获取"
|
||||
},
|
||||
"mode": {
|
||||
"type": "string",
|
||||
"enum": ["batch", "gui"],
|
||||
"description": "执行模式：batch(后台批处理)、gui(打开图形界面)，必须询问用户"
|
||||
}
|
||||
},
|
||||
"required": ["command", "topModule", "files"]
|
||||
"required": ["command", "topModule", "files", "part", "mode"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2.2 调用示例
|
||||
### 2.2 后端调用前的准备工作
|
||||
|
||||
#### 示例 1：综合单个文件
|
||||
**重要**：后端在调用 `runVivado` 工具前，必须先向用户询问必要参数：
|
||||
|
||||
1. **芯片型号（part）**：必须询问，例如 "xc7a35tcpg236-1"
|
||||
2. **执行模式（mode）**：必须询问用户选择
|
||||
- `batch`：后台批处理执行，自动完成
|
||||
- `gui`：打开 Vivado 图形界面，用户手动操作
|
||||
3. **顶层模块名**：可从文件名推断，但建议确认
|
||||
4. **约束文件**：询问是否有时序约束文件（.xdc）
|
||||
|
||||
**询问示例**：
|
||||
```
|
||||
AI: 我将使用 Vivado 进行综合。请提供以下信息：
|
||||
1. FPGA 芯片型号（例如：xc7a35tcpg236-1）
|
||||
2. 执行模式：
|
||||
- 批处理模式：后台自动执行，完成后返回结果
|
||||
- 图形界面：打开 Vivado GUI，您可以手动操作
|
||||
3. 是否有约束文件（.xdc）？
|
||||
|
||||
用户: xc7a35tcpg236-1，批处理模式，没有约束文件
|
||||
|
||||
AI: 好的，开始后台综合...
|
||||
[调用 runVivado 工具]
|
||||
```
|
||||
|
||||
### 2.3 调用示例
|
||||
|
||||
#### 示例 1：综合单个文件（批处理模式）
|
||||
|
||||
```json
|
||||
{
|
||||
@ -71,12 +102,14 @@ VivadoRunner
|
||||
"parameters": {
|
||||
"command": "synthesis",
|
||||
"topModule": "counter",
|
||||
"files": ["counter.v"]
|
||||
"files": ["counter.v"],
|
||||
"part": "xc7a35tcpg236-1",
|
||||
"mode": "batch"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 示例 2：综合带约束文件
|
||||
#### 示例 2：综合带约束文件（图形界面模式）
|
||||
|
||||
```json
|
||||
{
|
||||
@ -85,38 +118,71 @@ VivadoRunner
|
||||
"command": "synthesis",
|
||||
"topModule": "uart_top",
|
||||
"files": ["uart_tx.v", "uart_rx.v", "uart_top.v"],
|
||||
"constraints": "constraints.xdc"
|
||||
"constraints": "constraints.xdc",
|
||||
"part": "xc7k325tffg900-2",
|
||||
"mode": "gui"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 示例 3：实现（需要先综合）
|
||||
#### 示例 3：实现（批处理模式）
|
||||
|
||||
```json
|
||||
{
|
||||
"tool": "runVivado",
|
||||
"parameters": {
|
||||
"command": "implementation",
|
||||
"topModule": "counter"
|
||||
"topModule": "counter",
|
||||
"part": "xc7a35tcpg236-1",
|
||||
"mode": "batch"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 示例 4：生成比特流（需要先实现）
|
||||
#### 示例 4：生成比特流（图形界面）
|
||||
|
||||
```json
|
||||
{
|
||||
"tool": "runVivado",
|
||||
"parameters": {
|
||||
"command": "bitstream",
|
||||
"topModule": "counter"
|
||||
"topModule": "counter",
|
||||
"part": "xc7a35tcpg236-1",
|
||||
"mode": "gui"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 3. 前端接收和处理
|
||||
|
||||
### 3.1 MessageHandler 处理逻辑
|
||||
### 3.1 后端如何控制前端
|
||||
|
||||
**核心机制**：后端通过调用 `runVivado` 工具来控制前端执行 Vivado 命令。
|
||||
|
||||
**控制流程**：
|
||||
1. 后端识别用户意图（如"打开 Vivado"、"开始仿真"）
|
||||
2. 后端向用户询问必要参数（芯片型号等）
|
||||
3. 后端调用 `runVivado` 工具，传递参数
|
||||
4. 前端接收工具调用，执行相应操作
|
||||
5. 前端返回执行结果给后端
|
||||
6. 后端将结果展示给用户
|
||||
|
||||
**示例场景**：
|
||||
```
|
||||
用户输入："打开 Vivado 进行综合"
|
||||
|
||||
后端处理：
|
||||
1. 识别意图 → 需要调用 runVivado 工具
|
||||
2. 检查参数 → 缺少芯片型号
|
||||
3. 询问用户 → "请提供 FPGA 芯片型号"
|
||||
4. 用户回复 → "xc7a35tcpg236-1"
|
||||
5. 调用工具 → runVivado({ command: "synthesis", part: "xc7a35tcpg236-1", ... })
|
||||
6. 前端执行 → VivadoRunner 启动 Vivado
|
||||
7. 返回结果 → { success: true, ... }
|
||||
8. 展示结果 → "综合完成，耗时 45 秒"
|
||||
```
|
||||
|
||||
### 3.2 MessageHandler 处理逻辑
|
||||
|
||||
前端在 `messageHandler.ts` 中添加工具处理：
|
||||
|
||||
@ -141,7 +207,28 @@ async function handleVivadoTool(
|
||||
parameters: any
|
||||
): Promise<VivadoToolResponse> {
|
||||
|
||||
const { command, topModule, files, constraints, part } = parameters;
|
||||
const { command, topModule, files, constraints, part, mode } = parameters;
|
||||
|
||||
// 验证必需参数
|
||||
if (!part) {
|
||||
return {
|
||||
success: false,
|
||||
command,
|
||||
executionTime: 0,
|
||||
output: '',
|
||||
error: '缺少必需参数：芯片型号（part）。后端应该先询问用户。'
|
||||
};
|
||||
}
|
||||
|
||||
if (!mode) {
|
||||
return {
|
||||
success: false,
|
||||
command,
|
||||
executionTime: 0,
|
||||
output: '',
|
||||
error: '缺少必需参数：执行模式（mode）。后端应该询问用户选择 batch 或 gui。'
|
||||
};
|
||||
}
|
||||
|
||||
// 构建请求
|
||||
const request: VivadoToolRequest = {
|
||||
@ -150,10 +237,11 @@ async function handleVivadoTool(
|
||||
topModule,
|
||||
files,
|
||||
constraints,
|
||||
part
|
||||
part,
|
||||
mode
|
||||
},
|
||||
importOutput: {
|
||||
enabled: true,
|
||||
enabled: mode === 'batch', // 只有批处理模式才自动导入
|
||||
targetDir: path.join(
|
||||
vscode.workspace.workspaceFolders![0].uri.fsPath,
|
||||
'vivado_output'
|
||||
@ -222,7 +310,7 @@ async function handleVivadoTool(
|
||||
|
||||
## 5. 后端使用指南
|
||||
|
||||
### 5.1 AI 对话流程
|
||||
### 5.1 AI 对话流程（完整版）
|
||||
|
||||
```
|
||||
用户：帮我用 Vivado 综合一下 counter.v
|
||||
@ -233,6 +321,14 @@ AI 分析：
|
||||
3. 命令类型是 synthesis
|
||||
4. 顶层模块名从文件名推断为 counter
|
||||
5. 输入文件是 counter.v
|
||||
6. ⚠️ 缺少必要参数：芯片型号
|
||||
|
||||
AI 回复用户：
|
||||
"好的，我将使用 Vivado 进行综合。请提供以下信息：
|
||||
1. FPGA 芯片型号（例如：xc7a35tcpg236-1、xc7k325tffg900-2）
|
||||
2. 是否有约束文件（.xdc）？"
|
||||
|
||||
用户：xc7a35tcpg236-1，没有约束文件
|
||||
|
||||
AI 调用工具：
|
||||
{
|
||||
@ -240,7 +336,8 @@ AI 调用工具：
|
||||
"parameters": {
|
||||
"command": "synthesis",
|
||||
"topModule": "counter",
|
||||
"files": ["counter.v"]
|
||||
"files": ["counter.v"],
|
||||
"part": "xc7a35tcpg236-1"
|
||||
}
|
||||
}
|
||||
|
||||
@ -249,6 +346,7 @@ AI 调用工具：
|
||||
AI 回复用户：
|
||||
"Vivado 综合完成！
|
||||
- 执行时间：45.2 秒
|
||||
- 芯片型号：xc7a35tcpg236-1
|
||||
- 资源使用：LUT: 32/20800 (0.15%), FF: 8/41600 (0.02%)
|
||||
- 产出文件已导入到 vivado_output 目录"
|
||||
```
|
||||
@ -258,18 +356,25 @@ AI 回复用户：
|
||||
```
|
||||
用户：用 Vivado 跑完整个流程
|
||||
|
||||
AI：好的，我将依次执行综合、实现和生成比特流。
|
||||
AI：好的，我将依次执行综合、实现和生成比特流。请提供：
|
||||
1. FPGA 芯片型号
|
||||
2. 顶层模块名
|
||||
3. 是否有约束文件
|
||||
|
||||
用户：xc7a35tcpg236-1，顶层模块是 counter，没有约束文件
|
||||
|
||||
AI：收到，开始执行...
|
||||
|
||||
步骤 1：综合
|
||||
[调用] runVivado { command: "synthesis", ... }
|
||||
[调用] runVivado { command: "synthesis", topModule: "counter", files: ["counter.v"], part: "xc7a35tcpg236-1" }
|
||||
[结果] 综合成功，耗时 45s
|
||||
|
||||
步骤 2：实现
|
||||
[调用] runVivado { command: "implementation", ... }
|
||||
[调用] runVivado { command: "implementation", topModule: "counter", part: "xc7a35tcpg236-1" }
|
||||
[结果] 实现成功，耗时 120s，时序满足要求
|
||||
|
||||
步骤 3：生成比特流
|
||||
[调用] runVivado { command: "bitstream", ... }
|
||||
[调用] runVivado { command: "bitstream", topModule: "counter", part: "xc7a35tcpg236-1" }
|
||||
[结果] 比特流生成成功，文件：counter.bit
|
||||
|
||||
完成！所有文件已导入到 vivado_output 目录。
|
||||
@ -374,34 +479,152 @@ test('文件不存在', async () => {
|
||||
|
||||
## 9. 注意事项
|
||||
|
||||
### 9.1 执行时间
|
||||
### 9.1 后端必须询问的参数
|
||||
|
||||
**关键要求**：后端在调用 `runVivado` 前，必须先向用户收集以下参数：
|
||||
|
||||
| 参数 | 是否必须 | 询问方式 | 示例 |
|
||||
|------|---------|---------|------|
|
||||
| part（芯片型号） | ✅ 必须 | 直接询问 | "请提供 FPGA 芯片型号（如 xc7a35tcpg236-1）" |
|
||||
| mode（执行模式） | ✅ 必须 | 提供选项 | "选择执行模式：1.批处理 2.图形界面" |
|
||||
| topModule | ✅ 必须 | 可推断或询问 | 从文件名推断，或询问"顶层模块名是什么？" |
|
||||
| files | ✅ 必须（综合时） | 可推断或询问 | 从当前文件或工作区推断 |
|
||||
| constraints | ❌ 可选 | 询问 | "是否有约束文件（.xdc）？" |
|
||||
|
||||
### 9.2 常见用户输入场景
|
||||
|
||||
#### 场景 1：用户说"打开 Vivado"
|
||||
```
|
||||
用户：打开 Vivado
|
||||
|
||||
后端分析：用户想使用 Vivado，但没有指定具体操作
|
||||
|
||||
后端回复：
|
||||
"好的，请问您想执行什么操作？
|
||||
1. 综合（Synthesis）- 将 Verilog 转换为门级网表
|
||||
2. 实现（Implementation）- 布局布线
|
||||
3. 生成比特流（Bitstream）- 生成 .bit 文件
|
||||
|
||||
另外，请提供：
|
||||
- FPGA 芯片型号（例如：xc7a35tcpg236-1）
|
||||
- 执行模式：批处理（后台自动）或 图形界面（手动操作）"
|
||||
```
|
||||
|
||||
#### 场景 2：用户说"开始仿真"
|
||||
```
|
||||
用户：开始仿真
|
||||
|
||||
后端分析：用户可能混淆了仿真和综合
|
||||
|
||||
后端回复：
|
||||
"您是想：
|
||||
1. 使用 iverilog 进行功能仿真（验证逻辑）
|
||||
2. 使用 Vivado 进行综合（部署到 FPGA）
|
||||
|
||||
请选择您需要的操作。"
|
||||
```
|
||||
|
||||
#### 场景 3：用户提供完整信息
|
||||
```
|
||||
用户：用 Vivado 综合 counter.v，芯片是 xc7a35tcpg236-1，批处理模式
|
||||
|
||||
后端分析：信息完整，可以直接调用
|
||||
|
||||
后端操作：
|
||||
[调用] runVivado({
|
||||
command: "synthesis",
|
||||
topModule: "counter",
|
||||
files: ["counter.v"],
|
||||
part: "xc7a35tcpg236-1",
|
||||
mode: "batch"
|
||||
})
|
||||
```
|
||||
|
||||
#### 场景 4：用户选择图形界面
|
||||
```
|
||||
用户：打开 Vivado 图形界面做综合
|
||||
|
||||
后端分析：用户明确要求 GUI 模式
|
||||
|
||||
后端询问：
|
||||
"好的，请提供：
|
||||
1. FPGA 芯片型号
|
||||
2. 顶层模块名"
|
||||
|
||||
用户：xc7a35tcpg236-1, counter
|
||||
|
||||
后端操作：
|
||||
[调用] runVivado({
|
||||
command: "synthesis",
|
||||
topModule: "counter",
|
||||
files: ["counter.v"],
|
||||
part: "xc7a35tcpg236-1",
|
||||
mode: "gui"
|
||||
})
|
||||
|
||||
前端执行：
|
||||
- 生成 TCL 脚本和项目文件
|
||||
- 执行: vivado counter_project.xpr (打开图形界面)
|
||||
- 返回: { success: true, message: "Vivado GUI 已启动" }
|
||||
|
||||
后端回复：
|
||||
"Vivado 图形界面已打开，您可以在界面中手动操作。"
|
||||
```
|
||||
|
||||
### 9.3 执行时间
|
||||
- 综合：小型设计 30s-2min，大型设计 5-30min
|
||||
- 实现：通常是综合时间的 2-3 倍
|
||||
- 生成比特流：通常 10-30s
|
||||
|
||||
后端应该设置合理的超时时间（建议 10 分钟）。
|
||||
|
||||
### 9.2 依赖关系
|
||||
### 9.4 依赖关系
|
||||
- `implementation` 需要先执行 `synthesis`
|
||||
- `bitstream` 需要先执行 `implementation`
|
||||
|
||||
后端 AI 应该理解这个依赖关系，按顺序调用。
|
||||
|
||||
### 9.3 文件路径
|
||||
### 9.5 文件路径
|
||||
- 所有文件路径都是相对于工作区根目录
|
||||
- 前端会自动解析为绝对路径
|
||||
- 支持相对路径和绝对路径
|
||||
|
||||
## 10. 快速集成清单
|
||||
## 10. 参数传递详细说明
|
||||
|
||||
### 10.1 必需参数
|
||||
|
||||
| 参数 | 类型 | 说明 | 获取方式 |
|
||||
|------|------|------|----------|
|
||||
| command | string | 命令类型 | 从用户意图推断 |
|
||||
| topModule | string | 顶层模块名 | 从文件名推断或询问用户 |
|
||||
| files | string[] | 源文件列表 | 从工作区查找或用户指定 |
|
||||
| part | string | 芯片型号 | **必须询问用户** |
|
||||
|
||||
### 10.2 可选参数
|
||||
|
||||
| 参数 | 类型 | 说明 | 默认值 |
|
||||
|------|------|------|--------|
|
||||
| constraints | string | 约束文件路径 | 无 |
|
||||
|
||||
### 10.3 参数验证规则
|
||||
|
||||
后端在调用前应验证：
|
||||
- `part` 格式正确（如 xc7a35tcpg236-1）
|
||||
- `files` 数组不为空
|
||||
- `topModule` 不为空
|
||||
- `command` 在枚举值内
|
||||
|
||||
## 11. 快速集成清单
|
||||
|
||||
后端开发者需要做的事情：
|
||||
|
||||
- [ ] 在工具列表中注册 `runVivado` 工具
|
||||
- [ ] **实现参数询问逻辑（芯片型号等）**
|
||||
- [ ] 实现工具调用逻辑（发送请求到前端）
|
||||
- [ ] 处理返回结果（success/error）
|
||||
- [ ] 实现错误处理和用户提示
|
||||
- [ ] 理解三个命令的依赖关系
|
||||
- [ ] 设置合理的超时时间
|
||||
- [ ] 设置合理的超时时间（建议 10 分钟）
|
||||
- [ ] 编写测试用例
|
||||
|
||||
前端开发者需要做的事情：
|
||||
@ -411,3 +634,4 @@ test('文件不存在', async () => {
|
||||
- [ ] 实现进度推送
|
||||
- [ ] 实现结果展示
|
||||
- [ ] 处理各种错误情况
|
||||
- [ ] 验证传入的参数完整性
|
||||
|
||||
Reference in New Issue
Block a user