This tutorial will show you how to use the Lauterbach TRACE32 GDB front-end debugger to debug your Portenta H7 application via GDB on a serial interface. It also explains how to obtain a free license of a fully functional version of TRACE32 using your Portenta's serial number.
In this tutorial you will load an application on the Portenta H7 board which includes the Monitor for Remote Inspection (MRI). This is a GDB compatible Serial Monitor which is included in the ThreadDebug sketch in the Arduino IDE Examples for Portenta H7 (M7 core) and in all examples in the TRACE32 demo directory of the TRACE32 installation. Throughout this document the double-tilde (~~) is used as a place holder for the directory where you unzipped the TRACE32 software.
This tutorial assumes that you have already installed the Arduino IDE and configured it to support the Portenta H7 board. Please refer to Setting Up Portenta H7 For Arduino before you proceed.
In order download the TRACE32 debugger open the Lauterbach download page in your browser. Download the zip file named Debugger for GDB target (Arduino Pro) which contains TRACE32 for Portenta-H7 and demo applications.
Extract the zip file to a directory of your choice. On Windows systems, please avoid C:\T32, because this is the default installation directory for the full TRACE32 distribution.
Without a valid license, the TRACE32 debugger only works for few minutes in demo mode. Lauterbach can generate a free license based on the serial number of your Portenta H7 board. The license will be valid for one year and can easily be renewed for free after this period using the same procedure. In order to obtain a license, please register here:
Enter the board's serial number (instructions below), your name and e-mail address and you will be sent your license key.
There are two alternative ways to detect the board serial number:
If you only see a 16 character (64-bit) long serial number, then you need to update your Arduino IDE and the "Arduino mbed-enabled Boards" core from the boards manager in the IDE. Details on how to do this can be found on the Arduino website. Also, make sure your Portenta H7 has the latest bootloader installed.
Either copy & paste the displayed serial number manually to the Lauterbach registration page or click on the provided link in the dialog window.
Note: Newer TRACE32 software version should automatically detect and show the board serial number, at first attach to the target.
When you receive the email containing your license key, follow the instructions provided at the end of the message:
To use the debugger, launch the appropriate executable for your host operating system. The executables can be found in the corresponding sub-directory for your operating system:
~~/bin/windows
for 32-bit Windows hosts~~/bin/windows64
for 64-bit Windows hosts~~/bin/linux
for 32-bit Linux hosts~~/bin/linux64
for 64-bit Linux hosts.For easy access, we suggest creating a link to the corresponding executable file on your desktop:
for Windows, this is t32marm.exe
for Linux, this is t32marm-qt
On Windows systems, the TRACE32 start-up script will automatically search for the right COM port attached to the Portenta H7 board.
On Linux systems, you will need to edit the system-settings.cmm file to manually add the serial port to connect to the Portenta H7 board. This is a text file and can be opened with your favorite text editor. Edit the line that defines &GDBPORT to refer to the serial port, for example:
&GDBPORT="/dev/ttyACM0"
. This must be done before you start the TRACE32 software. After changing the port you can start the TRACE32 debugger or re-start it in case it was open while you made the changes.The manual port setting is also useful for Windows systems where you have multiple Portenta H7 boards connected and you want to select a specific board to be used by TRACE32 for debugging. The automatic port selection is disabled when a &GDBPORT definition is found in
.system-settings.cmm
A number of pre-built demo programs are available. They can be accessed from the "Portenta H7 Demos" menu. The following instructions relate to the T32ThreadDebug example. However, the other examples follow a similar pattern.
The demo directory already includes the symbolic file (.elf) for debugging and the binary file (.bin) for Flash programming.
Select "T32ThreadDebug" from the "Portenta H7 Demos" menu and you will be presented with a dialog called "Elf File Selection". This is where the TRACE32 initial environment can be configured.
In this dialog, you can select which variant of the Arduino IDE you would like to use to source ELF files or if you want to use the current directory. To follow this tutorial please select "current dir".
The list to the right of the "Options" selection should then become populated with a number of available ELF files for downloading and debugging. Select the one you want with a double click. In this case select "T32ThreadDebug.ino.elf". This will also show file attributes such as date, time and size. To select an ELF file from a custom directory, click the "File" button underneath the "User's choice" field and browse for the desired ELF file. You can opt for changing the behavior of this script the next time it is executed.
If the application has already been programmed to Flash, for instance via the Arduino IDE or a previous TRACE32 session, select "Load debug symbols (program is already in Flash)" to prevent an unnecessary erase and write cycle of the on-chip Flash memory.
If the application has changed or does not match the contents of the Flash, then select "Flash program and load debug symbols".
Click the "OK" button to confirm all of your choices and start the session.
If the Flash is being programmed, TRACE32 will prompt you to double-click the reset button on the board to enable the bootloader mode. The built-in green LED of the Portenta fades in and out when in bootloader mode. Click the "OK" button to proceed. Diagnostic messages will be displayed in the TRACE32 AREA window whilst the erasing and programming take place.
The script will then attach to the Portenta H7 board and cause TRACE32 to open some debug windows. When everything is ready, you should see the Program Counter halted at the entry to the setup() function. You may now use the arrow buttons in the toolbar to step through the code and inspect the variables, registers, call stack etc.
In case of errors, please check the physical connection to the board, check if your host PC has detected the board's serial port and if this is the port configured in TRACE32. Reset the board and retry.
Take a look at the readme.txt file inside the demo directory for further information about the demo.
The provided demos or another project of your choice can be edited, compiled and flashed with the Arduino IDE. You can open for example the T32ThreadDebug.ino file with Arduino IDE, build and flash it. Flashing is also possible with TRACE32.
IMPORTANT: If you choose to program the Flash from within the Classic Arduino IDE, do not close the IDE after programming; leave it open. This is very important because, if you close the IDE, it cleans up the temporary build directory which includes the ELF file.
The demo directory contains a startup script which will copy the ELF file and the binary file in the current working directory. After the startup script was run you can safely close the Classic Arduino IDE if you don't need it anymore.
When you are done with flashing your application to the board, you can switch back to TRACE32. Select the type of Arduino IDE. If an ELF file is found, double-click to select it, then select "Load debug symbols (program is already in flash)" and click "OK".
You may also create a custom startup script for your own application. A minimal startup script is shown below. Copy it into a text file and save it with a file extension ".cmm". To execute it call the menu command "File-->Run Script..." from the TRACE32 GUI.
1SYStem.Down2SYStem.CPU PortentaH7-CM73SYStem.PORT <serial_port> ; e.g. COM8 (Windows) or /dev/ttyUSB0 (Linux)4SYStem.Option MMUSPACES ON5Break.CONFIG.METHOD.Program Onchip6
7SYStem.Mode Attach8
9Data.LOAD.Elf * /NoCODE10
11TASK.CONFIG ~~/demo/arm/kernel/rtxarm/v5/rtx.t3212MENU.ReProgram ~~/demo/arm/kernel/rtxarm/v5/rtx.men13
14List.auto15ENDDO
You can also copy the script start.cmm from the T32ThreadDebug demo directory to your working directory. For an application using the Serial Monitor, it is necessary to copy both start.cmm and term.cmm from the T32ThreadDebugPrint demo directory.
For each demo the corresponding start.cmm script comes with a predefined window layout. For your own layout, manually open and arrange the windows as you prefer, then save this window layout using the "Store Windows..." command in the Window menu. Save the file as win.cmm. It will be automatically found and used the next time you start a debugging session.
In this tutorial you learned how to acquire a free version of the TRACE32 GDB Front End debugger, fully licensed for Portenta H7 for one year. You learned how to start the debugger and debug some ready-to-run demos. Furthermore, you learned how to debug an application compiled with the classic Arduino IDE.
Lauterbach also provides hardware-based debug & trace tools. To learn more about them please visit:
In case the debugger encounters any issues while connecting to the Portenta, try the following:
On Ubuntu Linux, for example, you can install the Qt5 libraries using apt-get:
sudo apt-get install qt5-default
The user running the TRACE32 executable on Linux must have the permission to access serial devices. For example, in Ubuntu a temporary permission can be set as follows:
sudo chown :username /dev/devicename
You can also set a permanent permission adding the user to the "dialout" group. For example, in Ubuntu:
sudo adduser username dialout
Alternatively you can run the TRACE32 executable with root permissions.
Reviewed by: Maurizio Menegotto, Richard Copeman [2020-11-06]