# wiggle — AURIX DFlash 调试工具

> 基于 Infineon TAS Client API 的 AURIX TC2x / TC3x DFlash 调试器。
> **16 个 active 子命令**（v2.2 旧二进制，源码已瘦身到 4,113 行），全部支持 `--json` 结构化输出。
> 配套 MCP server（`D:\wiggle_MCP\aurix_mcp_server.py`）**当前注册 19 个 `@mcp.tool()`**（v2.6）
> ——其中 13 个 `wiggle_*`（不含 rewrite/restore/ucb/shell）+ 1 个 `wiggle_pflash` + 5 个 `build_/parse_/lookup_*`。
> 另有 6 个 wiggle 子命令（halt/go/cpu_reg/break/step/bt）+ 3 个 MCP 工具（wiggle_rewrite/restore/ucb）已从源码删除——旧二进制仍能用，重 build 后消失，详见 §5.4 + §9。

---

## 目录

1. [支持的芯片](#1-支持的芯片)
2. [环境要求](#2-环境要求)
3. [目录结构](#3-目录结构)
4. [快速开始](#4-快速开始)
5. [16 个子命令一览](#5-16-个子命令一览)
6. [使用示例](#6-使用示例)
7. [全局选项](#7-全局选项)
8. [JSON 输出模式](#8-json-输出模式)
9. [MCP Server 集成](#9-mcp-server-集成)
10. [设备配置 / 寄存器定义](#10-设备配置--寄存器定义)
11. [退出码](#11-退出码)
12. [许可证](#12-许可证)

---

## 1. 支持的芯片

| 家族 | 芯片 |
|------|------|
| **TC2x** | TC21x, TC22x, TC23x, TC26x, TC27x, TC29x |
| **TC3x** | TC33x, TC35x, TC36x, TC37x, TC38x, TC39x, TC3Ex |

> **不支持 TC4x 系列**（DFlash 基址 0xAE000000 / 0xAC000000 + erase 命令序列不同）。
> PFlash 整片烧写请用 `AURIXFlasher.exe`（不在本包内），或通过 MCP 的 `wiggle_pflash` 工具调用。

芯片型号通过 `DeviceConfigs/*.json` 在运行时加载，目前覆盖 21 个配置文件。
新芯片支持：往 `DeviceConfigs/` 加 JSON 即可，无需重新编译。

---

## 2. 环境要求

| 组件 | 最低版本 | 备注 |
|------|----------|------|
| OS | Windows 10/11 x64 | 静态链接，**无需 VC++ 运行库** |
| TAS Server | Infineon 任意受支持版本 | 后台进程，监听 TCP:2000，连 miniWiggler |
| miniWiggler | 驱动装好 | USB 接 PC，DAP/JTAG 接 AURIX |
| 磁盘 | ~430 MB | 8 个 RegisterDefs JSON 占 ~290 MB |

> Python 不是 wiggle.exe 运行所必需——只在你想跑 MCP server（`D:\wiggle_MCP\aurix_mcp_server.py`）时才需要 Python 3.10+。

---

## 3. 目录结构

```
D:\wiggle_MCP\wiggle\
├── wiggle.exe                            # 主程序（v2.2，静态链接 C++17）
├── README.md                             # 本文档
├── wiggle-Command-Reference.xlsx         # 子命令速查表（22 个子命令）
│
├── DeviceConfigs\                        # 设备配置（21 个 JSON）
│   ├── devices.json                      # 设备索引
│   ├── TC33x_A_step.json
│   ├── TC36x_A_step.json
│   └── ...                               # 其他芯片
│
└── RegisterDefs\                         # SVD 派生的寄存器定义（8 个 JSON）
    ├── TC23x-full.json
    ├── TC27x_D-step-full.json
    ├── TC29x_B-step-full.json
    ├── TC33x-full.json
    ├── TC36x_A-step-full.json
    ├── TC37x_A-step-full.json
    ├── TC38x_A-step-full.json
    └── TC39x_B-step-full.json
```

---

## 4. 快速开始

```bash
# ① 启动 Infineon TAS Server（miniWiggler 调试器后端）

# ② AURIX 板上电 + miniWiggler USB 插入

# ③ 烟雾测试：列出已连接目标
D:\wiggle_MCP\wiggle\wiggle.exe list

# ④ 看设备信息
D:\wiggle_MCP\wiggle\wiggle.exe info

# ⑤ 看 Flash 状态（自动 SVD 字段解码）
D:\wiggle_MCP\wiggle\wiggle.exe status
```

> wiggle.exe 默认自动查找 `DeviceConfigs/`（相对自身位置 + 环境变量 `TAS_DEVICE_CONFIGS`）。
> 找不到会报错并提示搜索路径，详见 §10。

---

## 5. 16 个子命令一览

### 5.1 设备信息（3 个）

| 命令 | 别名 | 功能 |
|------|------|------|
| `list` | `l` | 列出已连接的所有 TAS 目标 |
| `status` | - | 读 Flash 状态寄存器 + SVD 字段解码 |
| `info` | - | 设备信息、内存布局、SVD 概况 |

### 5.2 DFlash 操作（10 个）

| 命令 | 别名 | 功能 |
|------|------|------|
| `erase` | `e` | 擦除 DFlash sector（支持整片 / 部分 / dry-run）|
| `write` | `w` | 从 HEX/BIN 文件写入 DFlash |
| `read` | `r` | 读取 DFlash 区间（hex dump 或落盘）|
| `dump` | - | Hex dump 任意地址（PFlash/DFlash/SRAM 通用）|
| `poke` | - | 写一个值到地址 + readback 校验 |
| `reg` | - | 按 SVD 名字/地址读/写寄存器 |
| `compare` | - | 本地文件 vs Flash 内容比对 |
| `search` | - | 内存字节模式搜索 |
| `rewrite` | `rw` | Read-Modify-Write 任意地址（自动 sector 对齐）|
| `restore` | - | 擦+写+验 整片恢复 |

### 5.3 UCB（1 个，三动作合一）

| 命令 | 子动作 | 功能 |
|------|--------|------|
| `ucb` | `read` / `write` / `erase` | UCB 操作（**仅 TC3xx**，HIGH RISK 二次确认）|

### 5.4 控制（2 个）

| 命令 | 别名 | 功能 |
|------|------|------|
| `reset` | - | 复位 MCU（可选择 halt）|
| `shell` | - | 交互式 REPL（保留连接，命令循环）|

> **关于 CPU 调试控制命令**（halt / go / cpu_reg / break / step / bt）：
> 早期版本（v2.2 完整版）包含 6 个调试命令（halt/go/cpu_reg/break/step/bt + 6 个 doXxx 函数实现）。
> 出于"AI 误操作可能导致 CPU 状态损坏"的风险考虑，**v2.6 起这 6 个命令已从 wiggle 源代码中移除**。
>
> - ✅ 当前 **wiggle.exe（v2.2 旧二进制）** 仍含这 6 个命令（17-22 号子命令），**未重新编译**
> - ✅ 当前 **wiggle_main.cpp 源码**（4,113 行）已不含这 6 个 doXxx 函数
> - ❌ 下一次 `build.bat` 重新编译后，这 6 个命令将**永久消失**——届时 `wiggle halt` 等会报 `Unknown subcommand`
>
> 如果你的工作流依赖这些命令（halt 后再 break / step 调试），**请在重新编译 wiggle 前先确认**：
> 要么保留旧版二进制（不重 build），要么把源码恢复成 v2.5 / 完整版。
>
> 可恢复的源（已经独立 git 仓库在 `D:\workspace\tas-dflash_-erase\apps\wiggle\`）的 5,305 行版本就是含这 6 个 doXxx 的完整版。

---

## 6. 使用示例

### 6.1 设备信息

```bash
# 列出所有目标
wiggle list

# 看设备完整信息（JSON 模式便于 AI 解析）
wiggle info --json

# Flash 状态寄存器 + 字段解码
wiggle status --json
```

### 6.2 DFlash 擦除

```bash
# 擦单个 sector
wiggle erase --addr 0xAF000000 --sectors 1

# 整片擦并 backup
wiggle erase --all --backup backup.hex --verify

# dry-run：只显示设备信息不擦
wiggle erase --info
```

### 6.3 DFlash 写入

```bash
# 从 HEX 写入（地址在 HEX 文件内嵌）
wiggle write -f data.hex --verify

# 从 BIN 写入指定地址
wiggle write -f data.bin --addr 0xAF000000 --verify
```

### 6.4 DFlash 读取

```bash
# 读 4KB 落盘为 HEX
wiggle read --addr 0xAF000000 --length 0x1000 --output dump.hex

# 读 4KB 落盘为 BIN
wiggle read --addr 0xAF000000 --length 0x1000 --output dump.bin

# 不指定 -o 则打到 stdout（hex dump 格式）
wiggle read --addr 0xAF000000 --length 0x100
```

### 6.5 任意地址 Read-Modify-Write

```bash
# 改一个字节（0xAF000010 写 0xDE 0xAD 0xBE 0xEF），自动备份
wiggle rewrite --addr 0xAF000010 --data DEADBEEF --backup

# 改 8 字节 + 显式指定备份路径
wiggle rewrite --addr 0xAF000010 --data 0102030405060708 --backup my_backup.hex

# 从 HEX 文件 rewrite
wiggle rewrite -f patch.hex --verify
```

### 6.6 整片恢复

```bash
# 从备份 .bin 恢复（擦+写+验，verify 默认开启）
wiggle restore -f backup.bin

# 跳过 verify
wiggle restore -f backup.hex --no-verify
```

### 6.7 寄存器操作

```bash
# 按 SVD 名字读
wiggle reg DMU.HF.STATUS

# 按地址读
wiggle reg 0xF8040010

# 写
wiggle reg DMU.HF.STATUS 0x1234

# 列出外设所有寄存器
wiggle reg --list DMU
```

### 6.8 内存调试

```bash
# Hex dump 任意地址（PFlash/DFlash/SRAM 通用）
wiggle dump 0x70000000 0x40           # 64B dump
wiggle dump 0xA0000000 0x100 -o pflash.hex   # 落盘
wiggle dump 0x70000000 0x80 -o sram.bin      # 落 BIN

# 写内存
wiggle poke 0x70000000 0xDEADBEEF

# 搜内存
wiggle search 0xAF000000 0x20000 DEADBEEF
wiggle search 0xA0000000 0x100000 00FF00
```

### 6.9 UCB（仅 TC3xx，HIGH RISK）

```bash
# 读整段 UCB
wiggle ucb read

# 写 UCB（**HIGH RISK**：写错可能锁芯片！）
wiggle ucb write -f ucb_dump.bin

# 擦 UCB sector
wiggle ucb erase --addr 0xAF400200 --sectors 1
```

> ⚠️ **UCB 写 / 擦是 HIGH-RISK 操作**：wiggle 会要求键入 `yes` 二次确认。
> 锁定区（0xAF400800-0xAF400FFF / 0xAF401800-0xAF401FFF）wiggle **自动拒绝**。
> 写之前**必须**先 `wiggle ucb read > backup.bin` 备份。

### 6.10 调试会话（halt → 单步/断点 → go）

> ⚠️ **本节命令（halt/go/cpu_reg/break/step/bt）在 v2.6 起已从源码删除**——本节仅适用于**当前** `wiggle.exe` v2.2 旧二进制（未重 build）。
> 重新编译后这 6 个命令会消失，请参见 §5.4 的解释。

```bash

```bash
# 1. halt CPU（首选 BRKIN，不复位）
wiggle halt

# 2. 看 PC
wiggle cpu_reg PC

# 3. 设断点 + 跑过去
wiggle break add 0x80001234 --type instruction
wiggle break go 0x80001234 --timeout 5000
#    （自动设 BP + resume + 等待命中；命中后 CPU 停在断点处）

# 4. 单步
wiggle step

# 5. 读调用栈
wiggle bt

# 6. 恢复运行
wiggle go
```

### 6.11 shell REPL

```bash
wiggle shell
# 进入 REPL，所有子命令免前缀
# wiggle> halt
# wiggle> cpu_reg PC
# wiggle> step
# wiggle> go
# wiggle> quit
```

> Shell 模式**保持 TCP 连接**，所有子命令免重新 `initTool`——调试场景下快很多。

---

## 7. 全局选项

几乎所有子命令都支持：

| 选项 | 说明 |
|------|------|
| `--json` | 输出结构化 JSON（MCP / 脚本 / AI 解析用）|
| `--server <ip>` | TAS Server IP（默认 `localhost`）|
| `--target <id>` | 目标标识符（多目标时指定；默认首个）|
| `--device <name>` | 设备名覆盖（跳过 JTAG ID 自动检测，如 `TC27x`）|
| `--config-dir <path>` | 显式指定 DeviceConfigs 目录 |
| `--hot` | 用 HOT_ATTACH（不复位 MCU；用于调试命令）|

子命令级选项详见 `wiggle <subcommand> --help`：

```bash
wiggle erase --help
wiggle write --help
wiggle reg --help
# ... 全部 22 个子命令都支持 --help
```

---

## 8. JSON 输出模式

加 `--json` 让 wiggle 输出结构化 JSON，**所有 22 个子命令都支持**：

```bash
wiggle status --json
```

输出示例：

```json
{
  "status": "ok",
  "command": "status",
  "register": "DMU.HF.STATUS",
  "address": "0xF8040010",
  "value": "0x00000000",
  "fields": {
    "D0BUSY": 0,
    "D1BUSY": 0,
    "P0BUSY": 0
  },
  "error_register": "DMU.HF.ERRSR",
  "error_fields": {}
}
```

读寄存器时，SVD 字段会全部展开（位域、enum 描述）：

```json
{
  "status": "ok",
  "command": "reg",
  "action": "read",
  "register": "DMU.HF.STATUS",
  "address": "0xF8040010",
  "value": "0x00000001",
  "access": "read-only",
  "fields": {
    "D0BUSY":  {"value": 1, "lsb": 0,  "msb": 0},
    "D1BUSY":  {"value": 0, "lsb": 1,  "msb": 1},
    "P0BUSY":  {"value": 0, "lsb": 2,  "msb": 2},
    "DFSIZE":  {"value": 0, "lsb": 11, "msb": 12, "desc": "Data Flash size"},
    "ERR":     {"value": 0, "lsb": 16, "msb": 16, "desc": "Flash error flag"}
  }
}
```

写寄存器时返回 readback：

```json
{
  "status": "ok",
  "action": "write",
  "address": "0xF8040010",
  "value": "0x1234",
  "readback": "0x00001234",
  "verified": true
}
```

错误也走 JSON：

```json
{
  "status": "error",
  "code": 2,
  "message": "TAS server not reachable at localhost:2000"
}
```

---

## 9. MCP Server 集成

wiggle 的 16 个子命令中，**13 个**通过 MCP server（`D:\wiggle_MCP\aurix_mcp_server.py`）暴露给 AI 客户端；**3 个调试 + 1 shell + 3 个已删的（rewrite/restore/ucb）**不暴露。

> 完整 MCP 工具清单（**当前 19 个 active + 3 个 deprecated**，含 build / parse / lookup 5 个非 wiggle 工具）见
> `D:\wiggle_MCP\docs\MCP-Command-Reference.xlsx`
> 和根 `D:\wiggle_MCP\README.md` 第 8-9 节。

### MCP 工具 vs wiggle 子命令对照（当前 19 个 active）

| MCP Tool | wiggle 子命令 | 备注 |
|----------|---------------|------|
| `wiggle_list` | `list --json` | |
| `wiggle_status` | `status --json` | |
| `wiggle_info` | `info --json` | |
| `wiggle_erase` | `erase ... --json` | |
| `wiggle_write` | `write ... --json` | |
| `wiggle_read` | `read ... --json` | |
| `wiggle_dump` | `dump ... --json` | |
| `wiggle_poke` | `poke ... --json` | |
| `wiggle_reg` | `reg ... --json` | |
| `wiggle_compare` | `compare ... --json` | |
| `wiggle_search` | `search ... --json` | |
| `wiggle_reset` | `reset --json` | |
| `wiggle_pflash` | **不走 wiggle** | 调 `AURIXFlasher.exe` |
| `build_project` | — | 纯 Python 解析 |
| `reload_parsers` | — | 纯 Python |
| `parse_symbols` | — | 解析 MAP / LST |
| `parse_elf` | — | 解析 ELF |
| `lookup_symbol` | — | 符号查地址 |
| `lookup_address` | — | 地址查符号 |

### ❌ 不暴露的（6+3+1 = 10 个）

| 来源 | 子命令 | 原因 |
|------|--------|------|
| 已从 wiggle 源码删除（6 个） | `halt` / `go` / `cpu_reg` / `break` / `step` / `bt` | AI 误操作 CPU 状态损坏风险高 |
| 已从 MCP server 删除（3 个） | `wiggle_rewrite` / `wiggle_restore` / `wiggle_ucb` | MCP wrapper 移除，**wiggle CLI 仍可用**——AI 可用 `mcp_bash` 之类直接调 wiggle.exe |
| 设计上不暴露 | `shell` | REPL 内部用，AI 进 REPL 容易卡住 |

### `mcp_config.json` 配置

```json
{
  "wiggle_exe":         "D:\\wiggle_MCP\\wiggle\\wiggle.exe",
  "aurix_flasher_exe":  null,
  "server":             "localhost",
  "target":             null,
  "device":             null,
  "timeout":            120
}
```

- `wiggle_exe` 默认自动搜；显式设置可省启动时间。
- `aurix_flasher_exe` 默认自动搜（详见 `D:\wiggle_MCP\README.md` §2.6）。
- `timeout` 默认 120 秒（`wiggle_pflash` 固定 300 秒）。

### 启动 MCP Server

```bash
# stdio 模式（Claude / Cursor / Qoder 默认）
python D:\wiggle_MCP\aurix_mcp_server.py --config D:\wiggle_MCP\mcp_config.json

# SSE 远程模式
python D:\wiggle_MCP\aurix_mcp_server.py --config D:\wiggle_MCP\mcp_config.json --transport sse --port 8000
```

---

## 10. 设备配置 / 寄存器定义

### 10.1 设备配置（`DeviceConfigs/`）

每个芯片一个 JSON，含：DFlash 基址、扇区大小、页大小、JTAG ID、UCB 配置等。

**搜索路径**（按优先级）：

1. `--config-dir <path>` 显式指定
2. 环境变量 `TAS_DEVICE_CONFIGS`
3. `wiggle.exe` 同级目录下的 `DeviceConfigs/`
4. `wiggle.exe` 同级的 `../data/DeviceConfigs/`（开发布局）
5. `wiggle.exe` 同级的 `../../../data/DeviceConfigs/`（build 布局）
6. 当前工作目录下的 `DeviceConfigs/`

> 找不到时 wiggle 报错并提示搜索路径，不会 fallback 到空。

### 10.2 寄存器定义（`RegisterDefs/`）

从 Infineon 公开的 SVD 文件（`D:\wiggle_MCP\data\SVD\*.svd`）派生，供 `reg` 命令按名字查寄存器地址。

- 单个文件 19-65 MB，**只在你用 `reg <name>` 时才需要**。
- 用 `--addr` 走数字地址访问寄存器时不需要 RegisterDefs。
- 重新生成方式见 `D:\wiggle_MCP\README.md` §15。

> 加载失败 `reg` 会用硬编码 fallback（TC3x `DMU.HF.STATUS` / TC2x `FSR`），不影响 status / info 命令。

---

## 11. 退出码

所有子命令退出时返回统一退出码，方便脚本/agent 解析：

| Code | 含义 |
|------|------|
| 0 | OK |
| 1 | Usage error（参数错）|
| 2 | Server error（TAS Server 连不上）|
| 3 | Target error（目标列表为空）|
| 5 | Session error |
| 6 | Connect error（设备连不上）|
| 7 | Device error（芯片未支持 / 未识别）|
| 11 | Flash status error（清状态失败）|
| 12 | Erase command error |
| 14 | Erase timeout |
| 15 | Erase error flags（OPER / SQER / PROER / PVER / EVER 之一置位）|
| 16 | Flash reset to read mode 失败 |
| 17 | Verify error（擦后回读 != 0x00）|
| 18 | I/O error（文件读写失败）|
| 19 | Write page command error |
| 20 | Write verify error |
| 21 | HEX parse error |
| 22 | Compare mismatch（wiggle_compare 找到不匹配）|
| 23 | Search not found（wiggle_search 无命中）|

---

## 12. 许可证

Apache License 2.0
