# AST波形调试工具 - TypeScript重写规范

## 一、项目背景

将Python实现的Verilog AST波形调试工具重写为TypeScript，用于VSCode插件。

**已完成部分**：
- ✅ Verilog AST解析（生成JSON格式的信号依赖图）
- ✅ 图结构定义

**待重写部分**：
- ⚠️ BFS信号回溯
- ⚠️ VCD波形解析
- ⚠️ 仿真输出解析
- ⚠️ 工具整合封装

---

## 二、数据结构定义

### 2.1 AST图结构（已完成）

```typescript
interface ASTNode {
  id: string;
  attributes: {
    lines: [number, number];  // [起始行, 结束行]
    type: string;             // Input/Output/Reg/Wire/Always/Assign等
  };
}

interface ASTEdge {
  from: string;   // 控制信号
  to: string;     // 被控制信号
  attributes: {
    lines: [number, number];
    type: string;  // Always/Assign/IfStatement等
  };
}

interface ASTGraph {
  metadata: {
    moduleName: string;
    nodeCount: number;
    edgeCount: number;
    generatedAt: string;
  };
  nodes: ASTNode[];
  edges: ASTEdge[];
}
```

### 2.2 追踪结果结构

```typescript
interface TraceResult {
  controlSignals: Map<string, [number, number]>;  // 信号名 -> 代码行号
  signalLevelTracer: string[][];                  // 每层的控制关系链
}
```

### 2.3 波形数据结构

```typescript
interface WaveformData {
  time: number;           // 时间点(ns)
  signals: {
    [signalName: string]: string;  // 信号名 -> 值(十六进制)
  };
}

interface MismatchInfo {
  signals: string[];      // 出错的信号列表
  firstMismatchTime: number;  // 第一次出错的时间
}
```

---

## 三、需要重写的模块

### 3.1 BFS信号回溯模块

**源文件**: `debug_graph_analyzer.py`
**代码行数**: ~70行
**第三方依赖**: 无

#### 功能描述
从出错信号出发，BFS反向遍历图，找到所有控制该信号的上游信号。

#### 输入输出
```typescript
// 输入
graph: ASTGraph           // AST图（JSON格式）
targetSignals: string[]   // 出错的信号列表，如 ['count', 'overflow']
k: number                 // 回溯层数
signalOnly: boolean       // 是否只返回信号节点（过滤Always/Assign等）

// 输出
TraceResult {
  controlSignals: Map<string, [number, number]>,
  signalLevelTracer: string[][]
}
```

#### 核心算法（伪代码）
```
1. 构建前驱映射（反向边）
   for each edge in graph.edges:
     predecessorMap[edge.to].push(edge.from)

2. 初始化BFS队列
   for each signal in targetSignals:
     queue.push([signal, signal])
     controlSignals.set(signal, node.lines)

3. BFS遍历K层
   for level = 0 to k:
     while queue not empty:
       [curSignal, controlledSignal] = queue.pop()
       记录关系: curSignal -> controlledSignal

       for each predecessor of curSignal:
         if not visited and not filtered:
           queue.push([predecessor, curSignal])

     记录本层关系到 signalLevelTracer

4. 返回结果
```

#### 过滤规则
```typescript
// 需要过滤的节点类型
const FILTERED_TYPES = ['Parameter', 'Localparam'];

// signalOnly=true时，还需要过滤以下前缀
const FILTERED_PREFIXES = ['Always', 'Assign', 'Module', 'IntConst'];
```

---

### 3.2 仿真输出解析模块

**源文件**: `vcd_waveform_analyzer.py` 中的 `parse_mismatch()`
**代码行数**: ~20行
**第三方依赖**: 无

#### 功能描述
解析仿真工具的输出文本，提取出错信号名和出错时间。

#### 输入输出
```typescript
// 输入
testOutput: string  // 仿真工具的输出文本

// 输出
MismatchInfo {
  signals: string[],        // 出错信号列表
  firstMismatchTime: number // 第一次出错时间(ns)
}
```

