📚 课程目录第4章 J-Scope工程创建与目标配置

4. J-Scope工程创建与目标配置

J-Scope 的使用并不是“打开软件就能看波形”，它需要先建立一个工程，把目标器件、J-Link 接口、可执行文件和采样变量这几件事绑定在一起。工程文件（.jscope）本质上是一份配置清单：它记录了用哪颗芯片、以什么接口和速度连接、从哪个 ELF/AXF/OUT 文件里读取符号信息、要采集哪些变量、采样率多高。理解这份清单的每一项，才能在实际调试中快速定位“连不上”“变量列表为空”“波形不对”等问题。

新建工程与目标器件选择

启动 J-Scope 后选择 File → New Project，进入配置向导。第一步是选择目标器件（Target Device）。这里的器件型号必须与目标板上实际运行的 MCU 一致，例如 STM32F407IG、STM32H743ZI、nRF52840_xxAA、i.MX RT1062 等。器件选择决定了 J-Link 使用哪套初始化序列、RAM 地址范围以及调试寄存器定义。如果选错型号，常见后果是连接成功但变量地址解析异常，或者根本无法 halt 内核。

如果目标板使用自定义上电时序、外部 SDRAM 或特殊时钟配置，仅靠器件型号可能不够，此时应改用 J-Link 脚本（.JLinkScript）或在 J-Link Commander 中先执行初始化命令。对于大多数标准开发板，直接选型号即可。

J-Link接口参数设置

接口配置决定 J-Link 如何与目标通信，关键参数如下：

Interface：SWD 或 JTAG。Cortex-M 通常用 SWD，只需 SWCLK、SWDIO 两根信号线，引脚占用少、速度稳定。
Speed：SWD 时钟频率，单位 kHz。调试初期建议 1000～4000 kHz；若走线较长或目标时钟较低，可降到 500 kHz 提高稳定性。
Reset 方式：可选择 Normal、ResetPin、Connect under reset 等。当目标程序一上电就进入低功耗或关闭调试引脚时，必须用 Connect under reset 才能建立连接。
Target 供电检测：确认 J-Link 是否为目标板供电，避免因供电不足导致连接间歇性失败。

这些参数在 J-Scope 的 Target Interface 页面设置，也可以在 J-Link Commander 中用 si SWD、speed 4000、connect 命令先行验证。建议先用 Commander 确认能识别到内核 ID（如 0x2BA01477），再回到 J-Scope 配置，可排除大部分连接问题。

加载 ELF/AXF/OUT 文件

J-Scope 需要从可执行文件中读取符号表，才能把变量名映射到内存地址。支持三种格式：

ELF：GCC/Clang 工具链默认输出，包含完整符号与调试信息，最常用。
AXF：ARM Compiler（Keil MDK）的输出格式，本质是 ELF 的变体。
OUT：部分 IAR 或旧工具链的输出，需确认包含符号表。

加载时要注意：文件必须与目标板上正在运行的固件完全对应。如果修改代码后重新编译却没有更新 J-Scope 中的文件，变量地址就会错位，波形会显示成无意义的数值。工程中可勾选 Reload on change，让 J-Scope 在文件更新后自动重新加载符号。

另外，变量要能被 J-Scope 看到，必须满足两个条件：一是变量具有全局作用域（非 static 局部变量），二是编译器没有把它优化掉。建议对采样变量加 volatile 修饰，并在编译选项中保留调试信息（-g）。

配置采样变量与采样率

符号加载完成后，J-Scope 会列出可选的变量。把需要观察的变量加入采样列表，例如电机控制中的 g_motorSpeed、g_currentA、g_pidOutput。每个变量可单独设置显示颜色和缩放系数。

采样率（Sample Rate）是核心参数，它决定 J-Scope 每秒从目标内存读取多少次数据。采样率越高，波形时间分辨率越好，但占用更多 J-Link 带宽和 CPU 时间。实际可达到的采样率受接口速度、变量数量和目标 RAM 访问速度共同限制。例如 SWD 4000 kHz、采样 4 个 32 位变量时，典型可持续采样率在 10～50 kHz 量级；若变量增多或接口降速，采样率会明显下降。

J-Scope 提供两种采样模式：

Halt 模式：每次采样前暂停 CPU，读取变量后再恢复。精度高，但会干扰实时运行，适合低速调试。
RTT 模式：通过 SEGGER RTT 从目标内存缓冲区读取，CPU 几乎不停顿，适合实时性要求高的场景。使用 RTT 模式需要在固件中集成 RTT 代码并创建 up-buffer。

建议先用较低采样率（如 1 kHz）确认变量数值合理，再逐步提高，观察是否出现丢点或连接断开。稳定后再固定为最终采样率。

配置流程与关键关系

下面这张图把工程创建到开始采样的配置链路、关键参数和它们之间的依赖关系集中呈现出来，便于对照检查每一步的输入与影响。

工程保存与复用

配置完成后选择 File → Save Project，保存为 .jscope 文件。该文件记录了器件、接口、符号文件路径、变量列表和采样率，下次直接打开即可恢复全部设置。在团队协作中，建议把 .jscope 与固件源码一起纳入版本管理，但要注意符号文件路径可能因编译输出目录不同而失效，必要时使用相对路径或在打开后重新指定 ELF 文件。

每次重新编译固件后，务必确认 J-Scope 加载的是最新 ELF/AXF/OUT 文件。符号地址错位不会报错，但会得到完全错误的波形，这是实际调试中最隐蔽的陷阱之一。

完成以上配置后，点击 Start 即可开始采样。此时应先在示波器或串口输出中确认目标程序确实在运行，再观察 J-Scope 波形是否随时间变化。如果波形是一条直线，先检查变量是否真的被程序修改，再检查采样模式是否与固件中的 RTT 配置匹配。只有把“工程—器件—接口—符号—变量—采样率”这条链路逐项确认，J-Scope 才能成为可靠的实时数据采集工具。