J-Link GDB Debugging

Applicable Scenarios

Users want to debug Cortex-M targets via SEGGER J-Link probes.
The workspace already has an
```
ELF
```
file and a J-Link probe.
Flashing or serial monitoring processes indicate that further inspection of breakpoints, core halt control, registers, or backtrace information is required.
Need to use the SWO output capture feature.
Need to confirm whether the JLinkGDBServer and GDB environment are ready before debugging.

A symbol-containing
```
ELF
```
file, or a
```
Project Profile
```
that includes
```
artifact_path
```
.
The
```
--device
```
parameter specifying the target chip model (required by J-Link GDB Server).

Optional debugging modes:

download-and-halt

attach-only

crash-context

The default mode is
```
download-and-halt
```
; it only switches when the user explicitly requests attach debugging or crash site inspection.
GDB is automatically detected by the script, with priority: explicit user input,
```
Project Profile
```
,
```
arm-none-eabi-gdb
```
,
```
gdb-multiarch
```
.
JLinkGDBServer is searched in the order of configuration files, PATH, and common installation paths.
An
```
ELF
```
file is mandatory for symbol-level debugging. If only
```
HEX
```
or
```
BIN
```
files are available, the process should block and request a matching
```
ELF
```
file.

First read references/usage.md to confirm whether this is an environment detection or a debugging session execution.
If unsure whether the environment is ready, first run the
```
--detect
```
mode of the built-in script scripts/jlink_debugger.py to confirm.
Select the debugging mode based on the user's intent:
```
download-and-halt
```
(default),
```
attach-only
```
, or
```
crash-context
```
.
Start debugging using
```
--elf
```
+
```
--device
```
, with optional
```
--interface
```
and
```
--port
```
parameters.
Use the
```
--swo
```
parameter when SWO output is needed.
Read the debugging results output by the script, focusing on register status, backtrace frames, and Fault registers.

Returns
```
environment-missing
```
when
```
JLinkGDBServerCLExe
```
or a compatible GDB is missing.
Returns
```
artifact-missing
```
when no available
```
ELF
```
file exists.
Returns
```
connection-failure
```
when JLinkGDBServer cannot connect to the target board.
Returns
```
project-config-error
```
when the device name is not recognized by J-Link or the configuration is inconsistent.
Returns
```
target-response-abnormal
```
when the session can be established but cannot halt the core, load files, or obtain a reliable backtrace.
Returns
```
ambiguous-context
```
when
```
--device
```
is missing and cannot be inferred from the workspace.

JLinkGDBServer is
```
JLinkGDBServerCLExe
```
on Linux/macOS, and
```
JLinkGDBServerCL.exe
```
on Windows.
The default GDB port is 2331 (J-Link default), which can be modified via
```
--port
```
.
The built-in script uses Python standard libraries and subprocess, and is cross-platform compatible.
The SWO feature is exclusive to J-Link and can capture ITM printf output.

Output the debugging mode, JLinkGDBServer command, GDB executable file,
```
ELF
```
path, and key observation conclusions.

Retain

artifact_path

artifact_kind

gdb_executable

, and

jlink_device

in the

Project Profile

When the next step after reset or resume is to observe runtime behavior,
```
serial-monitor
```
is recommended.

When the target resumes operation and runtime logs need to be observed continuously, hand over the successful session to
```
serial-monitor
```
.
When the user requires RTOS thread-aware debugging, hand over the session to
```
rtos-debug
```
.