vscode-jz-debug — VS Code 调试扩展

JZ8P 系列 OTP 微控制器的 VS Code 调试扩展，支持 JZ-IDE V2.0 仿真器和软件仿真。协议、烧录、寄存器读取和 DAP 服务由 Python 包 jz_debug 提供。

前置依赖

无需手动安装 Python 或 jz_debug。扩展激活时会自动完成运行环境准备：

自动检测系统 Python（>=3.10），创建扩展专属虚拟环境；
自动安装 jz_debug Python 包；
没有合适的系统 Python 时，自动下载并静默安装 Python 3.12.10；
运行环境位于 VS Code 扩展专属缓存目录，不修改系统 PATH。

首次启动调试时需要网络连接，用于下载 Python 或安装 Python 包。

安装

安装 VSIX

在 VS Code 中打开命令面板，执行：

扩展: 从 VSIX 安装...

选择 jz-debug-*.vsix 文件，然后重新加载 VS Code。

开发运行

cd vscode-jz-debug
npm install
npm run compile

按 F5 启动扩展开发宿主，或使用：

扩展: 从文件夹安装...

选择 vscode-jz-debug 目录。

开发模式下，如果扩展目录旁边存在仓库中的 jz_debug 目录，扩展会优先以 editable 模式安装本地源码。

使用

打开包含 .mpj 工程文件的工作区；
确认 program、listFile 和 sourceFile 指向同一工程；
按 F5，选择 JZ Hardware Debug 或 JZ Sim Debug；
首次启动时等待扩展自动准备 Python 环境。

硬件调试前请关闭 JZ-IDE，避免 USB 设备被其他程序占用。仿真器需要安装 libusbK 驱动，设备标识为 VID=8235、PID=584A。

launch.json 示例

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "jz-debug",
      "request": "launch",
      "name": "JZ Hardware Debug",
      "backend": "hardware",
      "program": "${workspaceFolder}/jzcheck_build/Main.xbin",
      "listFile": "${workspaceFolder}/jzcheck_build/Main.lst",
      "sourceFile": "${workspaceFolder}/Main.asm",
      "stopOnEntry": true
    }
  ]
}

功能

调试控制

烧录 .xbin；
Run / Pause / Step / Step Over / Reset；
源码行断点；
硬件仿真器固件版本输出；
启动前校验项目芯片和仿真上板型号。

变量查看

Variables 面板查看 CPU、通用寄存器和 I/O 寄存器；
Watch 支持寄存器、EQU 符号、字节和位表达式；
Inline Values 在源码变量旁显示灰色的实时值；
变量值复用已有调试数据，不额外产生 USB 读取请求。

断点限制

仿真器运行期间不能修改断点。此时 VS Code 会显示未验证断点，并提示：

运行中不能改断点，请先暂停

能力与限制

支持	限制
烧录、断点、Run/Pause/Step/Step Over/Reset	不支持写寄存器
PC、CPU、通用寄存器和 I/O 寄存器	不支持条件断点和数据断点
Watch 与 Inline Values	不支持调用栈展开
硬件仿真和软件仿真	硬件调试时 JZ-IDE 不能同时运行

设置项

配置项	说明
`backend`	`hardware` 使用 USB 仿真器，`sim` 使用软件仿真
`program`	`Main.xbin` 路径，必填
`listFile`	`Main.list` 路径，用于源码行映射
`sourceFile`	`.asm` 源文件路径
`stopOnEntry`	启动后是否停在入口，默认 `true`
`pollIntervalMs`	硬件轮询间隔，默认 50ms
`verifyProgram`	是否校验烧录结果，默认 `true`
`python`	可选，覆盖扩展自动准备的 Python
`repoRoot`	可选，指定 `jz_debug` 源码仓库根目录

自举运行目录

运行环境位于 VS Code 的 globalStorage 目录：

{globalStorage}/jz-assembly.jz-debug/jz-debug-runtime/
├── venv/
│   └── Scripts/python.exe
└── python/
    └── python.exe       # 仅在没有系统 Python 时创建

系统要求

VS Code ^1.80.0；
Windows 10 或更高版本；
硬件调试需要 JZ 仿真器和 libusbK 驱动。