Using the ITM console for printf redirects and LWIP debug messages

[STea]

Introduction

This article provides a step-by-step guide on how to use the Instrumentation Trace Macrocell (ITM) console to redirect print statements and LWIP debug messages in STM32CubeIDE. These tools are valuable for debugging and optimizing your applications involving LWIP middleware. Moreover, networking applications such as Ethernet based applications. 

You may already have an application where you need to enhance its debuggability and trace your potential issues. If you're trying to test this from scratch, we provide you with a quick and useful tutorial. You can find the working example with all the modifications on GitHub here: GitHub: stm32-hotspot. 

1. Prerequisites

Hardware:

• An STM32 development board (we use the NUCLEO-F439 as an example).

Software:

• STM32CubeIDE v1.16
• STM32CubeMX v1.12

2. Configuring the ITM console for printf redirections

2.1. Steps to configure the ITM in STM32CubeIDE

1. Open your project in STM32CubeIDE.

2. Open main.c and include the following headers:

#include <stdio.h>

3. Redirect printf to ITM by adding the following function:

int _write(int file, char *ptr, int len) {
    for (int i = 0; i < len; i++) {
        ITM_SendChar((*ptr++));
    }
    return len;
}

After these steps, you should be able to view printfs in your ITM console. This can be done by adding a printf call in your while(1) loop to test this feature. 

2.2. Enable the ITM console in STM32CubeIDE

1. Go to [Run] -> [Debug Configurations].
2. Select your debug configuration and go to the [Debugger] tab.
3. Tick the [Enable] box underneath [Serial Wire View (SWW)].
4. Set the clock speed to match the clock speed used in your application.
5. Click [Apply] and [Debug].

6. After the debug section is opened, open the SWV ITM Data Console by accessing [Window] -> [Show View] -> [Other] -> [SWV] -> [SWV ITM Data]. 

7. Check the configuration as seen in the image below, and start the process by clicking the red dot on the top-right corner. 

3. Redirecting LWIP debug messages

Assuming the steps in section 2 are applied, we can enable the debug capabilities.  

1. Open lwipopts.h and add the following macro:

#define LWIP_DBG_MIN_LEVEL LWIP_DBG_LEVEL_ALL
define ETHARP_DEBUG LWIP_DBG_ON
/*----- Default Value for NETIF_DEBUG: LWIP_DBG_OFF ---*/
#define NETIF_DEBUG LWIP_DBG_ON
/*----- Default Value for PBUF_DEBUG: LWIP_DBG_OFF ---*/
#define PBUF_DEBUG LWIP_DBG_ON
/*----- Default Value for API_LIB_DEBUG: LWIP_DBG_OFF ---*/
#define API_LIB_DEBUG LWIP_DBG_ON
/*----- Default Value for API_MSG_DEBUG: LWIP_DBG_OFF ---*/
#define API_MSG_DEBUG LWIP_DBG_ON
/*----- Default Value for SOCKETS_DEBUG: LWIP_DBG_OFF ---*/
#define SOCKETS_DEBUG LWIP_DBG_ON
/*----- Default Value for ICMP_DEBUG: LWIP_DBG_OFF ---*/
#define ICMP_DEBUG LWIP_DBG_ON
/*----- Default Value for IGMP_DEBUG: LWIP_DBG_OFF ---*/
#define IGMP_DEBUG LWIP_DBG_ON
/*----- Default Value for INET_DEBUG: LWIP_DBG_OFF ---*/
#define INET_DEBUG LWIP_DBG_ON
/*----- Default Value for IP_DEBUG: LWIP_DBG_OFF ---*/
#define IP_DEBUG LWIP_DBG_ON
/*----- Default Value for IP_REASS_DEBUG: LWIP_DBG_OFF ---*/
#define IP_REASS_DEBUG LWIP_DBG_ON
/*----- Default Value for RAW_DEBUG: LWIP_DBG_OFF ---*/
#define RAW_DEBUG LWIP_DBG_ON
/*----- Default Value for MEM_DEBUG: LWIP_DBG_OFF ---*/
#define MEM_DEBUG LWIP_DBG_ON
/*----- Default Value for MEMP_DEBUG: LWIP_DBG_OFF ---*/
#define MEMP_DEBUG LWIP_DBG_ON
/*----- Default Value for SYS_DEBUG: LWIP_DBG_OFF ---*/
#define SYS_DEBUG LWIP_DBG_ON
/*----- Default Value for TIMERS_DEBUG: LWIP_DBG_OFF ---*/
#define TIMERS_DEBUG LWIP_DBG_ON
/*----- Default Value for TCP_DEBUG: LWIP_DBG_OFF ---*/
#define TCP_DEBUG LWIP_DBG_ON

You can select one of the elements that you want to see it is debug message, and you can select which level of debug you want to visualize:

The element of the LWIP stack from which you want to get returns can be selected in the STM32CubeMX debug menu config of LWIP:

Make sure that the right call of printf is redirected with the LWIP_PLATFORM_DIAG macro in the arch.h file. 

/** Platform specific diagnostic output.\n
 * Note the default implementation pulls in printf, which may
 * in turn pull in a lot of standard libary code. In resource-constrained 
 * systems, this should be defined to something less resource-consuming.
 */
#ifndef LWIP_PLATFORM_DIAG
#define LWIP_PLATFORM_DIAG(x) do {printf x;fflush(0);} while(0)
#include <stdio.h>
#include <stdlib.h>

After this, you can see debug messages of the LWIP stack in your ITM console.

You can also extract them from the SWV export folder in your project for further investigation and analysis if needed.

The combination of this tool with FreeRTOS™ can help immensely in the debugging process.

You can refer to the following article showing a how to of FreeRTOS™ debugging: How to enable FreeRTOS™ Run Time and Stack Usage view

Conclusion

By following these steps, you can effectively use the ITM console to redirect print statements and LWIP debug messages. These tools help you gain deeper insights into your applications behavior and facilitate efficient debugging and optimization.

Related links

• GitHub: stm32-hotspot 
• Knowledge article: How to enable FreeRTOS™ Run Time and Stack Usage view