Introduction

This chapter describes the three debugging modes supported by the development board.

• GDB Debug

  • Run on the host directly and communicate with the target device via GDB Server.

  • Support using the .axf file to set breakpoints at the corresponding source code locations.

• Jlink Debug

  • Support halting the CPU and obtaining the current CPU status directly.

  • Allow direct access to the target device’s memory.

• Ozone Debug

  • Provide graphical user interface debugging operations.

Hardware Connection

Refer to the following diagram to connect JLink’s SWCLK and SWDIO to the SoC’s SWD CLK and SWD DATA, then connect JLink to the PC.

Wiring diagram of connecting JLink to SWD

Note

The JLink version must be v9 or higher.

GDB Debug

GDB Software Connect and Configure

WindowsLinux

1. Download and install the latest GDB Server from SEGGER official website

2. Edit the corresponding xxx_jlinkGDBSever.bat to adjust the path of JLinkGDBServer.exe

RTL8721DxRTL8720ERTL8726ERTL8713ERTL8730ERTL8721F

KM4 SetupKM0 Setup

Connect JLinkGDBSever

Double-click {SDK}\amebadplus_gcc_project\utils\jlink_script\cm4_jlinkGDBSever.bat. As shown below, confirm successful connection between KM4 and JLinkGDBSever:

Caution

• Keep this window open for subsequent operations

GDB Download Image

We recommend using Realtek’s Image Tool software for firmware download. For more information, please refer to Image Tool.

If you must use JLinkGDBSever to download the firmware, please follow the instructions below:

1. Compile the image (refer to Building Code) and connect JLink

2. Enter the build.py -gdb command to start the download. The firmware will be downloaded to Flash, and take RTL8721Dx as an example, as shown below:

   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. Confirm the firmware

WindowsLinux

select verify download before downloading. During the firmware download, there will be a verified OK log prompt.

4. After the download is complete, press the Reset button to see the device boot with the new firmware.

Debug Mode Entry Process

1. Build Image and Connect JLinkGDBSever

2. Execute Debug Commands

   1. Navigate to SDK root directory

   2. Run build.py -debug to enter GDB mode, take RTL8721Dx as an example, as shown below:

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

GNU Debugger enables runtime state inspection and error tracing (Reference: Debug Mode Entry Process)

Complete documentation: GDB User Manual

Functional command reference

Function Module	Command	Operation Guide
Breakpoint Management	break (b)	Set execution pause points
Data Watchpoints	watch	Monitor variable changes (watch/rwatch/awatch)
Breakpoint List	info	Display active breakpoints/watchpoints
Breakpoint Removal	delete (d)	Remove specified breakpoint
Execution Resume	continue (c)	Continue program execution
Step Into	step (s)	Enter function execution
Step Over	next (n)	Execute current line and jump to next
Debug Session Exit	quit (q)	Terminate debugging session
Call Trace	backtrace (bt)	Display function call stack
Source Code View	list (l)	Display contextual code
Data Inspection	print (p)	Output variable/expression values

Note

• Recommended watch scope <20 bytes.

JLink Debug

JLink Connect and Configure

WindowsLinux

1. Download and install the latest JLink from SEGGER official website

2. Edit the corresponding xxx_jlink.bat to adjust the path of JLink.exe

RTL8721DxRTL8720ERTL8726ERTL8713ERTL8730ERTL8721F

KM4 SetupKM0 Setup

Connect JLink

Double-click {SDK}\amebadplus_gcc_project\utils\jlink_script\cm4_jlink.bat. Follow the prompts to enter connect and Enter (default value). As shown below, confirm successful connection between KM4 and JLink:

Type "connect" to establish a target connection, '?' for help
J-Link>connect
Specify target interface speed [kHz]. <Default>: 4000 kHz
Speed>
Device "CORTEX-M33" selected.

