jlink

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

J-Link 下载与在线调试

J-Link Download and Online Debugging

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

This skill provides capabilities for J-Link probe including device detection, firmware flashing, memory read/write, register viewing, target reset, RTT log reading, lightweight online debugging, and GDB source-level debugging.

配置

Configuration

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

Environment-level Configuration (skill/config.json)

skill 目录下的

config.json

包含环境级配置（工具路径、端口号等），首次使用前确认

exe

路径正确：

json

{
  "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
```
执行前确认

The

config.json

in the skill directory contains environment-level configurations (tool paths, port numbers, etc.). Before first use, confirm the

exe

path is correct:

json

{
  "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
```
: Full path to JLink.exe (required)
```
gdbserver_exe
```
: Path to JLinkGDBServerCL.exe, required for RTT and GDB debugging
```
rtt_exe
```
: Path to JLinkRTTClient.exe
```
gdb_exe
```
: Path to arm-none-eabi-gdb, required for GDB source-level debugging
```
serial_no
```
: Default probe serial number, used in multi-probe scenarios
```
rtt_telnet_port
```
: RTT port, 0 means using the tool's default value
```
swo_command
```
: Optional, complete SWO viewer command array, wrapped by
```
jlink_swo.py
```
```
operation_mode
```
:
```
1
```
Execute directly /
```
2
```
Output risk summary without blocking /
```
3
```
Confirm before execution

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

Project-level Configuration (.embeddedskills/config.json)

设备参数（device/interface/speed）统一在工作区的

.embeddedskills/config.json

中管理：

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 会自动写回工程配置。

Device parameters (device/interface/speed) are uniformly managed in

.embeddedskills/config.json

of the workspace:

json

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

```
device
```
: Chip model (e.g., STM32F407VG, GD32F470ZG)
```
interface
```
: Debug interface, SWD or JTAG, default is SWD
```
speed
```
: Debug speed in kHz, default is 4000

Parameter parsing priority: CLI explicit parameters >
.embeddedskills/config.json
(project-level) >
skill/config.json
(environment-level) >
.embeddedskills/state.json
> default value/error

After successful execution, the confirmed device/interface/speed will be automatically written back to the project configuration.

子命令

Subcommands

基础操作

Basic Operations

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

Subcommand	Purpose	Risk
`info`	Detect probe and target connectivity	Low
`flash`	Flash firmware (.hex / .bin / .elf)	High
`read-mem`	Read memory area	Low
`write-mem`	Write to memory	High
`regs`	View CPU registers	Low
`reset`	Reset target chip	High
`rtt`	Read RTT log output	Low
`swo`	Wrap external SWO viewer into a unified event stream	Low

在线调试（JLink Commander）

Online Debugging (JLink Commander)

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

Subcommand	Purpose	Risk
`halt`	Pause CPU, return register status	Low
`go`	Resume CPU operation	Low
`step`	Step execution (supports specifying step count), return executed instructions and registers	Low
`run-to`	Set breakpoint and run, return status after hitting	Low

GDB 源码级调试

GDB Source-level Debugging

子命令	用途	依赖
`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

Subcommand	Purpose	Dependencies
`gdb backtrace/locals`	View call stack and local variables	arm-none-eabi-gdb
`gdb break/continue/next/step/finish/until`	One-shot execution flow control	arm-none-eabi-gdb
`gdb frame/print/watch/disassemble/threads/crash-report`	One-shot source-level diagnosis	arm-none-eabi-gdb

执行流程

Execution Flow

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

Read
```
skill/config.json
```
, confirm the
```
exe
```
path is valid
Read
```
.embeddedskills/config.json
```
to get project-level configurations (device/interface/speed)
Read
```
.embeddedskills/state.json
```
to get historical status
Parameter parsing priority: CLI explicit parameters >
.embeddedskills/config.json
(project-level) >
skill/config.json
(environment-level) >
.embeddedskills/state.json
> default value/error
If the current action requires
```
device
```
and it is still empty, directly ask the user to supplement it, never guess
When
```
serial_no
```
is not specified in multi-probe scenarios, list the probes for the user to select, do not select automatically
Decide whether to confirm before execution according to
```
operation_mode
```
Generate a temporary
```
.jlink
```
command file using templates, and call JLink.exe with
```
-NoGui 1 -ExitOnError 1 -AutoConnect 1
```
Parse output and return code, return structured results
After successful execution, write the confirmed device/interface/speed back to
```
.embeddedskills/config.json
```

脚本调用

Script Invocation

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

There are four Python scripts in the skill directory, implemented using standard libraries with no additional dependencies.

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

jlink_exec.py — Basic Operations + Lightweight Debugging

bash

undefined

bash

undefined

探测连通性

Detect connectivity

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

烧录固件

Flash firmware

python <skill-dir>/scripts/jlink_exec.py flash --file build/app.hex --device GD32F470ZG --json

烧录 .bin（必须提供地址）

Flash .bin (address must be provided)

python <skill-dir>/scripts/jlink_exec.py flash --file build/app.bin --device GD32F470ZG --address 0x08000000 --json

读取内存

Read memory

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

写入内存

Write to memory

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

查看寄存器

View registers

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

复位目标

Reset target

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

暂停 CPU

Pause CPU

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

恢复运行

Resume operation

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

单步执行（3 步）

Step execution (3 steps)

python <skill-dir>/scripts/jlink_exec.py step --device GD32F470ZG --count 3 --json

运行到断点地址

Run to breakpoint address

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路径>`

python <skill-dir>/scripts/jlink_exec.py run-to --device GD32F470ZG --address 0x08001234 --timeout-ms 3000 --json


General optional parameters: `--interface SWD|JTAG`, `--speed 4000`, `--serial-no <serial number>`, `--exe <path to JLink.exe>`

jlink_rtt.py — RTT 日志读取

jlink_rtt.py — RTT Log Reading

bash

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。

bash

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

Optional parameters:

--serial-no

--channel

--encoding

--rtt-port

--gdbserver-exe <path>

--rtt-exe <path>

RTT working principle: The script first establishes a debug connection via JLinkGDBServerCL.exe, then starts JLinkRTTClient.exe to read RTT data. The

--json

mode outputs JSON Lines.

jlink_swo.py — SWO 事件流包装

jlink_swo.py — SWO Event Stream Wrapping

bash

undefined

bash

undefined

使用 config.json 里的 swo_command

Use swo_command in config.json

python <skill-dir>/scripts/jlink_swo.py --json

或显式传入 viewer 命令

Or explicitly pass viewer command

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 继续消费。

python <skill-dir>/scripts/jlink_swo.py
--viewer-cmd JLinkSWOViewerCL.exe -device GD32F470ZG -itf SWD -speed 4000
--json


`jlink_swo.py` does not directly implement the SWO protocol, but wraps the stdout/stderr of external viewers into JSON Lines, making it easier for upper-layer workflows or AI to consume.

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

jlink_gdb.py — GDB Source-level Debugging (requires arm-none-eabi-gdb)

bash

undefined

bash

undefined

执行自定义 GDB 命令序列

Execute custom GDB command sequence

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 run
--gdbserver-exe <path> --gdb-exe <path to arm-none-eabi-gdb>
--device GD32F470ZG --elf build/app.elf
--commands "break main" "continue" "backtrace" "info locals" --json

快捷：获取调用栈

Shortcut: Get call stack

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 backtrace
--gdbserver-exe <path> --gdb-exe <path>
--device GD32F470ZG --elf build/app.elf --json

快捷：查看局部变量

Shortcut: View local variables

python <skill-dir>/scripts/jlink_gdb.py locals
--gdbserver-exe <路径> --gdb-exe <路径>
--device GD32F470ZG --elf build/app.elf --json


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

python <skill-dir>/scripts/jlink_gdb.py locals
--gdbserver-exe <path> --gdb-exe <path>
--device GD32F470ZG --elf build/app.elf --json


GDB debugging requires an ELF file for source-level debugging (breakpoints at function names, variable viewing). Address-level debugging is still available without an ELF file.

输出格式

Output Format

所有脚本以 JSON 格式返回，基础字段为

status

（ok/error）、

action

、

summary

、

details

，并可能附带

context

、

artifacts

、

metrics

、

state

、

next_actions

、

timing

。流式观测命令使用 JSON Lines，并统一输出

source

、

channel_type

、

stream_type

。

成功示例：

json

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

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

json

{
  "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 示例（断点命中）：

json

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

All scripts return results in JSON format. Basic fields are

status

(ok/error),

action

summary

details

, and may also include

context

artifacts

metrics

state

next_actions

timing

. Stream observation commands use JSON Lines and uniformly output

source

channel_type

stream_type

Success example:

json

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

Step example (includes executed instructions):

json

{
  "status": "ok",
  "action": "step",
  "summary": "3 steps executed, 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 example (breakpoint hit):

json

{
  "status": "ok",
  "action": "run-to",
  "summary": "Breakpoint hit @ 0x08049AB4, PC=0x08049AB4",
  "details": {
    "bp_address": "0x08049AB4",
    "bp_hit": true,
    "registers": { "PC": "0x08049AB4", "..." : "..." }
  }
}

核心规则

Core Rules

不自动猜测
```
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
```

Do not automatically guess the
```
device
```
chip model; must ask the user if it is missing
Do not automatically select a probe in multi-probe scenarios; must let the user specify the serial number
Parameter parsing priority: CLI explicit parameters >
.embeddedskills/config.json
(project-level) >
skill/config.json
(environment-level) >
.embeddedskills/state.json
> default value/error
```
.bin
```
files must explicitly provide a flash address; report an error if missing
When connection fails, provide troubleshooting suggestions (check wiring, power supply, interface type, speed), do not automatically try more aggressive parameters
Flashing, memory writing, and reset are executed directly when parameters are complete and user intent is clear
Breakpoints for
```
run-to
```
are set and cleared within a single JLink session, no cross-session handle issues
The target chip, interface type, and executed action are always included in the result echo
Product paths (elf/file) do not enter project configuration, still only depend on
```
state.json
```
Running states such as
```
last_flash
```
/
```
last_debug
```
continue to be written to
```
state.json
```

调试典型工作流

Typical Debugging Workflows

快速排查（JLink Commander）

Quick Troubleshooting (JLink Commander)

halt → regs → read-mem → step → go

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

halt → regs → read-mem → step → go

Suitable for viewing current execution location, register status, and memory values, no ELF or GDB required.

断点调试（JLink Commander）

Breakpoint Debugging (JLink Commander)

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

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

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

Set a breakpoint at the specified address and wait for it to hit, then check the status at that time.

源码级调试（GDB）

Source-level Debugging (GDB)

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

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

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

Requires an ELF file and arm-none-eabi-gdb, supports function name breakpoints and variable viewing.

参考

References

遇到芯片型号问题时可查阅

references/common_devices.md

。

For chip model issues, refer to

references/common_devices.md