J-Link 下载与在线调试

本 skill 提供 J-Link 探针的设备探测、固件烧录、内存读写、寄存器查看、目标复位、RTT 日志读取，以及轻量在线调试和 GDB 源码级调试能力。

配置

环境级配置（skill/config.json）

skill 目录下的 config.json 包含环境级配置（工具路径、端口号等），首次使用前确认 exe 路径正确：

{
  "exe": "C:\\Program Files\\SEGGER\\JLink\\JLink.exe",
  "gdbserver_exe": "C:\\Program Files\\SEGGER\\JLink\\JLinkGDBServerCL.exe",
  "rtt_exe": "C:\\Program Files\\SEGGER\\JLink\\JLinkRTTClient.exe",
  "gdb_exe": "C:\\Program Files\\Arm\\GNU Toolchain mingw-w64-x86_64-arm-none-eabi\\bin\\arm-none-eabi-gdb.exe",
  "serial_no": "",
  "rtt_telnet_port": 0,
  "swo_command": [],
  "operation_mode": 1
}

• exe：JLink.exe 完整路径（必填）
• gdbserver_exe：JLinkGDBServerCL.exe 路径，RTT 和 GDB 调试需要
• rtt_exe：JLinkRTTClient.exe 路径
• gdb_exe：arm-none-eabi-gdb 路径，GDB 源码级调试需要
• serial_no：默认探针序列号，多探针场景下使用
• rtt_telnet_port：RTT 端口，0 表示使用工具默认值
• swo_command：可选，完整 SWO viewer 命令数组，供 jlink_swo.py 包装
• operation_mode：1 直接执行 / 2 输出风险摘要但不阻塞 / 3 执行前确认

工程级配置（.embeddedskills/config.json）

设备参数（device/interface/speed）统一在工作区的 .embeddedskills/config.json 中管理：

{
  "jlink": {
    "device": "STM32F407VG",
    "interface": "SWD",
    "speed": "4000"
  }
}

• device：芯片型号（如 STM32F407VG、GD32F470ZG）
• interface：调试接口，SWD 或 JTAG，默认 SWD
• speed：调试速率 kHz，默认 4000

参数解析优先级：CLI 显式参数 > .embeddedskills/config.json（工程级）> skill/config.json（环境级）> .embeddedskills/state.json > 默认值/报错

成功执行后，确认过的 device/interface/speed 会自动写回工程配置。

子命令

基础操作

子命令	用途	风险
info	探测探针与目标连通性	低
flash	烧录固件（.hex / .bin / .elf）	高
read-mem	读取内存区域	低
write-mem	写入内存	高
regs	查看 CPU 寄存器	低
reset	复位目标芯片	高
rtt	读取 RTT 日志输出	低
swo	包装外部 SWO viewer 为统一事件流	低

在线调试（JLink Commander）

子命令	用途	风险
halt	暂停 CPU，返回寄存器状态	低
go	恢复 CPU 运行	低
step	单步执行（支持指定步数），返回执行的指令和寄存器	低
run-to	设置断点并运行，等待命中后返回状态	低

GDB 源码级调试

子命令	用途	依赖
gdb backtrace/locals	查看调用栈和局部变量	arm-none-eabi-gdb
gdb break/continue/next/step/finish/until	one-shot 控制执行流	arm-none-eabi-gdb
gdb frame/print/watch/disassemble/threads/crash-report	one-shot 源码级诊断	arm-none-eabi-gdb

执行流程

1. 读取 skill/config.json，确认 exe 路径有效
2. 读取 .embeddedskills/config.json 获取工程级配置（device/interface/speed）
3. 读取 .embeddedskills/state.json 获取历史状态
4. 参数解析优先级：CLI 显式参数 > .embeddedskills/config.json（工程级）> skill/config.json（环境级）> .embeddedskills/state.json > 默认值/报错
5. 若当前动作需要 device 且仍为空，直接要求用户补充，绝不猜测
6. 多探针场景未指定 serial_no 时，列出探针让用户选择，不自动选择
7. 按 operation_mode 决定是否需要确认后执行
8. 使用模板生成临时 .jlink 命令文件，调用 JLink.exe 时带 -NoGui 1 -ExitOnError 1 -AutoConnect 1
9. 解析输出和返回码，返回结构化结果
10. 成功执行后，将确认过的 device/interface/speed 写回 .embeddedskills/config.json

脚本调用

skill 目录下有四个 Python 脚本，使用标准库实现，无额外依赖。

jlink_exec.py — 基础操作 + 轻量调试

# 探测连通性
python <skill-dir>/scripts/jlink_exec.py info --device GD32F470ZG --json

# 烧录固件
python <skill-dir>/scripts/jlink_exec.py flash --file build/app.hex --device GD32F470ZG --json

# 烧录 .bin（必须提供地址）
python <skill-dir>/scripts/jlink_exec.py flash --file build/app.bin --device GD32F470ZG --address 0x08000000 --json

# 读取内存
python <skill-dir>/scripts/jlink_exec.py read-mem --address 0x08000000 --length 256 --device GD32F470ZG --json

# 写入内存
python <skill-dir>/scripts/jlink_exec.py write-mem --address 0x20000000 --value 0x12345678 --device GD32F470ZG --json

# 查看寄存器
python <skill-dir>/scripts/jlink_exec.py regs --device GD32F470ZG --json

# 复位目标
python <skill-dir>/scripts/jlink_exec.py reset --device GD32F470ZG --json

# 暂停 CPU
python <skill-dir>/scripts/jlink_exec.py halt --device GD32F470ZG --json

