debug-jlink

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

J-Link GDB 调试

J-Link GDB Debugging

适用场景

Applicable Scenarios

用户希望通过 SEGGER J-Link 探针调试 Cortex-M 类目标。
工作区中已有
```
ELF
```
和 J-Link 探针。
烧录或串口监视流程表明，需要进一步查看断点、停核控制、寄存器或回溯信息。
需要使用 SWO 输出捕获功能。
需要在调试前确认 JLinkGDBServer 和 GDB 环境是否就绪。

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.

必要输入

Required Inputs

一份带符号的
```
ELF
```
，或包含
```
artifact_path
```
的
```
Project Profile
```
。
```
--device
```
参数指定目标芯片型号（J-Link GDB Server 要求必须指定）。

可选调试模式：

download-and-halt

、

attach-only

、

crash-context

。

可选的 GDB 可执行文件路径。

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

Optional path to the GDB executable file.

自动探测

Auto-Detection

默认模式为
```
download-and-halt
```
；只有用户显式要求附着调试或崩溃现场检查时才切换。
GDB 由脚本自动探测，优先级为：显式用户输入、
```
Project Profile
```
、
```
arm-none-eabi-gdb
```
、
```
gdb-multiarch
```
。
JLinkGDBServer 按配置文件、PATH、常见安装路径顺序查找。
做符号级调试必须有
```
ELF
```
。若只有
```
HEX
```
或
```
BIN
```
，应阻塞并要求提供匹配
```
ELF
```
。

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.

执行步骤

Execution Steps

先阅读 references/usage.md，确认本次是环境探测，还是执行调试会话。
若不确定环境是否就绪，先运行自带脚本 scripts/jlink_debugger.py 的
```
--detect
```
模式确认。
根据用户意图选择调试模式：
```
download-and-halt
```
（默认）、
```
attach-only
```
或
```
crash-context
```
。
使用
```
--elf
```
+
```
--device
```
启动调试，可选
```
--interface
```
和
```
--port
```
。
需要 SWO 输出时，使用
```
--swo
```
参数。
读取脚本输出的调试结果，重点关注寄存器状态、回溯帧和 Fault 寄存器。

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.

失败分流

Failure Diversion

当缺少
```
JLinkGDBServerCLExe
```
或兼容 GDB 时，返回
```
environment-missing
```
。
当没有可用的
```
ELF
```
时，返回
```
artifact-missing
```
。
当 JLinkGDBServer 无法连接目标板时，返回
```
connection-failure
```
。
当设备名不被 J-Link 识别或配置不一致时，返回
```
project-config-error
```
。
当会话可以建立，但无法停核、加载或得到可信回溯时，返回
```
target-response-abnormal
```
。
当
```
--device
```
缺失且无法从工作区推断时，返回
```
ambiguous-context
```
。

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.

平台说明

Platform Notes

JLinkGDBServer 在 Linux/macOS 下为
```
JLinkGDBServerCLExe
```
，Windows 下为
```
JLinkGDBServerCL.exe
```
。
默认 GDB 端口为 2331（J-Link 默认），可通过
```
--port
```
修改。
自带脚本使用 Python 标准库和 subprocess，跨平台兼容。
SWO 功能为 J-Link 独有，可捕获 ITM printf 输出。

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 Conventions

输出调试模式、JLinkGDBServer 命令、GDB 可执行文件、
```
ELF
```
路径和关键观察结论。

在

Project Profile

中保留

artifact_path

、

artifact_kind

、

gdb_executable

、

jlink_device

。

当复位后或继续运行后下一步是观察运行行为时，推荐
```
serial-monitor
```
。

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.

交接关系

Handover Relationships

当目标恢复运行后，需要继续观察运行期日志时，将成功会话交给
```
serial-monitor
```
。
当用户需要 RTOS 线程感知调试时，将会话交给
```
rtos-debug
```
。

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