#### 解析规则
```typescript
// 需要匹配的格式
// "First mismatch occurred at time 100. Output 'count' ..."

const pattern = /First mismatch occurred at time (\d+).*Output '(\w+)'/g;

// 提取所有匹配
// 返回信号列表和最小时间戳
```

#### 示例
```
输入:
"First mismatch occurred at time 100. Output 'count' expected 0001, got 0000
First mismatch occurred at time 150. Output 'overflow' expected 1, got 0"

输出:
{
  signals: ['count', 'overflow'],
  firstMismatchTime: 100
}
```

---

### 3.3 VCD波形解析模块

**源文件**: `vcd_waveform_analyzer.py` 中的 `get_tabular()` 和 `tabular_via_dataframe()`
**代码行数**: ~150行
**第三方依赖**: Python版用了 `vcdvcd`, `pandas`, `numpy`

#### 功能描述
读取VCD（Value Change Dump）波形文件，提取指定信号的波形值，生成表格。

#### VCD文件格式简介
```vcd
$timescale 1ns $end
$scope module tb $end
$var wire 1 ! clk $end
$var wire 8 " count [7:0] $end
$upscope $end
$enddefinitions $end
#0
b0 "
1!
#5
0!
#10
1!
b00000001 "
...
```

#### 输入输出
```typescript
// 输入
vcdPath: string           // VCD文件路径
signalsToTrace: string[]  // 需要提取的信号列表
offset: number            // 时间偏移（从哪个时间点开始）
windowSize: number        // 窗口大小（提取多少个时间点）

// 输出
string  // 格式化的波形表格字符串
```

#### 输出格式示例
```
### First mismatched signals time(ns) Trace ###
time(ns)  clk  reset  count_ref  count_dut
0         1    1      00         00
5         0    1      00         00
10        1    0      00         00
15        0    0      00         00
20        1    0      01         00  <- mismatch
### First mismatched signals time(ns) End ###
```

#### TS实现建议
1. **方案A**: 找现有的JS VCD解析库
   - 搜索: `npm vcd parser`, `vcd-stream`, `wavedrom`

2. **方案B**: 自己实现简单的VCD解析器
   - VCD格式相对简单，核心是解析变量定义和时间变化
   - 约100-150行代码

#### VCD解析核心逻辑
```typescript
class VCDParser {
  signals: Map<string, Signal>;  // 信号定义
  timeValues: Map<number, Map<string, string>>;  // 时间 -> 信号值

  parse(vcdContent: string): void {
    // 1. 解析头部（$var定义）
    // 2. 解析数据部分（#时间 和 值变化）
  }

  getSignalValues(signalName: string, startTime: number, endTime: number): WaveformData[] {
    // 提取指定信号在时间范围内的值
  }
}
```

---

### 3.4 工具整合封装模块

**源文件**: `waveform_trace_tool.py`
**代码行数**: ~150行
**第三方依赖**: 依赖上面所有模块

#### 功能描述
整合所有模块，提供统一的调试接口。

#### 输入输出
```typescript
// 输入
verilogFilePath: string      // Verilog文件路径
vcdFilePath: string          // VCD波形文件路径
simulationOutput: string     // 仿真输出文本
traceLevel: number           // 回溯层数

// 输出
string  // 完整的调试报告
```

#### 调试报告格式
```
[Signal Traces] Backtrace control signal relations.
clk->count
reset->count
-count->state
--state->out (*last output port level)

[Signal Waveform]:
<signal>_ref 是期望值（golden）
<signal>_dut 是实际输出
[Traced Signals]: out, state, count, clk, reset

[Table Waveform in hexadecimal format]
time(ns)  clk  reset  count_ref  count_dut
...

[Verilog of DUT]:
```verilog
module counter(...);
...
endmodule
```

[Hint] ...
```

---

## 四、调用流程图

