J-Link Debugging

Introduction

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

• Direct J-Link Debugging

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

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

• GDB-Based J-Link Debugging

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

• Ozone-Based J-Link Debugging

  • Provide graphical user interface debugging operations.

Hardware Connection

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

Wiring diagram of connecting J-Link to SWD

Note

The J-Link version must be v9 or higher.

Direct J-Link Debugging

JLink Connect and Configure

WindowsLinux

1. Download and install the latest J-Link from SEGGER official website

2. Connect J-Link

RTL8721DxRTL8720ERTL8710ERTL8726ERTL8713ERTL8730ERTL8721F

KM4 SetupKM0 Setup

Execute ameba.py jlink -k km4 in the root directory of the SDK. Follow the prompts to enter connect and Enter (default value). As shown below, confirm successful connection between KM4 and J-Link:

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.

Note

JLink.exe default installation path is C:\Program Files (x86)\SEGGER\JLink. To specify a custom path, use: ameba.py jlink -k XXX -d <jlink_path>

J-Link 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 J-Link

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

GDB-Based J-Link Debugging

GDB Software Connect and Configure

WindowsLinux

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

2. Connect JLinkGDBSever

RTL8721DxRTL8720ERTL8710ERTL8726ERTL8713ERTL8730ERTL8721F

KM4 SetupKM0 Setup

Execute ameba.py jlink -t gdb -k km4 in the root directory of the SDK. As shown below, confirm successful connection between KM4 and JLinkGDBSever:

Caution

• Keep this window open for subsequent operations

Note

JLinkGDBServer default installation path is C:\Program Files (x86)\SEGGER\JLink. To specify a custom path, use: ameba.py jlink -t gdb -k XXX -d <jlinkgdb_path>

Debug Mode Entry Process

1. Build Image and Connect JLinkGDBSever

2. Execute Debug Commands

   1. Navigate to SDK root directory

   2. Run ameba.py build -debug to enter GDB mode, 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 (Refer to 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.

Ozone-Based J-Link Debugging

Generating JLinkScript

Execute the command ameba.py jlink -t ozone in the SDK root directory. By default, the generated files are saved in the {SDK}/build_RTLxxx/jlink_script directory.

To customize the output path, use the -sd parameter. For example: ameba.py jlink -t ozone -sd <jlinkscript_path>

Ozone Software Installation

WindowsLinux

Download and install the latest version of J-Link and Ozone from the official SEGGER website.

Ozone Project Configuration

Create, save, and run projects.

Create ProjectSave ProjectRun Project

Connect J-Link 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 J-Link 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 {SDK}/build_RTL8721Dx/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