WJ2350 Tools VSCode 扩展使用说明

当前版本：0.1.21。适用于本地 Windows VSCode，需信任工作区。安装包包含 32 位 Python 后端、dll_test.dll、Flash 算法和加密工具，不需要使用者安装 Python；设备驱动需自行安装。GDB 调试另外需要 Cortex-Debug 和 RISC-V GDB。

安装与打开

在扩展面板菜单选择“从 VSIX 安装”，选择 dist/wj2350-tools-0.1.21.vsix，按 VSCode 提示重新加载窗口。左侧 WJ2350 功能列表和页面标签顺序一致：读写、加密、EFUSE、串口。点击任一入口切换对应页面。0.1.21 调整了单选、焦点及初始化消息同步，防止旧消息覆盖新选择。

四页下方共用文件、下载选项、设备控制和日志。以加密页高度为基准，其他页放不下时统一增高；页面内容无独立滚动条，窗口不足时滚动整体界面。文本输出框自身仍可滚动。

连接、控制与下载

Speed 支持 20 / 100 / 400 / 750 kHz，默认 750。连接按钮切换为断开连接，尺寸不变、颜色不同。
手动连接不主动复位；断开手动连接保持目标当前状态。
核号下拉选择后立即生效。暂停、指令单步、运行针对选中核；共享 SMT halt 的硬件行为仍适用。
读取状态遍历 CPU0–7，将状态写入运行日志，然后恢复选核。dbg_get_run 表示已从复位释放，不代表正在运行。
全核 Reset Run 沿用已有全核复位暂停、运行流程。
文件区选择固件 BIN/ELF/HEX；Flash 算法留空使用内置算法。
BIN 需要手动填写下载地址。ELF/HEX 自动解析最低加载地址并锁定，不使用入口 PC 作为下载地址；后端保持原始段地址。
0x10000000–0x11FFFFFF 自动识别为 Flash，其他地址沿用 RAM 下载流程。混合 Flash/非 Flash 段、跨 Flash 边界报错。
下载并校验会暂停目标，不自动运行。

32 位读写

读取地址和写入地址分开。地址必须 4 字节对齐，地址和数据支持十进制或 0x 十六进制。读取数量为 1–256 word，默认 4。结果每行四个 32 位值，表头为 +0 / +4 / +8 / +C（字节偏移），行地址后有冒号。每次写入一个 word，数据范围 0–0xFFFFFFFF。读写结果显示在专用区域，操作记录进入日志。

加密

选择原始 BIN、加密输出 BIN、Blob 输出 BIN，可选择追加配置文件。输入输出文件不能相同。配置 KEK（4 word）、BlobData（32 word）、Mask、Shift、mask/crc/fig 使能、Image addr 和 Context（0–3）。 Image addr 至少为 0x10002000、按 1KB 对齐且位于所选 Context 范围内；原始固件至少 0x1000 字节。Shift 范围 0–255。使用内置 fig_encrypt_cli.exe 本机处理，无需连接芯片，分别输出固件密文与 Blob 文件。可选追加配置沿用原上位机的 blob_append 格式，参见项目根目录 BLOB_APPEND.md。

“导入 JSON / 导出 JSON”使用原上位机的字段：kek、blobdata32、key_mask、mask_shift、mask_en、crc_en、fig_en、image_addr、ctx_index。JSON 可能包含密钥，请按密钥文件管理。普通“保存参数”不保存这些密钥。

EFUSE

必须先连接芯片。每次读写操作前调用已有控制器初始化和配置，通过 DLL 内存接口访问。

读取：先读取控制位；受读保护的 word 跳过读取，显示 XXXXXXXX。
结果含 word0–15，每行四个 32 位十六进制值；+0 / +1 / +2 / +3 表示 word 序号偏移。
普通写入仅允许 word0–13，每次一个 word，数据范围 0–0xFFFFFFFF。
“EFUSE 生效”向 word14 写入固定值 0x55AA6699。
“写入控制位”操作 word15：bit0–14 为编程保护，bit16–30 为读保护，分别对应 word0–14。两种掩码范围均为 0–0x7FFF，置位即生效。
写入失败不会自动重试。GDB 调试会话占用时禁止手动 EFUSE 操作。

串口

支持端口刷新、常用波特率、数据位 5–8、校验 N/E/O/M/S、停止位 1/1.5/2，默认 115200、8N1、无流控。监控显示原始 TX/RX，支持 ASCII/HEX 切换、暂停显示、清空、保存和字节计数，时间戳在行尾。接收分包拼接后按实际 LF/CRLF 换行；ASCII 隐藏不可显示的控制字节。手动发送支持多行 ASCII/HEX，切换时转换数据格式；HEX 每字节两位，ASCII 可追加 CRLF。 YMODEM 支持单个 BIN 文件、进度与取消。传输期间独占串口，仍记录 TX/RX，不能同时手动发送。普通监听异常最多自动重连三次；发送失败不自动重发。监控历史有界，高流量可能丢弃事件，不作为无损抓包。

GDB 调试

手动芯片连接与 GDB Server 监听可以共存；实际 GDB 客户端接管期间禁用手动芯片操作，串口仍独立可用。页面和左侧 GDB 启停入口同步状态。停止 GDB Server 不等于停止整个后端，不会因此关闭串口。 “启动所选 VSCode 调试配置”使用项目已有 launch.json，不自动生成或修改它。GDB 可执行文件由其中的 gdbPath 配置。

{
  "version": "0.2.0",
  "configurations": [{
    "name": "WJ2350 Debug",
    "type": "cortex-debug",
    "request": "launch",
    "servertype": "external",
    "cwd": "${workspaceFolder}",
    "executable": "${workspaceFolder}/output/firmware.elf",
    "gdbPath": "D:/riscv_gcc/bin/riscv-none-elf-gdb.exe",
    "gdbTarget": "127.0.0.1:8000",
    "runToEntryPoint": "main"
  }]
}

将示例中的 ELF 和 GDB 路径替换为本机路径，gdbTarget 端口与页面一致。调试模式提供 Common 多核与 AMP 自动绑定，沿用原服务器行为。扩展化未改变代码搬移覆盖 RAM 软件断点等硬件/固件限制。

日志与生命周期

运行日志位于最底部，最多保留 1000 条。支持自动滚动、清空、搜索、上一个/下一个匹配和保存 TXT；Enter 查找下一个，Shift+Enter 查找上一个。保存的是当前保留的日志。串口监控与运行日志分开。侧栏“查看后端日志”打开 VSCode Output。关闭页面不会停止后端；命令面板的停止后端命令或扩展停用会关闭串口并停止 Server。正常主动停止不会作为退出错误显示。

保存参数的实际范围

当前使用 VSCode workspaceState，按项目/工作区隔离，不是用户 settings.json。不同项目窗口不共享；当前也没有“用户设置/工作区设置”范围选择功能。保存项：Speed、核号、固件路径、下载地址及目标、算法路径、GDB 端口及模式、串口端口/波特率/数据位/校验/停止位、YMODEM 文件路径。不保存：连接/运行状态、日志、读写地址和数据、EFUSE 待写值与保护掩码、手动发送内容、加密参数。加密参数请使用 JSON 导出。恢复参数不会自动连接、写入或下载。ELF/HEX 地址恢复时仍重新解析。

生成安装包

在项目根目录 PowerShell 执行：

Set-Location F:\2350\tools
.\build_vsix.ps1 -Version 0.1.21

输出 F:\2350\tools\dist\wj2350-tools-0.1.21.vsix。详细依赖、安装与验证命令见项目根目录《VSCode插件打包与运行.md》。

WJ2350 Tools

wj2350-local