概述

本章主要介绍开发板支持的三种调试方式：

  • GDB 调试

    • 可在主机上直接运行，通过 GDB Server 与目标设备通信

    • 支持使用 .axf 文件，在相应源码位置设置断点，实现源码级调试

  • Jlink 调试

    • 支持直接暂停 CPU 并获取 CPU 的当前状态

    • 可直接访问和操作目标设备内存

  • Ozone 调试

    • 提供图形化界面调试, 便于调试和可视化操作

硬件连接

参考下图将 JLink 的 SWCLK 和 SWDIO 连接到 SoC 的 SWD CLK 和 SWD DATA，然后将 JLink 连接到 PC。

../../rst_rtos/0_gdb_debug/figures/connecting_jlink_to_swd.svg

JLink 连接到 SWD 的接线图

备注

JLink 的版本必须高于或等于 v9。

GDB 调试

GDB 软件连接和配置

  1. 从 SEGGER 官网下载并安装最新版 JLink

  2. 连接时可编辑对应的 xxx_jlinkGDBSever.bat 调整 JLinkGDBServer.exe 的路径

连接 JLinkGDBSever

双击 {SDK}\amebadplus_gcc_project\utils\jlink_script\cm4_jlinkGDBSever.bat，如下图所示，确认 KM4 与 JLinkGDBSever 成功连接。

../../rst_rtos/0_gdb_debug/figures/dplus_windows_km4_jlink_gdb_server_connection.png

小心

  • 保持此窗口开启以进行后续操作

GDB 固件烧录

我们更推荐使用 Realtek 提供的 Image Tool 软件下载固件。更多信息请参考 Image Tool。

如果必须使用 JLinkGDBSever 下载固件，请参考如下内容：

  1. 编译固件（参考 编译代码）并连接 JLinkGDBSever

  2. 键入 build.py -gdb 命令开始下载，之后固件将被下载到 Flash 中，以 RTL8721Dx 为例，如下所示：

    Breakpoint 1, Gdb_Floader_Program_Start () at .amebadplus_gcc_project/project_km4/asdk/flashloader/rtl_flash_download.c:36
36      in .amebadplus_gcc_project/project_km4/asdk/flashloader/rtl_flash_download.c
flash_write FileName:3
flash_write FileSize:0
Loopnumber = 0
TailSize = 0
global variables
FlashDatSrc:3000a754
FlashBlockWriteSize:800
Flash write start...

Breakpoint 2, Gdb_Floader_Program_End () at .amebadplus_gcc_project/project_km4/asdk/flashloader/rtl_flash_download.c:45
45      in .amebadplus_gcc_project/project_km4/asdk/flashloader/rtl_flash_download.c
dump for check

  3. 验证固件是否被正确地下载

在下载之前勾选 verify download，在固件下载过程中，将会有 verified OK 的日志提示。

../../rst_rtos/0_gdb_debug/figures/windows_verify_download.png

  1. 下载完成后按下 Reset 按键，可以看到设备使用新的固件启动。

GDB 调试模式流程

  1. 编译固件并连接 JLinkGDBSever

  2. 执行命令：

    1. 进入 SDK 根目录

    2. 运行 build.py -debug，进入 GDB 模式，以 RTL8721Dx 为例，如下所示：

    GDB CMD :  cd E:\sdk0508\amebadplus_gcc_project\project_km4/asdk && C:/rtk-toolchain/asdk-10.3.1-4365/mingw32/newlib/bin/arm-none-eabi-gdb.exe -x E:\sdk0508\amebadplus_gcc_project\project_km4/asdk\gnu_utility/gnu_script\rtl_gdb_debug.txt
GNU gdb (Realtek ASDK-10.3.1 Build 4365) 12.1.90.20221114-git
Copyright (C) 2022 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Type "show copying" and "show warranty" for details.
This GDB was configured as "--host=x86_64-w64-mingw32 --target=arm-none-eabi".
Type "show configuration" for configuration details.
For bug reporting instructions, please see:
<https://www.gnu.org/software/gdb/bugs/>.
Find the GDB manual and other documentation resources online at:
   <http://www.gnu.org/software/gdb/documentation/>.

