SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsjlink

jlink

Coding & development

View repository

Updated 10-16 11:26

About this skill

J-Link Download and Online Debugging

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

Configuration

Environment-level configuration (skill/config.json)

In the skill directory, config.json contains environment-level configuration (tool paths, port numbers, etc.). Before first use, confirm that the exe path is correct:

{
  "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 use the tool's default value
  • swo_command: Optional, complete SWO viewer command array, for jlink_swo.py wrapping
  • operation_mode：1 execute directly / 2 output risk summary but do not block / 3 confirm before execution

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

Device parameters (device/interface/speed) are managed uniformly in the workspace's .embeddedskills/config.json :

{
  "jlink": {
    "device": "STM32F407VG",
    "interface": "SWD",
    "speed": "4000"
  }
}
  • device: Chip model (e.g., STM32F407VG, GD32F470ZG)
  • interface: Debug interface, SWD or JTAG, default SWD
  • speed: Debug speed in kHz, default 4000

Parameter resolution priority:Explicit CLI 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

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

Online Debugging (JLink Commander)

Subcommand Purpose Risk
halt Pause the CPU and return register state Low
go Resume CPU execution Low
step Single-step execution (supports specifying the number of steps), returning the executed instructions and registers Low
run-to Set a breakpoint and run, returning status after it is hit Low

GDB Source-Level Debugging

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 control execution flow arm-none-eabi-gdb
gdb frame/print/watch/disassemble/threads/crash-report one-shot source-level diagnostics arm-none-eabi-gdb

Execution Flow

  1. Read skill/config.json, confirm exe path is valid
  2. Read .embeddedskills/config.json to get project-level configuration (device/interface/speed)
  3. Read .embeddedskills/state.json to get historical state
  4. Parameter resolution priority:Explicit CLI parameters > .embeddedskills/config.json(project-level) > skill/config.json(environment-level) > .embeddedskills/state.json > default value/error
  5. If the current action requires device and it is still empty, directly ask the user to provide it; never guess
  6. In multi-probe scenarios where serial_no is not specified, list the probes and let the user choose; do not select automatically
  7. According to operation_mode , decide whether confirmation is required before execution
  8. Use a template to generate a temporary .jlink command file; when calling JLink.exe, include -NoGui 1 -ExitOnError 1 -AutoConnect 1
  9. Parse the output and return code, and return a structured result
  10. After successful execution, write the confirmed device/interface/speed back to .embeddedskills/config.json

Script Invocation

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

jlink_exec.py — Basic operations + lightweight debugging

# 探测连通性
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

Common optional parameters:--interface SWD|JTAG、--speed 4000、--serial-no <序列号>、--exe <JLink.exe路径>

jlink_rtt.py — RTT log reading

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

Optional parameters:--serial-no、--channel、--encoding、--rtt-port、--gdbserver-exe <路径>、--rtt-exe <路径>

How RTT works: the script first establishes a debug connection through JLinkGDBServerCL.exe, then starts JLinkRTTClient.exe to read RTT data.--json mode outputs JSON Lines.

jlink_swo.py — SWO event stream wrapper

# 使用 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 does not directly implement the SWO protocol; instead, it uniformly wraps the external viewer's stdout/stderr into JSON Lines, making it easy for higher-level workflows or AI to continue consuming.

jlink_gdb.py — GDB source-level debugging (requires 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 debugging requires an ELF file for source-level debugging (breakpoints on function names, viewing variables). Address-level debugging can still be used without an ELF.

Output Format

All scripts return in JSON format, with the base fields being status（ok/error）、action、summary、details, and may include context、artifacts、metrics、state、next_actions、timing. Streaming observation commands use JSON Lines and uniformly output source、channel_type、stream_type。

Success example:

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

step example (including executed instructions):

{
  "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 example (breakpoint hit):

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

Core Rules

  • Do not automatically guess the device chip model; when missing, the user must be asked
  • In multi-probe scenarios, do not automatically select a probe; the user must specify the serial number
  • Parameter resolution priority is:Explicit CLI parameters > .embeddedskills/config.json(project-level) > skill/config.json(environment-level) > .embeddedskills/state.json > default value/error
  • .bin file must explicitly provide the flashing address; if missing, report an error
  • When connection fails, provide troubleshooting suggestions (check wiring, power supply, interface type, speed); do not automatically try more aggressive parameters
  • Flashing, writing memory, and reset are executed directly when parameters are complete and the user's intent is clear
  • run-to breakpoints are set and cleared within a single JLink session; there is no cross-session handle issue
  • The result echo always includes the target chip, interface type, and executed action
  • The artifact paths (elf/file) do not enter the project configuration and still only depend on state.json
  • last_flash/last_debug and other runtime states continue to be written to state.json

Typical Debugging Workflow

Quick Troubleshooting (JLink Commander)

halt → regs → read-mem → step → go

Suitable for viewing the current execution location, register states, and memory values, without the need for an ELF or GDB.

Breakpoint Debugging (JLink Commander)

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

Set a breakpoint at the specified address and wait for it to be hit, then view the state at that point.

Source-Level Debugging (GDB)

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

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

Reference

When encountering chip model issues, you can consult references/common_devices.md。