This guide is for v4.6 and later for the recorder and for use with FreeRTOS version 7.3 or later.
Copy the files into your project. The folder structure is a bit different depending on if the code is copied from the Tracealyzer installation directory or from the official git repository.
If the code is copied from the installation directory of Tracealyzer all files should be copied from the selected RTOS folder and the include and config subfolders.
If the code is copied from the git repository all c and h files should be copied into your project from the folders described below.
/ /config /include /kernelports/selected RTOS /kernelports/selected RTOS/config /kernelports/selected RTOS/include
Make sure to add the path to the h files to the compilers “include paths” so the compiler can find them. This step is different depending on your development environment.
In trcConfig.h set
TRC_CFG_HARDWARE_PORTto the architecture used. For some hardware ports an
#includeof the processors header file needs to be done by replacing the row
#error "Trace Recorder: Please include your processor's header file here and remove this line.". If the error line is removed and your project compiles the header file isn’t needed. All available hardware ports can be found at the bottom of trcDefines.h.
TRC_CFG_FREERTOS_VERSIONneeds to be set in trcKernelPortConfig.h.
configUSE_TRACE_FACILITYneeds to be set to 1 and
#include "trcRecorder.h"needs to be included at the end of the file as described below.
/* Integrates the Tracealyzer recorder with FreeRTOS */ #if ( configUSE_TRACE_FACILITY == 1 ) #include "trcRecorder.h" #endif /* Note: Since FreeRTOSConfig.h is also included from some FreeRTOS assembly files, depending on your IDEs you may need to use a conditional include, like in the examples below.*/ /* IAR Embedded Workbench */ #ifndef __IASMARM__ #if ( configUSE_TRACE_FACILITY == 1 ) #include "trcRecorder.h" #endif #endif /* Microchip MPLAB X IDE */ #ifndef __LANGUAGE_ASSEMBLY #if ( configUSE_TRACE_FACILITY == 1 ) #include "trcRecorder.h" #endif #endif
xTraceEnable(TRC_START) in your main function to initialize and start the recorder. This must be done after the initial hardware setup, but before any RTOS objects (tasks etc.) have been created.
xTraceInitialize() can be used to only initialize the trace system and then
xTraceEnable() can be used later when appropriate. Other start options for xTraceEnable are described in trcRecorder.h.
Configure the project for snapshot or streaming as mentioned below.
For hardware ports that uses the same time source as FreeRTOS tick interrupt (for example the hardware port for Pic32/24 and Cortex-A9)
xTraceInitialize()needs to be called in the main function before any RTOS objects are created. Then
xTraceEnable()needs to be called after the kernel has started. This ensures that the clock used for timestamps have been correctly configured by FreeRTOS.
In snapshot mode, the trace data is stored in a local RAM buffer on the target device, that later can be read from the host. The recorder can be configured to stop when the buffer is full or overwrite the start when the buffer is full.
Copy the files from the RingBuffer folder, located in the streamports folder, into your project. Make sure to include all .c files and the header files from the Config and Include folders.
For FreeRTOS make sure
TRC_CFG_RECORDER_MODEis set to
TRC_RECORDER_MODE_STREAMINGin trcKernelPortConfig.h. As of v4.6 this is the default mode, and (despite the name) it supports both streaming and snapshots.
For streamport-specific settings see trcStreamPortConfig.h
TRC_CFG_STREAM_PORT_BUFFER_SIZEdecides the size of the trace buffer that is stored in RAM.
TRC_CFG_STREAM_PORT_RINGBUFFER_MODEcan be set to
TRC_CFG_STREAM_PORT_RINGBUFFER_MODE_OVERWRITE_WHEN_FULLfor continuously recording or
TRC_CFG_STREAM_PORT_RINGBUFFER_MODE_STOP_WHEN_FULLfor stopping when the buffer is full.
Now the project should compile and write the data to the ring buffer, from which snapshots can be made when the target is halted.
Reading a snapshot¶
There are a few ways to read a snapshot. More informantion is found in the Tracealyzer User Manual, but for convinience we provide two examples below - the Percepio plugins for Eclipse and MLAB X IDE. But basically you can use any method to save the contents of the RAM buffer to a .hex file or .bin file, and simply open the dump in Tracealyzer.
The Ecplipse plugin can be found on Eclipse Marketplace. This plugin will work for most versions of Eclipse. After the plugin has been installed the Percepio option can be found in the toolbar. To save a snapshot, start a debugging session, halt the application and then select Percepio -> Save Snapshot.
The MPLAB x plugin can be downloaded here then it can be installed following these instructions. To save a snapshot first open the Tracealyzer plugin by going to Tools -> Embedded -> Tracealyzer Export Plugin. Then start a debugging session, halt it, and press the “Save Trace” button.
Streaming is a method where the trace data are offloaded from the target continuously, this means that a streaming trace can run for hours or even days depending on the setup. The different streaming methods included can be found in the stream ports folder. If there are no stream ports available that works with the target and/or application a custom stream port can be made, as long as an interface with high enough bandwidth is used.
Follow the below steps to integrate a stream port:
Copy the files from the selected stream port into the project.
For FreeRTOS make sure
TRC_CFG_RECORDER_MODEis set to
For stream port specific settings see trcStreamPortConfig.h
Now the project should compile and streaming can be started using the selected interface.
SEGGER J-Link Streaming¶
For SEGGER J-Link streaming a proprietary feature called RTT, Real-Time Transfer, from SEGGER is used. This method uses a RAM buffer that can be read by the J-Link debugger during run time. After the files have been included in the project from the Jlink_RTT folder as described in the streaming section the different configurations can be changed in trcStreamPortConfig.h. The different settings are:
TRC_CFG_STREAM_PORT_USE_INTERNAL_BUFFER, decides if an extra internal buffer should be used. This should be turned off in most cases when using this port.
TRC_CFG_STREAM_PORT_INTERNAL_BUFFER_SIZE, sets the size of the internal buffer.
TRC_CFG_STREAM_PORT_RTT_UP_BUFFER_SIZE, sets the size of the dedicated RTT output buffer.
TRC_CFG_STREAM_PORT_RTT_UP_BUFFER_INDEX, defines the buffers RTT channel. 0 is reserved for for built in RTT functions and shouldn’t be used.
TRC_CFG_STREAM_PORT_RTT_DOWN_BUFFER_INDEX, defines the RTT buffer channel for incoming data.
TRC_CFG_STREAM_PORT_RTT_MODE, can be set to
SEGGER_RTT_MODE_NO_BLOCK_SKIP. Where the first one will block the system until the whole buffer is cleared, this may disturb the real-time behavior of the system. The second option will generate missed events if the interface isn’t fast enough to clear the buffer.
TRC_CFG_STREAM_PORT_RTT_NO_LOCK_WRITE, sets if RTT should write without locking or not. This should normally be disabled.
To connect to the target from Tracealyzer open the settings and go to J-Link settings. Set the debugger, speed, interface and device to match the target.
Go to PSF Streaming Settings and select SEGGER RTT as target connection. Sometimes the J-Link drivers can’t find the RTT control block then the address needs to be set manually, it should be the address of
_SEGGER_RTT from the target. The up and down buffer index should be set as the same as set in trcStreamPortConfig. If the argument
TRC_START is used when calling
xTraceEnable in the application the Target Starts Tracing box should be checked, otherwise it should be empty.
When all the settings are set the settings window can be closed, now the streaming can be started by pressing the connect button in the Live Stream window followed by pressing the Start Session button. If everything is set up correct data should now be received from the target.