Metadata-Version: 2.4
Name: jz_debug
Version: 0.1.0
Summary: JZ emulator debug core (USB / flash / DAP)
Author: jz-assembly contributors
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Debuggers
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pyusb>=1.2.1
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"

# jz_debug — JZ 仿真器调试核心

Python 包：USB 协议 / 烧录 / 调试会话 / DAP（VS Code）。

## 环境

- Python 3.10+
- `pip install -r requirements-jz-debug.txt`
- Windows：需 libusbK 驱动（JZ-IDE INF，VID=0x8235 PID=0x584A）

## 与 JZ-IDE 互斥

**同一时刻只能有一个程序占用仿真器。** 使用本工具前请关闭 JZ-IDE；用完后关闭本工具再开 IDE。

## 离线测试（无需硬件）

```bat
python -m jz_debug.tools.extract_fixtures
python -m pytest jz_debug/tests -q
```

## 实机冒烟

```bat
python -m jz_debug.tools.smoke_usb
```

应打印：`EV1.6.3-250609`

## 命令行烧录

```bat
python -m jz_debug.tools.program codes\V2_0_0_20260525_JZ8P1520\Main.xbin
```

## 调试 REPL

```bat
python -m jz_debug.tools.debug_repl --sim --xbin codes\V2_0_0_20260525_JZ8P1520\Main.xbin --list codes\V2_0_0_20260525_JZ8P1520\Main.list
python -m jz_debug.tools.debug_repl --xbin codes\...\Main.xbin
```

## DAP（VS Code）

```bat
python -m jz_debug.dap
```

扩展见 `vscode-jz-debug/`。

## 模块

| 包 | 说明 |
|----|------|
| `protocol/` | 纯协议，零 I/O |
| `usb/` | pyusb 设备 |
| `flash/` | 镜像 + 烧录状态机 |
| `session/` | HardwareBackend / SimBackend |
| `symbols/` | list 行映射 |
| `dap/` | Debug Adapter |
