# DACtester

**Repository Path**: cmx1998/dactester

## Basic Information

- **Project Name**: DACtester
- **Description**: DACtester 是一款**专为非技术用户设计**的自动化测试工具，用于验证 FPGA 设计中的 WAV→PCM→DAC 数据通路。  
通过**容器化部署 + Web 图形界面**，用户只需点击几下鼠标，即可完成从音频文件上传、仿真运行、波形对比到问题定位的全流程，彻底告别命令行和手工排查。
- **Primary Language**: Go
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-23
- **Last Updated**: 2026-06-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DACtester - FPGA DAC 驱动自动化验证工具

DACtester 是一款**专为非技术用户设计**的自动化测试工具，用于验证 FPGA 设计中的 WAV→PCM→DAC 数据通路。  
通过**容器化部署 + Web 图形界面**，用户只需点击几下鼠标，即可完成从音频文件上传、仿真运行、波形对比到问题定位的全流程，彻底告别命令行和手工排查。

---

## 功能特性

### 1. 纯软件仿真（核心）
- 📤 **一键上传 WAV**：自动解析 16-bit PCM WAV 文件头，提取音频样本作为仿真激励。
- 🔄 **自动化仿真**：集成开源 Verilog 仿真器 [Icarus Verilog](http://iverilog.icarus.com/)，自动编译并运行用户提供的 FPGA 设计及 Testbench。激励数据通过生成 Verilog 头文件的方式内嵌，彻底解决文件路径依赖问题。
- 📊 **图形化波形对比**：前端使用 Canvas 并列绘制 **“预期波形”（音频源）** 与 **“实际仿真波形”（DAC 输入）**。差异点自动用红色标记，帮助快速定位逻辑错误。
- 🎯 **智能诊断**：仿真完成后自动显示 PASS/FAIL 状态，并提示首个错误发生的位置。

### 2. 硬件回环测试（硬件诊断）
- 🧪 **串口回环**：通过串口向 FPGA 板卡发送 256 字节递增测试序列（`0x00`~`0xFF`），验证 FPGA 是否能将数据原样返回。用于排查物理连接和基础通信故障。
- 🚀 **自动串口扫描**：优先使用 `go.bug.st/serial` 库扫描系统串口。若扫描失败，自动降级为 Windows 注册表方案，并支持手动输入端口号。

### 3. SD 卡扇区读测试（已集成，需 FPGA 配合）
- 💾 **指定扇区读取**：通过串口发送自定义读命令（`0xBB` + 4字节扇区地址 + 填充），从 FPGA 连接的 SD 卡中读取任意扇区数据。
- 📋 **十六进制数据展示**：返回的数据以十六进制格式分行显示，便于直接观察和导出。

### 4. 部署方式
- 🐳 **Docker 容器化**：所有依赖（仿真器、Go 后端）打包为单一 Docker 镜像，一键运行。
- ⚡ **Windows 原生程序**：可编译为单个 `.exe` 文件，双击运行，硬件串口测试更稳定。

---

## 系统架构

```
┌────────────────────────────────────────────────────┐
│                    用户浏览器                        │
│          (Web 前端: 文件上传、波形展示)               │
└────────────────────┬───────────────────────────────┘
                     │ HTTP
┌────────────────────▼───────────────────────────────┐
│                Go 后端服务 (容器内)                   │
│  ┌─────────────────────────────────────────────┐   │
│  │  路由层: gin                                  │   │
│  ├─────────────────────────────────────────────┤   │
│  │  业务逻辑:                                    │   │
│  │    - WAV 解析 / 测试向量生成                    │   │
│  │    - 仿真调度 (调用 iverilog + vvp)             │   │
│  │    - 仿真日志解析与对比 (替代 VCD)               │   │
│  │    - 串口通信 (回环测试 / SD 读)                 │   │
│  ├─────────────────────────────────────────────┤   │
│  │  数据层: 文件存储, 内存缓存                     │   │
│  └─────────────────────────────────────────────┘   │
└────────────────────┬───────────────────────────────┘
                     │ 命令行调用
┌────────────────────▼───────────────────────────────┐
│           Icarus Verilog 仿真引擎 (容器内)            │
│  - 编译 Verilog 设计 + Testbench                     │
│  - 生成仿真运行日志                                  │
└────────────────────────────────────────────────────┘
```

**关键数据流**:
1. 用户上传 WAV 文件和 Verilog 源码。
2. 后端解析 WAV 文件，生成包含激励数据的 Verilog 头文件 (`stim_data.v`)。
3. 后端调用 Icarus Verilog 编译并运行仿真。
4. Testbench 将每个采样点的数据和时间写入 `pcm_log.txt`。
5. 后端解析日志文件，得到实际的 DUT 输入数据。
6. 后端将预期波形与实际波形进行对齐和对比。
7. 前端获取两组 JSON 波形数据，使用 Canvas 进行并列渲染，差异自动标红。

---

## 技术栈

| 层级 | 技术选型 | 说明 |
|------|----------|------|
| **后端** | Go 1.21+, gin, encoding/binary | 高性能、单二进制部署，易于调用外部仿真器 |
| **前端** | HTML5, JavaScript, Canvas API | 轻量级，通过 `go:embed` 嵌入 Go 二进制，无外部依赖 |
| **仿真引擎** | Icarus Verilog (iverilog + vvp) | 开源、跨平台，命令行友好 |
| **串口通信** | `go.bug.st/serial` + Windows 注册表 API | 跨平台串口库 + 专用后备方案 |
| **容器化** | Docker, Alpine 3.18 | 多阶段构建，最终镜像仅包含运行时环境 |

---

## 目录结构

```
dactester/
├── cmd/
│   └── server/          # 后端主入口
│       ├── main.go
│       └── static/      # 前端静态文件 (CSS, JS, HTML)
├── internal/
│   ├── handler/         # HTTP 路由处理 (api.go)
│   ├── simulator/       # 仿真调用封装 (iverilog.go)
│   ├── parser/          # WAV/VCD/日志解析 (vcd.go, ...)
│   ├── wav/             # WAV 文件解析 (parser.go)
│   └── serial/          # 硬件串口测试 (loopback.go)
├── Dockerfile           # Docker 多阶段构建文件
├── go.mod
└── README.md
```

---

## 快速开始

### 方式一：Docker 部署 (推荐用于软件仿真)

1.  **构建镜像**
    ```bash
    docker build -t dactester:latest .
    ```

2.  **运行容器**
    ```bash
    docker run -d -p 8080:8080 --name dactester dactester
    ```

3.  **访问界面**
    打开浏览器访问 `http://localhost:8080`。

### 方式二：Windows 原生运行 (推荐用于硬件测试)

1.  **编译**
    ```powershell
    go build -o dactester.exe ./cmd/server
    ```

2.  **运行**
    双击 `dactester.exe`，或在 PowerShell 中执行：
    ```powershell
    .\dactester.exe
    ```

3.  **访问**
    浏览器会自动打开 `http://localhost:8080`。

---

## 使用指南

### 1. 软件仿真测试
1.  准备一个 **16-bit PCM** 格式的 `.wav` 文件（单/双声道均可）。
2.  准备待测的 Verilog 设计文件 (`.v`) 和对应的 Testbench 文件 (`.v`)。
    > **Testbench 编写要求**：必须使用 `$fwrite` 和 `$fflush` 将激励信号（如 `pcm_data`）的值按 `<时间> <数值>` 的格式写入 `pcm_log.txt` 文件。具体可参考示例文件。
3.  在页面上分别选择这三个文件，点击 **“开始测试”**。
4.  等待几秒，页面将展示预期与实际波形的对比图。
    - ✅ **绿色** 提示表示仿真数据与音频源完全匹配。
    - ❌ **红色** 标记表示在对应位置发现了差异。

### 2. 硬件回环测试
1.  确保 FPGA 已烧录 **回环固件**（收到串口数据后立即原样返回）。
2.  在页面的 “硬件回环测试” 区域，选择或输入正确的 **串口号** (e.g., `COM3`) 和 **波特率** (e.g., `115200`)。
3.  点击 **“开始硬件测试”**，系统将发送 256 个测试字节并等待回环。
4.  如果数据完全一致，提示 “回环测试通过”。否则，会列出所有不匹配的位置。

### 3. SD 卡扇区读测试
1.  确保 FPGA 已烧录 **支持命令解析的固件**（支持 `0xBB` 读命令）。
2.  在 “SD 卡读测试” 区域，输入串口号、波特率和目标 **扇区地址** (e.g., `8192`)。
3.  点击 **“读取扇区”**。成功时，下方的文本框会显示从 FPGA 返回的 512 字节数据。

---

## 配置文件 (可选)

在可执行文件同目录下创建 `config.yaml` 可以覆盖默认设置：
```yaml
server:
  port: 8080
simulator:
  iverilog_path: /usr/bin/iverilog
  timeout: 30s
serial:
  port: COM3
  baud: 115200
```

---

## 常见问题

**Q: 软件仿真波形为空或全为 0？**
A: 请检查 Testbench 是否按要求将数据正确写入了 `pcm_log.txt` 文件。同时，确保 WAV 文件为 16-bit PCM 格式。

**Q: 硬件测试提示 “打开串口失败” 或 “无可用串口”？**
A: 请确认 FPGA 板卡已连接且驱动安装正确。若自动扫描失败，可以手动输入端口号（如 `COM3`）。**Docker 用户请注意**：硬件测试强烈建议使用 Windows 原生程序，因为 Docker 容器默认无法直接访问主机串口。

**Q: 为什么仿真时间很长？**
A: 程序会自动限制最多使用 **1024 个采样点** 进行仿真，避免因音频文件过大导致超时。

**Q: 能否使用其他仿真器？**
A: 可以。本项目采用模块化设计，只需实现 `simulator.Simulator` 接口即可。欢迎贡献 Verilator 驱动。

---

## 后续扩展计划

- [ ] 支持 Verilator 后端，提供更快的仿真速度
- [ ] 增加更多音频格式支持 (FLAC, MP3)
- [ ] 集成 Sigrok 实现硬件逻辑分析仪图形界面
- [ ] 提供 Wails 桌面版，无需 Docker 即可运行
- [ ] 自动生成 Testbench 骨架

---

## 许可证
本项目采用 **[木兰宽松许可证，第2版 (MulanPSL-2.0)](http://license.coscl.org.cn/MulanPSL2)**。  
依赖的第三方软件（如 Icarus Verilog）遵循其各自的许可证条款。

---

## 致谢

- [Icarus Verilog](http://iverilog.icarus.com/) - 强大的开源 Verilog 仿真器
- [gin](https://gin-gonic.com/) - Go 语言高性能 Web 框架
- [go.bug.st/serial](https://github.com/bugst/go-serial) - 跨平台串口通信库