How to trace FreeRTOS based applications?

Tracing allows recording the software behavior during runtime for later analysis of collected trace data. Tracing is especially important for systems integrating an operating system (OS), like FreeRTOS for embedded systems. FreeRTOS feature is multi-threading – the ability to run multiple programs (threads) on a single processor core by rapidly switching among execution contexts. Multi-threading, however, makes software behavior more complex, and gives the developer less control over run-time behavior as execution is preempted by the scheduler. 

There are 2 ways of how you can trace the run-time behavior of FreeRTOS applications: logging functionality and visual tracing.

Logging functionality is mostly done by trace hook macros mechanism. Trace hook macros are empty macros within the FreeRTOS source code that an application can re-define for the purpose of providing application- specific trace facilities. These macros can be used to:

  • Set a digital output to indicate which task is executing – allowing a logic analyzer to be used in order to view and record the task execution sequence and timing.
  • Similarly – setting an analogue output to a voltage that represents which task is executing – allowing an oscilloscope to be used in order to view and record the task execution sequence and its timing.
  • Logging task execution sequences, task timing, RTOS kernel events, and API calls for offline analysis via command line(using standard interfaces for transfer of events: uart, spi, i2c, etc.) .

As it may be easier to implement this method, traced data, however, can be hard for users to track. There is a slowdown in the process of finding system corruption by only looking at a logical analyzer, oscilloscope, or command line interface.

Visual trace diagnostics can be viewed as a surveillance camera for your FreeRTOS application that allows you to see a timeline of software events, spot issues at high level overviews, and drill down into sequencing details. This is often a valuable approach for debugging, verification, and optimisation of FreeRTOS applications. There are some applications that can analyze and visualize traced data,  while the target keeps running, such as: Tracealyzer from Percepio, Trace Compass free Eclipse plugin, SystemView by SEGGER, etc. As additional libraries are integrated to your application for tracing, it can  cause  a slowdown  in the overall system and, also, take too much  space in small embedded memory. Regardless of downsides, visual tracing is a powerful and human-friendly way of debugging. 

Which application you will decide to use in your system for visual tracing is out of this scope. For example,  in order to understand how to build FreeRTOS with a visual tracing mechanism, I made example projects with the SEGGER SystemView real-time recording and visualization tool. SEGGER SystemView has a free non-commercial license and there is a good support community.  Also, these examples are done using a NXP mimxrt1170 evaluation board and an ST nucleo-f413zh board, so you can distinguish the steps of porting SystemView library that are the same for every board and those that are board-specific. Traced events are sent via the UART interface from board to host application (see image below).

            Tracing FreeRTOS with SEGGER SystemView using UART interface

Link to the git repository of tracing FreeRTOS based applications is:

In both examples you can find the file that gives you a step-by-step explanation of  how to run your FreeRTOS with the SEGGER SystemView library. Here is an overview of file:

  • Steps from 1 to 10 are the same for every board, configuring FreeRTOS and SEGGER SystemView libraries to work with each other. 
  • Steps from 11 to 14 are platform specific. You have to configure the UART module in “interrupt” mode in order to be able to send and receive SEGGER events. This can be easily done by copying uart_segger.c file from /root_of_FreeRTOS_and_SEGGER/SEGGER/SystemView/Rec/ location(whereas root_of_FreeRTOS_and_SEGGER stands for the start location of FreeRTOS and SEGGER SystemView libraries) and modifying it to match your needs (maybe you have to change the initial function of UART or interrupt routine). Just follow the instruction steps in the file and then make your adjustments.
  • Step 15 is enabling the tracing counter(I used Cortex-M built-in Debug WatchPoint and Trace(DWT) counter).
  • Step 16 is running SEGGER SystemView host application with target platform. 


Hope that this can save your precious time of configuring and tracing FreeRTOS system and increase time of debugging.

Contact Us

Please, enter your details below. We will get back to you as fast as we can.

This website uses cookies to ensure you get the best experience on our website.

Get Cogita

Please, enter your details below. We will get back to you as fast as we can.

Thank you!

We will get in touch soon.

Get a Quote

Please, enter your details below. We will get back to you as fast as we can.