Connecting to target via SWD
InitTarget() start
InitTarget() end
Found SW-DP with ID 0x6BA02477
DPIDR: 0x6BA02477
AP map detection skipped. Manually configured AP map found.
AP[0]: APB-AP (IDR: Not set)
AP[1]: AHB-AP (IDR: Not set)
AP[2]: AHB-AP (IDR: Not set)
AP[2]: Core found
AP[2]: AHB-AP ROM base: 0xE00FF000
CPUID register: 0x721FD22A. Implementer code: 0x72 (Realtek)
Feature set: Mainline
Found Cortex-M33 r1p10, Little endian.
FPUnit: 4 code (BP) slots and 0 literal slots
Security extension: implemented
Secure debug: enabled
CoreSight components:
ROMTbl[0] @ E00FF000
[0][0]: E000E000 CID B105900D PID 000F9133 DEVARCH 47702A04 DEVTYPE 00 SCS
[0][1]: E0001000 CID B105900D PID 000F9035 DEVARCH 47701A02 DEVTYPE 00 DWT
[0][2]: E0002000 CID B105900D PID 000F9034 DEVARCH 47701A03 DEVTYPE 00 FPB
Cortex-M33 identified.

JLink Core Command Set

Command quick reference

Command (Full)	Shortcut	Syntax	Description
Halt	H		Suspend CPU execution
Go	G		Resume CPU execution
Mem	/	Mem <Address> <ByteCount>	Read memory (ASCII format)
SaveBin	/	SaveBin <File> <Address> <ByteCount>	Dump memory to binary file
Exit	/		Disconnect JLink

Official documentation: https://wiki.segger.com/J-Link_Commander

Note

• Track PC values via multiple H/G executions

• Use mem <sp_address> to inspect call stack

Ozone Debug

Ozone Software Installation

WindowsLinux

Download and install the latest version of JLink and Ozone from the official SEGGER website.

Ozone Project Configuration

Create, save, and run projects.

Create ProjectSave ProjectRun Project

Connect JLink and launch Ozone to create a new project by following steps:

1. Enter the main interface and create a new project, as shown below:

2. Select the target device and svd file, as shown below:

3. Configure connection settings: choose the interface and confirm the JLink device, as shown below:

   

4. Select the debug file, as shown below:

5. Set initialization options

   • Initialization settings: Set Initial PC and Stack Pointer to Do not set.

   • Select the corresponding JLinkScript file from the amebaxxxx_gcc_project/utils/jlink_script directory, as shown below:

6. Handle Plugin installation warning

   • Install: Click Apply to install automatically. The installation result will be shown in the Console window.

   • Do not install: Click Continue to proceed without installing.

7. Project created successfully

Ozone Debug Features

In this section, commonly used debug features are introduced. Click View to see the debug functions supported by Ozone.

General Debug FeaturesReal-time Monitoring Features

Breakpoint SettingReset DebugSingle Step DebugCall Stack AnalysisDual-core Debugging

1. Adding Breakpoints

   • Code breakpoint: In the C file opened in the File Scope area, click the gray dot to the left of the code line to add a breakpoint.

   • Data breakpoint: In the Break & TracePoints window, right-click on a blank area and use the drop-down menu to add a breakpoint by variable name or address. Alternatively, right-click a variable name in the global or local variable window and select the option to add it as a breakpoint.

2. Removing Breakpoints

   • Code breakpoint: Click the red dot to the left of the code line. When it changes to a gray dot, the breakpoint is removed.

   • In the Break & TracePoints window: Right-click on a blank area and use the drop-down menu to remove a breakpoint.

   • Enable/disable: In the Break & TracePoints window, click √ to the left of the breakpoint to enable or disable it.

3. Viewing Breakpoints

   • When the program reaches a breakpoint, it will pause and the corresponding line of code will be highlighted in green, as shown below:

   

   Caution

   • The number of breakpoints that can be set is limited. If exceed this limit, the following error message will appear SetBreakpoint: JLINK API call failed.

Ozone Command Set

The Ozone debugger supports checking program status and tracing errors during execution. To view all available commands, enter help in the Console window.

Official documentation reference: Ozone User Manual