# 恢复运行
python <skill-dir>/scripts/jlink_exec.py go --device GD32F470ZG --json

# 单步执行（3 步）
python <skill-dir>/scripts/jlink_exec.py step --device GD32F470ZG --count 3 --json

# 运行到断点地址
python <skill-dir>/scripts/jlink_exec.py run-to --device GD32F470ZG --address 0x08001234 --timeout-ms 3000 --json

通用可选参数：--interface SWD|JTAG、--speed 4000、--serial-no <序列号>、--exe <JLink.exe路径>

jlink_rtt.py — RTT 日志读取

python <skill-dir>/scripts/jlink_rtt.py --device GD32F470ZG --json

可选参数：--serial-no、--channel、--encoding、--rtt-port、--gdbserver-exe <路径>、--rtt-exe <路径>

RTT 工作原理：脚本先通过 JLinkGDBServerCL.exe 建立调试连接，再启动 JLinkRTTClient.exe 读取 RTT 数据。--json 模式输出 JSON Lines。

jlink_swo.py — SWO 事件流包装

# 使用 config.json 里的 swo_command
python <skill-dir>/scripts/jlink_swo.py --json

# 或显式传入 viewer 命令
python <skill-dir>/scripts/jlink_swo.py \
  --viewer-cmd JLinkSWOViewerCL.exe -device GD32F470ZG -itf SWD -speed 4000 \
  --json

jlink_swo.py 不直接实现 SWO 协议，而是把外部 viewer 的 stdout/stderr 统一包装成 JSON Lines，便于上层 workflow 或 AI 继续消费。

jlink_gdb.py — GDB 源码级调试（需要 arm-none-eabi-gdb）

# 执行自定义 GDB 命令序列
python <skill-dir>/scripts/jlink_gdb.py run \
  --gdbserver-exe <路径> --gdb-exe <arm-none-eabi-gdb路径> \
  --device GD32F470ZG --elf build/app.elf \
  --commands "break main" "continue" "backtrace" "info locals" --json

# 快捷：获取调用栈
python <skill-dir>/scripts/jlink_gdb.py backtrace \
  --gdbserver-exe <路径> --gdb-exe <路径> \
  --device GD32F470ZG --elf build/app.elf --json

# 快捷：查看局部变量
python <skill-dir>/scripts/jlink_gdb.py locals \
  --gdbserver-exe <路径> --gdb-exe <路径> \
  --device GD32F470ZG --elf build/app.elf --json

GDB 调试需要 ELF 文件才能进行源码级调试（断点到函数名、查看变量）。没有 ELF 时仍可使用地址级调试。

输出格式

所有脚本以 JSON 格式返回，基础字段为 status（ok/error）、action、summary、details，并可能附带 context、artifacts、metrics、state、next_actions、timing。流式观测命令使用 JSON Lines，并统一输出 source、channel_type、stream_type。

成功示例：

{
  "status": "ok",
  "action": "halt",
  "summary": "已暂停，PC=0x08049ABC",
  "details": {
    "device": "GD32F470ZG",
    "registers": { "PC": "0x08049ABC", "R0": "0x00000004", "..." : "..." }
  }
}

step 示例（包含执行的指令）：

{
  "status": "ok",
  "action": "step",
  "summary": "单步3次，PC=0x08049AB4",
  "details": {
    "steps": [
      { "address": "0x08049AB8", "opcode": "80 1B", "instruction": "SUBS R0, R0, R6" },
      { "address": "0x08049ABA", "opcode": "A8 42", "instruction": "CMP R0, R5" },
      { "address": "0x08049ABC", "opcode": "FA D3", "instruction": "BCC #-0x0C" }
    ],
    "registers": { "PC": "0x08049AB4", "..." : "..." }
  }
}

run-to 示例（断点命中）：

{
  "status": "ok",
  "action": "run-to",
  "summary": "断点命中 @ 0x08049AB4，PC=0x08049AB4",
  "details": {
    "bp_address": "0x08049AB4",
    "bp_hit": true,
    "registers": { "PC": "0x08049AB4", "..." : "..." }
  }
}

核心规则

• 不自动猜测 device 芯片型号，缺失时必须询问用户
• 多探针场景不自动选择探针，必须让用户指定序列号
• 参数解析优先级为：CLI 显式参数 > .embeddedskills/config.json（工程级）> skill/config.json（环境级）> .embeddedskills/state.json > 默认值/报错
• .bin 文件必须显式提供烧录地址，缺失时报错
• 连接失败时给出排查建议（检查连线、供电、接口类型、速度），不自动尝试更激进参数
• 烧录、写内存、复位在参数完整且用户意图明确时直接执行
• run-to 的断点在单次 JLink 会话内完成设置和清除，不存在跨会话 handle 问题
• 结果回显中始终包含目标芯片、接口类型和执行动作
• 产物路径（elf/file）不进入工程配置，仍只依赖 state.json
• last_flash/last_debug 等运行状态继续写入 state.json

调试典型工作流

快速排查（JLink Commander）

halt → regs → read-mem → step → go

适合查看当前执行位置、寄存器状态、内存值，无需 ELF 和 GDB。

断点调试（JLink Commander）

run-to(address) → regs → read-mem → go

在指定地址设置断点并等待命中，查看此时的状态。

源码级调试（GDB）

gdb run --elf app.elf --commands "break main" "continue" "backtrace" "info locals"

需要 ELF 文件和 arm-none-eabi-gdb，支持函数名断点和变量查看。

参考

遇到芯片型号问题时可查阅 references/common_devices.md。