For help, type "help".
Type "apropos word" to search for commands related to "word".
warning: No executable has been specified and target does not support
determining executable automatically.  Try using the "file" command.
0x3000a304 in ?? ()
Notification of completion for asynchronous execution commands is off.
(gdb)

GDB 调试器指南

GNU 调试器支持在程序运行时进行状态检查与错误追踪（参考章节 GDB 调试模式流程）

完整文档：GDB 用户手册

功能指令对照表

功能模块

命令

操作说明

断点管理

break (b)

设置执行暂停点

数据监视点

watch

监控变量变化 (含 watch/rwatch/awatch)

断点列表

info

显示所有激活的断点/监视点

断点删除

delete (d)

移除指定断点

恢复执行

continue (c)

继续程序运行

单步进入

step (s)

进入函数内部执行

单步跳过

next (n)

执行当前行并跳至下一行

退出调试

quit (q)

终止调试会话

调用追踪

backtrace (bt)

显示函数调用栈

源码查看

list (l)

显示上下文代码

数据检查

print (p)

输出变量/表达式值

备注

  • 数据监视点的监视范围建议小于 20 字节。

Ozone 调试

Ozone 软件安装

从 SEGGER 官网下载并安装最新版 JLink 及 Ozone

Ozone 工程配置

创建，保存及运行工程。

连接 JLink 后启动 Ozone 创建新工程，按照以下步骤执行

  1. 进入主界面，选择创建新工程，如下图所示

    ../../rst_rtos/0_gdb_debug/figures/ozone_creat_project.png

  2. 选择目标设备及 svd 文件， 如下图所示：

    ../../rst_rtos/0_gdb_debug/figures/ozone_choice_device.png

  3. 连接设置：选择接口并确认 JLink 设备， 如下图所示：

    ../../rst_rtos/0_gdb_debug/figures/ozone_conection_setting.png

  4. 选择 debug 文件， 如下图所示：

    ../../rst_rtos/0_gdb_debug/figures/ozone_choose_debugged_program.png

  5. 初始化设置：Initial PC 和 Stack Pointer 选择 Do not set， 在 amebaxxxx_gcc_project/utils/jlink_script 目录中选择相应的 JLinkScript 文件，如下图所示：

    ../../rst_rtos/0_gdb_debug/figures/ozone_inital_setting.png

  6. 插件安装警告

    • 安装： 点击 Apply 后将自动安装，在 Console 窗口可查看安装结果

    • 不安装：点击 Continue T 跳过安装

    ../../rst_rtos/0_gdb_debug/figures/ozone_plugin_diagnostics.png

  7. 工程创建成功

Ozone 调试功能

点击 View, 在下拉菜单中可查看 Ozone 支持的调试功能，点击功能项即可将其添加至主界面窗口。该章节介绍一些常用的调试功能。

  1. 断点添加

    • 代码断点：在 File Scope 区打开的 c 文件中，点击代码行左侧的灰色圆点即可添加

    • 数据断点：在 Break & TracePoints 窗口右击空白处使用下拉菜单中以变量名或者地址的方式添加。可在全局、局部变量窗口右键变量名选择添加至断点。

  2. 断点清除

    • 代码断点：点击代码行左侧的红色圆点，当变为灰色圆点即取消断点

    • 在 Break & TracePoints 窗口右击空白处使用下拉菜单中清除断点功能

    • 在 Break & TracePoints 窗口点击断点左侧方框中 √ 可选择禁用或启用断点

  3. 断点查看

    • 程序运行到断点位置后暂停且对应行代码绿色高亮，如下图所示：

    ../../rst_rtos/0_gdb_debug/figures/ozone_breakpoints_setting.png

    小心

    • 断点可设置数量有限，若超过可添加数量限制, 则会出现如下错误提示 SetBreakpoint: JLINK API call failed

Ozone 指令集

Ozone 调试器支持在程序运行时进行状态检查与错误追踪， 在 Console 窗口输入 help 可查看所有可用指令

官方文档参考：Ozone 用户手册