# Vivado 联动前后端对接文档

## 1. 前端提供的工具

前端提供 4 个独立工具，每个工具执行一个 Vivado 命令。

### 1.1 createVivadoProject - 创建工程

**参数**：
```typescript
{
  projectName: string;      // 项目名称
  part: string;             // 芯片型号（如 xc7a35tcpg236-1）
  topModule: string;        // 顶层模块名
  files: string[];          // 源文件路径列表
  constraints?: string;     // 约束文件路径（可选）
  mode: 'gui' | 'batch';    // gui=打开图形界面，batch=后台执行
}
```

**返回**：
```typescript
{
  success: boolean;         // 是否成功
  command: "create_project";
  executionTime: number;    // 执行时间（毫秒）
  output: string;           // 完整日志
  error?: string;           // 失败原因（如果失败）
  outputFiles?: string[];   // 产出的工程文件路径
}
```

### 1.2 runVivadoSynthesis - 综合

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

**返回**：
```typescript
{
  success: boolean;
  command: "synthesis";
  executionTime: number;
  output: string;
  error?: string;           // 失败原因
  outputFiles?: string[];   // .dcp 文件等
  reports?: {
    resources?: string;     // 资源使用摘要
    timing?: string;        // 时序摘要
  };
}
```

### 1.3 runVivadoImplementation - 实现

**参数**：
```typescript
{
  dcpFile: string;          // 综合后的 .dcp 文件路径
  mode: 'gui' | 'batch';
}
```

**返回**：
```typescript
{
  success: boolean;
  command: "implementation";
  executionTime: number;
  output: string;
  error?: string;           // 失败原因
  outputFiles?: string[];   // 实现后的 .dcp 文件等
  reports?: {
    resources?: string;
    timing?: string;
  };
}
```

### 1.4 runVivadoBitstream - 生成比特流

**参数**：
```typescript
{
  dcpFile: string;          // 实现后的 .dcp 文件路径
  mode: 'gui' | 'batch';
}
```

**返回**：
```typescript
{
  success: boolean;
  command: "bitstream";
  executionTime: number;
  output: string;
  error?: string;           // 失败原因
  outputFiles?: string[];   // .bit 文件路径
}
```

## 2. 前端职责

- 接收后端工具调用
- 生成对应的 TCL 脚本
- 执行 Vivado 命令
- 捕获输出日志
- 解析报告文件（提取资源和时序摘要）
- 返回执行结果

**前端不做**：
- 不检查依赖关系
- 不验证执行顺序
- 不控制流程

## 3. 后端职责

- 询问用户参数（芯片型号、执行模式等）
- 理解依赖关系（创建工程 → 综合 → 实现 → 生成比特流）
- 按正确顺序调用工具
- 检查每步的 `success` 字段
- 如果失败，读取 `error` 字段并提示用户
- 汇总结果展示给用户

## 4. 调用示例

```
用户: 用 Vivado 做综合

后端:
1. 询问芯片型号 → xc7a35tcpg236-1
2. 询问执行模式 → batch

3. 调用 createVivadoProject(...)
   返回: { success: true, outputFiles: ["counter.xpr"] }

4. 调用 runVivadoSynthesis(...)
   返回: { success: true, outputFiles: ["counter_synth.dcp"], reports: {...} }

5. 展示结果给用户
```

## 5. 错误处理

如果某步失败：
```typescript
{
  success: false,
  error: "ERROR: [Synth 8-439] module 'counter' not found",
  output: "详细日志..."
}
```

后端应该：
1. 停止后续步骤
2. 提取 `error` 字段
3. 给用户提示和建议