J-Link Download and Online Debugging

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

Environment-level Configuration (skill/config.json)

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

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

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

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

Online Debugging (JLink Commander)

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 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 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

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

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

jlink_exec.py — Basic Operations + Lightweight Debugging

bash

# 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

# 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

# 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

# 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

General optional parameters:

--interface SWD|JTAG

--speed 4000

--serial-no <serial number>

--exe <path to JLink.exe>

jlink_rtt.py — RTT Log Reading

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 Event Stream Wrapping

bash

# Use swo_command in config.json
python <skill-dir>/scripts/jlink_swo.py --json

# 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

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 Source-level Debugging (requires arm-none-eabi-gdb)

bash

# Execute custom GDB command sequence
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 <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 <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

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

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

Quick Troubleshooting (JLink Commander)

halt → regs → read-mem → step → go

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

Breakpoint Debugging (JLink Commander)

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.

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, supports function name breakpoints and variable viewing.

References

For chip model issues, refer to

references/common_devices.md

jlink

NPX Install

Tags

SKILL.md Content (Chinese)

J-Link Download and Online Debugging

Configuration

Environment-level Configuration (skill/config.json)

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

Subcommands

Basic Operations

Online Debugging (JLink Commander)

GDB Source-level Debugging

Execution Flow

Script Invocation

jlink_exec.py — Basic Operations + Lightweight Debugging

jlink_rtt.py — RTT Log Reading

jlink_swo.py — SWO Event Stream Wrapping

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

Output Format

Core Rules

Typical Debugging Workflows

Quick Troubleshooting (JLink Commander)

Breakpoint Debugging (JLink Commander)

Source-level Debugging (GDB)

References