RZ/G OpenOCD Information
Introduction
This page provides a guide to use OpenOCD and compatible JTAG debugger devices on RZ/G2 platforms.
Target Devices
RZ/G2L-LC-UL, RZ/Five SMARC evaluation boards
Overview
OpenOCD is an opensource software that provides on-chip programming and debugging feature, with support from compatible JTAG hardware debugger devices.
Prerequisites
A compatible JTAG hardware debugger device is required. Different JTAG devices can have slightly different procedure.
As an example, following guidance is for:
Segger J-Link Debug Probe
J-Link BASE, J-Link PLUS, J-Link PRO
Requires 20-to-10 pin adapter
ARM-JTAG-20-10 Adapter
Tigard Open Source Tool
Includes correct 10-pin JTAG cable (no adapter is needed)
Requires USB-C cable for power and data (not included)
🛒 ($49) https://www.mouser.com/ProductDetail/Securing-Hardware/TIGARD-V1?qs=aP1CjGhiNiFnjSEE%2FnXyEw%3D%3D
Hardware setup
Most RZ development boards has 10 pin JTAG header, so a JTAG converter (20pin-10pin) might be required depending on what JTAG adapter you are using. For example the Olimex ARM-JTAG-20-10. can be used to convert from 20-pin to 10-pin.
After connecting the devices as per guide in the previous section, follow below instructions to use OpenOCD and JTAG debugger. You must change the switches setting on development board to enable the JTAG debugging feature. The switches setting may be different for each development board. Please refer to the relevant board manual or user guide for detailed information.
SMARC RZ/G2L-LC-UL, RZ/Five board
Change switches as per below.
SW1: OFF - OFF
EK874 RZ/G2E board
Change switches as per below. Note that board version 3 (Rev C) or later must be used.
SW12: change bit 4 and 5 to OFF to enable JTAG
SW50: change to (2-3) side
SW51: change to (1-2) side
HiHope RZ/G2M-N-H board
Change switches as per below. Note that board rev. 3 or later must be used.
SW1003: change bit 4 to OFF to enable JTAG
SW305: change to (2-3) side
SW2405: change to (1-2) side
Tigard Switch Setting
If you are using a Tigard, set the TARGET switch to 1v8
and the MODE switch to JTAG
Use the 10-pin 1.27mm ribbon cable that comes in the kit. Attach the cable as seen below by connecting the “CORTEX” connector on the Tigard board to the “Debug I/F” CN2 connector on the RZ/G2L SMARC board.
Download and Build OpenOCD
To build OpenOCD you can use this script found in the https://github.com/renesas-rz/rzg_openocd repository.
$ wget https://raw.githubusercontent.com/renesas-rz/rzg_openocd/master/build_openocd.sh$ wget https://raw.githubusercontent.com/renesas-rz/rzg_openocd/master/0001-tcl-target-renesas_rz_g2-Rename-to-renesas_rz-and-ad.patch$ wget https://raw.githubusercontent.com/renesas-rz/rzg_openocd/master/0002-target-aarch64-MRS-MSR-support-for-system-register-a.patch$ wget https://raw.githubusercontent.com/renesas-rz/rzg_openocd/master/0003-target-aarch64-enable-disable-mmu-new-commands.patch$ wget https://raw.githubusercontent.com/renesas-rz/rzg_openocd/master/0004-target-aarch64-Add-code-to-invaldate-the-instruction.patch$ wget https://raw.githubusercontent.com/renesas-rz/rzg_openocd/master/0005-tcl-target-renesas_rz-add-hwthread-and-coreid.patch$ chmod +x ./build_openocd.sh$ export GIT_SSL_NO_VERIFY=1 # Avoid GIT error: server certificate verification failed$ ./build_openocd.sh
Or manually follow the steps in that script:
The script / procedure assumes that the environment is a relatively new Ubuntu (>=22.04). The OpenOCD binaries can be found in the openocd/installdir/bin directory.
In the configuration, options that are commonly needed are --enable-ftdi to ensure ftdi related function will be built. Same for J-Link, with --enable-jlink, however both should be recognized and added automatically during the configuration phase.
Note - The patch is not strictly needed. It slows down the download operations but it is required if an existing code in memory has to be replaced by using the JTAG.
Run OpenOCD
OpenOCD provides many setting scripts for many JTAG debugger and development boards under directory share/openocd/scripts/.
Normally two suitable scripts has to be chosen, one for Debugger Configuration and one for the Development Board or SoC Configuration.
Debugger Configuration File
To debug with J-Link, the following script is available: share/openocd/scripts/interface/jlink.cfg
To debug with Tigard, the following script is available: share/openocd/scripts/interface/ftdi/tigard.cfg
Development Board or SoC Configuration File
The Device configuration file for the RZ family is share/openocd/scripts/target/renesas_rz.cfg
Note: In the Official OpenOCD repository, the file name is renesas_rz_g2.cfg. However, in the patches you downloaded and ran, we renamed it to renesas_rz.cfg. We plan to mainline this change back into the official openocd repository eventually
Development Board or SoC Configuration (SoC selection)
Different commands have to be used to select different devices belonging to the RZ family:
SMARC RZ/G2L board: "set SOC G2L" (default), i.e. -c can be omitted
SMARC RZ/G2LC board: "set SOC G2LC"
SMARC RZ/G2UL board: "set SOC G2UL"
SMARC RZ/V2L board: "set SOC V2L"
SMARC II RZ/G3S board: "set SOC G3S"
EK874 RZ/G2E board: "set SOC G2E"
HiHope RZ/G2M board: "set SOC G2M"
HiHope RZ/G2N board: "set SOC G2N"
HiHope RZ/G2H board: "set SOC G2H"
Example Command Lines:
Example to run OpenOCD and attach to a RZ/G2L device using a Segger J-Link JTAG adapter:
$ cd installdir
$ sudo bin/openocd -f share/openocd/scripts/interface/jlink.cfg -c "set SOC G2L" -f share/openocd/scripts/target/renesas_rz.cfg
Example to run OpenOCD and attach to a RZ/G2L device using a Tigard JTAG adapter:
$ cd installdir
$ sudo bin/openocd -f share/openocd/scripts/interface/ftdi/tigard.cfg -c "set SOC G2L" -f share/openocd/scripts/target/renesas_rz.cfg
RZ/Five uses a different configuration file (renesas_rz_five.cfg)
Example to run OpenOCD and attach to a RZ/Five device using a Segger J-LinkJTAG adapter:
$ cd installdir
$ sudo bin/openocd -f share/openocd/scripts/interface/jlink.cfg -f share/openocd/scripts/target/renesas_rz_five.cfg
Please note that there's a way to avoid the usage of sudo by making sure that both the user and the debugger devices used belong to the dialout/plugdev groups.
JTAG Adapter Clock Speed
You can modify the renesas_rz_*.cfg configure file to tweak the clock speed (default 4MHz), for example to increase it to 15MHz:
adapter speed 15000
Verify Connection
If openocd command succeeds, a message like these below appears:
Open On-Chip Debugger 0.12.0+dev-01565-g5622ada82 (2024-04-10-13:59)
Licensed under GNU GPL v2
For bug reports, read
http://openocd.org/doc/doxygen/bugs.html
G2L
G2L - 0 CA57(s), 2 CA55(s), 0 CA53(s), 0 CR7(s), 1 CM33(s)
Boot Core - CA55
r9a07g044l.cpu
SMP targets: r9a07g044l.a55.0 r9a07g044l.a55.1
init_reset
Info : Listening on port 6666 for tcl connections
Info : Listening on port 4444 for telnet connections
Info : J-Link Lite V10 compiled Jan 30 2023 11:28:07
Info : Hardware version: 10.10
Info : VTarget = 1.761 V
Info : clock speed 4000 kHz
Info : JTAG tap: r9a07g044l.cpu tap/device found: 0x6ba00477 (mfg: 0x23b (ARM Ltd), part: 0xba00, ver: 0x6)
Info : r9a07g044l.a55.0: hardware has 6 breakpoints, 4 watchpoints
Info : r9a07g044l.a55.0 cluster 0 core 0 multi coreInfo : [r9a07g044l.a55.0] Examination succeedInfo : [r9a07g044l.axi_ap] Examination succeed
Info : starting gdb server for r9a07g044l.a55.0 on 3333
Info : Listening on port 3333 for gdb connections
Info : starting gdb server for r9a07g044l.m33 on 3334
Info : Listening on port 3334 for gdb connections
Info : gdb port disabled
Open On-Chip Debugger 0.11.0+dev-00663-gd1e14abdb-dirty (2022-05-10-07:54) Licensed under GNU GPL v2 For bug reports, read http://openocd.org/doc/doxygen/bugs.htmlr9A07g043u.cpu Info : Listening on port 6666 for tcl connections Info : Listening on port 4444 for telnet connections Info : J-Link Lite V9 compiled Feb 2 2021 16:32:48 Info : Hardware version: 9.00 Info : VTarget = 1.819 V Info : clock speed 4000 kHz Info : JTAG tap: r9A07g043u.cpu tap/device found: 0x1000563d (mfg: 0x31e (Andes Technology Corporation), part: 0x0005, ver: 0x1) Info : datacount=4 progbufsize=8 Info : Examined RISC-V core; found 1 harts Info : hart 0: XLEN=64, misa=0x800000000094312d Info : starting gdb server for r9A07g043u.cpu on 3333 Info : Listening on port 3333 for gdb connections
Note that the "DAP transaction stalled" messages are normal and do not affect the functionality.
Start debugging
Now that openocd command has succeeded, you can use GDB on your Linux Host PC and attach to GDB Server created by OpenOCD. Note that on the Linux machine there might be several instances of GDB, including the native GDB (x86_64). In order to debug the Cortex-A55 the Arm AArch64 cross GDB has to be used, normally the one included in the SDK generated by Yocto, target: aarch64-poky-linux. For the Cortex-M33, instead the target has to be arm-none-eabi (to be installed separately).
$ source /opt/poky/3.1.5/environment-setup-aarch64-poky-linux
$ $GDB
GNU gdb (GDB) 9.1
Copyright (C) 2020 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-pokysdk-linux '''--target=aarch64-poky-linux'''".
Type "show configuration" for configuration details.
For bug reporting instructions, please see:
<http://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".
Instead of the gdb included in the SDK and generated by Yocto, you can also install a newer Arm toolchain, for example Version 13.2.Rel1 and launch the corresponding gdb:
$ aarch64-none-linux-gnu-gdbGNU gdb (Arm GNU Toolchain 13.2.rel1 (Build arm-13.7)) 13.2.90.20231008-gitCopyright (C) 2023 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-pc-linux-gnu --target=aarch64-none-linux-gnu".Type "show configuration" for configuration details.For bug reporting instructions, please see:<https://bugs.linaro.org/>.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".(gdb)
In case of RISC-V there are different options, assuming the GDB that comes with Yocto SDK is used (riscv64-oe-linux-gdb):
$ source /opt/poky/oecore-x86_64/environment-setup-riscv64-oe-linux
$ $GDB
GNU gdb (GDB) 9.1
Copyright (C) 2020 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-oesdk-linux --target=riscv64-oe-linux".
Type "show configuration" for configuration details.
For bug reporting instructions, please see:
<http://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".
Different ports are potentially created for the different cores available in the device. For the example above GDB can connect to the port 3333 for the Cortex-A55 (configured in SMP by default) or RISC-V Andes AX45MP and port 3334 for the Cortex-M33.
(gdb) target remote localhost:3333
Remote debugging using localhost:3333
warning: No executable has been specified and target does not support
determining executable automatically. Try using the "file" command.
0x0000000050000000 in ?? ()
(gdb)
A message similar to the one shown above means that GDB managed to connect to the target and it is ready to accept further commands to debug.
Debug Flash Writer using GDB Text User Interface (TUI)
In the recent versions of GDB the Text User Interface is built in by default. This provides a convenient way to quickly debugging effectively the code without having to rely on more complex graphical user interfaces. For example the aforementioned 13.2.Rel1 does include the TUI that can be activated by running GDB with the -tui flag:
aarch64-none-linux-gnu-gdb -tui
To quickly debug a bare metal code like Flash Writer (here we assume it was previously built), TUI is a very convenient option.
Connect to the openOCD instance (that should be already running):
(gdb) target extended-remote localhost:3333Remote debugging using localhost:3333warning: No executable has been specified and target does not supportdetermining executable automatically. Try using the "file" command.0x000000000005688 in ?? ()Load Flash Writer code and symbols:
(gdb) load ~/PATH_TO_FLASH_WRITER/AArch64_output/Flash_Writer_RZxxx_SMARC_xxDDRx.axfLoading section .cert, size 0x200 lma 0xa1e00Loading section .text, size 0x25780 lma 0xa2000Loading section .data, size 0x980 lma 0xc7780Start address 0x00000000000a2000, load size 156416Transfer rate: 162 KB/sec, 13034 bytes/write.(gdb) symbol-file ~/PATH_TO_FLASH_WRITER/AArch64_output/Flash_Writer_RZxxx_SMARC_xxDDRx.axfReading symbols from ~/PATH_TO_FLASH_WRITER/AArch64_output/Flash_Writer_RZxxx_SMARC_xxDDRx.axf...Set breakpoint at Main:
(gdb) b MainBreakpoint 1 at 0xa2048: file main.c, line 50.Run till Main:
(gdb) cContinuing.Breakpoint 1, Main () at main.c:5050 init_tzc_400_xspi();
Then something like this should appear:
There are many guides online on how to use GDB but we can say that the most frequently used commands are b or break, c or continue, n or next (step over), s or step (step into). Then you can hit CTLR + c to break the target if running.
Printf style debugging using OpenOCD
Normally once you have OpenOCD and Eclipse running and you can enjoy the modern features to debug your code: breakpoints, watchpoints, stepping thru the code, etc.
However in some circumstances (legacy, no UART, etc) you may still want to use printf to debug the code using the JTAG interface.
As of today expensive debug tools like Lauterbach do fully support the so called Arm semihosting, actually most of debug tools do support Arm semihosting for 32-bit targets. However there are very few tools that can support AArch64 semihosting. AArch64 is a completely new architecture and semihosting has been redefined and specified in much more detail. So apart from Lauterbach, OpenOCD is one of the few tools that can fully support AArch64 semihosting.
If you used semihosting in the past, enabling it for AArch64 is not that different:
the project should use the standard Arm C libraries
any IO function like _write or _read, as well as syscalls shall be excluded from the build
--specs=rdimon.specs shall be used as linker flag
initialise_monitor_handles()function shall be called before using standard input / output function only once. In doing so,<stdio.h>and<stdlib.h>shall be included andvoid initialise_monitor_handles (void)shall be declared as anextern
After the call initialise_monitor_handles() function, any printf or scanf function can be used and they will be redirected to the OpenOCD debugger window. As per AArch64 specification, eventually any scanf/printf will end up in a hlt 0xf000 instruction, that is "captured" by OpenOCD and handled accordingly. It's worth noting that semihosting shall be enabled in OpenOCD using the command: arm semihosting enable.
For example, for a bare metal Hello World application with semihosting enabled, this simple gdb script can be used (manually rest the target first):
target remote localhost:3333
mon halt
mon arm semihosting enable
set $pc = 0x12000
c
This assumes that the application entry point is located at 0x12000.
The OpenOCD output on the RZ/G2L will be something like:
Info : r9a07g044l.a55.0: hardware has 6 breakpoints, 4 watchpoints r9a07g044l.a55.0 halted in AArch64 state due to debug-request, current mode: EL3H cpsr: 0x400003cd pc: 0x20021f40, semihosting MMU: disabled, D-Cache: disabled, I-Cache: disabled Hello World!
Arm semihosting minimal helper functions
If your code does not use standard C libraries, it is possible to use two minimal helper functions to input and/or output data using semihosting:
static inline int sh_readc(void) {
register long x0 asm("x0") = 0x07;
asm volatile ("hlt #0xF000" : "+r"(x0) :: "memory");
return (char)x0;
}
static inline void sh_write0(const char *s) {
register long x0 asm("x0") = 0x04;
register const char *x1 asm("x1") = s;
asm volatile ("hlt #0xF000" : "+r"(x0), "+r"(x1) :: "memory");
}
void test(void) {
const char *str = "Hello Semihosting!";
sh_write0(str);
char c = (char)sh_readc();
}
Obviously it is always necessary to instruct openOCD with arm semihosting enable or via GDB mon arm semihosting enable.