```
┌─────────────────────────────────────────────────────────────────┐
│                     waveform_trace_tool()                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. 检查文件是否存在                                            │
│     ├── verilogFilePath                                         │
│     └── vcdFilePath                                             │
│                                                                 │
│  2. 加载AST图（已有JSON）                                       │
│     └── graph = loadASTGraph(verilogFilePath)                   │
│                                                                 │
│  3. 解析仿真输出，获取出错信号                                  │
│     └── mismatchInfo = parseMismatch(simulationOutput)          │
│         ├── signals: ['count', 'overflow']                      │
│         └── firstMismatchTime: 100                              │
│                                                                 │
│  4. BFS回溯，找到控制信号链                                     │
│     └── traceResult = getKControlSignals(graph, signals, k)     │
│         ├── controlSignals: Map<信号名, 行号>                   │
│         └── signalLevelTracer: [['clk->count'], ...]            │
│                                                                 │
│  5. 读取VCD波形，提取相关信号的值                               │
│     └── waveformTable = getTabular(vcdPath, signals, offset)    │
│                                                                 │
│  6. 读取Verilog源码                                             │
│     └── verilogCode = readFile(verilogFilePath)                 │
│                                                                 │
│  7. 组装调试报告                                                │
│     └── return formatReport(traceResult, waveformTable, code)   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

---

## 五、参考实现

### 5.1 Python源文件位置

```
ast_debug_core/
├── ast_node.py              # AST节点定义（参考32-137行）
├── graph_builder.py         # 图构建入口
├── debug_graph_analyzer.py  # BFS回溯（完整文件，约70行）
├── vcd_waveform_analyzer.py # VCD解析（参考89-285行）
└── waveform_trace_tool.py   # 工具封装（完整文件，约180行）
```

### 5.2 关键函数对照表

| Python函数 | 位置 | TS函数名建议 |
|------------|------|--------------|
| `get_k_control_signals()` | debug_graph_analyzer.py:20 | `getKControlSignals()` |
| `parse_mismatch()` | vcd_waveform_analyzer.py:244 | `parseMismatch()` |
| `get_tabular()` | vcd_waveform_analyzer.py:264 | `getTabular()` |
| `tabular_via_dataframe()` | vcd_waveform_analyzer.py:95 | `generateWaveformTable()` |
| `waveform_trace_tool()` | waveform_trace_tool.py:63 | `waveformTraceTool()` |

---

## 六、测试用例

### 6.1 BFS回溯测试

```typescript
// 输入
const graph: ASTGraph = /* 加载 counter_ast_graph.json */;
const targetSignals = ['count'];
const k = 2;

// 期望输出
const expected = {
  controlSignals: new Map([
    ['count', [6, 6]],
    ['next_count', [10, 10]],
    ['reset', [4, 4]],
    ['clk', [3, 3]],
    ['enable', [5, 5]]
  ]),
  signalLevelTracer: [
    ['count->count'],
    ['next_count->count', 'reset->count', 'clk->count'],
    ['enable->next_count', 'count->next_count']
  ]
};
```

### 6.2 仿真输出解析测试

```typescript
// 输入
const testOutput = `
Mismatches: 2
First mismatch occurred at time 100. Output 'count' expected 0001, got 0000
First mismatch occurred at time 150. Output 'overflow' expected 1, got 0
`;

// 期望输出
const expected = {
  signals: ['count', 'overflow'],
  firstMismatchTime: 100
};
```

---

## 七、注意事项

1. **无第三方依赖要求**
   - BFS回溯和仿真解析完全可以用原生TS实现
   - VCD解析可以自己实现或找现有库

2. **性能考虑**
   - 图遍历使用Map而非Object，提高查找效率
   - VCD文件可能很大，考虑流式解析

3. **错误处理**
   - 文件不存在时返回友好错误信息
   - 信号不在图中时跳过而非报错

4. **兼容性**
   - 信号名可能包含方括号，如 `count[7:0]`
   - 时间单位统一为ns

---

## 八、交付物

1. `debugGraphAnalyzer.ts` - BFS回溯模块
2. `simulationParser.ts` - 仿真输出解析模块
3. `vcdParser.ts` - VCD波形解析模块
4. `waveformTraceTool.ts` - 工具整合封装
5. `types.ts` - 类型定义
6. 单元测试文件
