Debugging Synergy Applications: Getting Started with the ITM

There are so many different advanced debugging techniques that are available to developers today that it is nearly impossible to select a good starting point. A great jumping off point though is to discuss the Instruction Trace Macrocell (ITM) since it can bridge the gap between traditional debugging techniques and more advanced techniques. As we discussed in the last post, the ITM is a hardware module that allows a developer to send printf style messages through hardware far faster and efficiently than using a UART or semi-hosting. In today’s post, we will dive into the ITM and look at how we can get it setup in the Renesas Synergy™ development environment.

The ITM contains 32 separate stimulus ports that can be used to separate debug, data and trace messages. Arm recommends that developers use port 0 for printf style messages and port 31 for RTOS event messages. Everything in between can be used for whatever purpose a developer decides is necessary such as outputting sensor data on port 1 or a Wi-Fi communication status state on port 2. Each port shares a common ITM buffer that typically contains a maximum of 10 bytes. In most cases, the ITM can be read out very quickly by the debugger in timeframes less than a microsecond!

The Arm CMSIS standard contains some predefined functions for transmitting information using the ITM. These functions include:

  • ITM_SendChar
  • ITM_ReceiveChar
  • ITM_CheckChar

The function that is most commonly used by developers is the ITM_SendChar function. ITM_SendChar is a simple function that accepts a single parameter that is a character to be transmitted through the ITM then back through the SWO pin to the debugger which then displays it in the ARM Coresight ITM Live Trace Console in the ISDE. It is important to note that by default, the Arm CMSIS code uses only the ITM Stimulus 0 port. A developer wanting to use other ports would need to write their own custom functions.

Transmitting a character is fairly simple. For example, if a developer wants to transmit the character ‘A’ into the BlinkyLed application every time the LEDs blink, they would insert the following code into their blinky_thread_entry function in the primary loop:

ITM_SendChar(‘A’);

At this point, compiling the project will include the capability to transmit the ‘A’ to the ITM console but not until the developer sets up their debugging toolchain to receive ITM messages. There are several steps that a developer must first go through in order to setup the ITM trace.

First, in the debug configuration for the project, a developer needs to click on the Debugger tab and then under Connections make sure that the Serial Wire Viewer (SWV) Core clock frequency is set to 120 MHz for the SK-S7G2 board. Setting the SWV setting lets the debugger know that data will be coming back over the Serial Wire Output (SWO) pin.

 

Once the settings are configured, a developer can start the debug session. The ARM CoreSight ITM Trace Console now needs to be setup to enable messages on stimulus port 0. This can be done by opening the CoreSight ITM Console by clicking Renesas Views -> Debug -> ARM CoreSight ITM Trace Console. Once the console is open, a developer can click the settings tab to reveal the ITM settings as shown below:

 

By default, a developer will see that all the settings are disabled. To enable port 0, simply click the checkbox next to the 0. A developer can easily enable or disable the ITM Stimulus Ports by just checking or unchecking the boxes. Once this is done, a developer clicks OK and starts running their application code. If everything goes as expected, the console will begin displaying the letter A every time that the LED changes state as shown below:

 

In the next post, I’ll show you how to redirect printf so that all the printf messages are output on the ARM CoreSight ITM Live Trace Console along with how to create functions that can use the other ITM stimulus ports.

Until next time,

Live long and profit!

Professor_IoT

 

Hot Tip of the Week

Don’t forget to check periodically for video tutorials on the Synergy Platform.  You can find all the Renesas Synergy videos in one convenient location here: https://www2.renesas.eu/videos/america.html

The Synergy tutorial playlist is here: https://www2.renesas.eu/videos/america.html?p=177

Two of the tutorials cover Debugging:

Basic Debugging: https://www2.renesas.eu/videos/america.html?p=177&v=B6TvpS1Kyp4

Advanced Debugging: https://www2.renesas.eu/videos/america.html?p=177&v=HmKiCZA0XoU

View both these short videos to see additional debugging capabilities that will get your development projects done quicker and easier. This assumes you will have some bugs in your code. Probably a good assumption…