1. Introduction
When developing embedded software based on a real-time operating system (RTOS), a good understanding of the runtime behavior can save your time when debugging and validating your application. Following pages introduce how to use Tracealyzer tool from Percepio company. Tracealyzer tool is an advanced software tracing designed for RTOS-based application. In our case, RTOS is FreeRTOS.
Tracealyzer tool uses software-based run time tracing called snapshot mode, and no special tracing hardware is required.
However, Tracealyzer tool can be coupled with external probe like IAR I-Jet probe or J-Trace probe from Segger for fast trace streaming. Streaming mode is out of scope of this presentation.
1.1. Tracealyzer tool
To see and exploit the traces, Tracealyzer tool installation is required.
This one can be downloaded from https://percepio.com/tracealyzer/.
1.2. Trace recording
To trace the behavior of an embedded system there are two ways:
- Streaming mode: record data continuously and send them to the PC running Tracealyzer tool. Not tested and therefore not deployed.
- Snapshot mode: store in an on-target RAM buffer and transfer when the system is halted this on-target RAM buffer to the PC running Tracealyzer tool.
The drawing below gives an overview of the snapshot race buffer management:
2. Getting started
To be able to use the Percepio trace recorder feature, trace recorder component must be enabled in X-CUBE-ST67W61 component selector window.
This import can be also done manually in using the Tracerecorder source code.
2.1. Debug trace recorder selection
By using STM32CubeMX tool software packs:
- Select the X-CUBE-ST67W61 component in the Software pack
- Check the radio button "Debug TraceRecorder"
By selecting this option, the code generator of STM32CubeMX will import the TraceRecorder component.
To have a complete view and understanding of the project generator please refer to:
the how to generate a project with STM32CubeMX
2.2. TraceRecorder component
Having generated the project, all the TraceRecorder files are located under Middleware directory. Do not forget to enable the TraceRecorder group at IAR workspace level.
To activate the associated TraceRecorder pieces of code, you have to define a dedicated "SYS_DBG_ENABLE_TA4=1" preprocessor symbol
2.3. User code instrumentation
2.3.1. FreeRTOSConfig.h
The code lines must be put at the end of the FreeRTOSConfig.h file to connect the task hooks of FreeRTOS on the TraceRecorder functions:
#if !(SYS_DBG_ENABLE_TA4 >= 1) /* Disable the task_perf hooks from util_task_perf.c performance utility */ #define traceTASK_SWITCHED_IN task_perf_in_hook #define traceTASK_SWITCHED_OUT task_perf_out_hook #endif /* SYS_DBG_ENABLE_TA4 */ /* TA4 recorder library */ #if (configUSE_TRACE_FACILITY == 1) && (SYS_DBG_ENABLE_TA4 >= 1) #include "trcRecorder.h" #endif /* configUSE_TRACE_FACILITY & SYS_DBG_ENABLE_TA4 */
This user code will only be enabled if "SYS_DBG_ENABLE_TA4=1" is defined.
2.3.2. MX_FREERTOS_Init()
To activate the "TraceRecorder" feature, code has to be instrumented. The code below shows the two needed functions to be call during the initialization of the project before FreeRTOS initialization is done. For example, Code has to be placed under the user code section of the MX_FREERTOS_Init() function.
#include "trcRecorder.h"
/**
* @brief FreeRTOS initialization
* @param None
* @retval None
*/
void MX_FREERTOS_Init(void) {
/*...*/
#if (SYS_DBG_ENABLE_TA4 >= 1)
/*Initialise the trace recorder library*/
xTraceInitialize();
trace_init();
#endif /* SYS_DBG_ENABLE_TA4 */
/*...*/
}
2.3.3. Starts the tracing directly
After initialization is done, it is up to the user to find the right entry point within application to start the trace recording using xTraceEnable(TRC_START) Percepio TraceRecorder built-in function.
#include "trcRecorder.h"
void MyAppFunc(void)
{
/* some application code ...*/
/* start trace recording here */
if (xTraceEnable(TRC_START) != TRC_SUCCESS) {
/* treat error */;
}
/* ... some application code*/
}
2.3.4. Additional trace message
You also have the possibility to add specific trace message. Below example (extract from ST67W6X_CLI project) of added message.
/**
* Called in the thread control loop of the low level driver of the logging component when data are received or
* the timeout is expired. When (bytes > 0) new data have been received
*/
#define TRACE_LOG_TH_DID_RECEIVE_TX_DATA(bytes) \
if (((bytes) > 0) && xTraceIsRecorderEnabled()) \
{ \
vTracePrintF(LOG_TA4_EVT, "new tx data"); \
}
/**
* Called in the thread control loop of the low level driver of the logging component when a new log message is received or
* the timeout is expired. When (bytes > 0) new data have been received
*/
#define TRACE_LOG_TH_DID_RECEIVE_MSG(bytes) \
if (((bytes) > 0) && xTraceIsRecorderEnabled()) \
{ \
vTracePrintF(LOG_TA4_EVT, "new log msg"); \
}
2.4. Getting to start with IAR
Here is short description how to install and how to use the necessary macro function in IAR IDE environment to get back the trace for Tracealyzer tool.
In the following macro definition (in save_trace_buffer.mac), the trace file (trace.hex) will be saved in the current project directory.
__var start;
__var end;
save_trace_buffer()
{
start = __smessage "Memory:0x",RecorderDataPtr:%x;
end = __smessage "Memory:0x",(RecorderDataPtr + 1):%x;
__memorySave(start,end,"intel-extended", "$PROJ_DIR$\\trace.hex", 1);
return 0;
}
The picture below shows how to set-up the macro in the the IAR Debugger (option panel)
After project execution, the trace.hex data file is recorded in the current project directory.
For more and complete details:
Percepio Tracealizer - getting started for IAR
2.5. Getting to start with other IDE
For complete details, follow the link corresponding to the chosen IDE:
Percepio Tracealizer - getting started for STM32CubeIDE
Percepio Tracealizer - getting started for MDK-ARM
2.6. Display the snapshot trace file
In snapshot mode, open the Tracealyzer software tool and load the file trace.hex or trace.bin (depending on the IDE description) generated by the dump procedure explained above (in our description it is trace.hex).
Here below possible standard views proposed by Tracealyzer tool.
