Adding Trace Capability To Your RTOS Application

Using FreeRTOS+Trace

Introduction

FreeRTOS+Trace has two components:

Trace Recorder Source Files:
The trace recorder is responsible for collecting trace data and runs on the target hardware as part of your RTOS application. It is provided as C source code in the main FreeRTOS .zip file download.
FreeRTOS+Trace PC Application:
Trace recordings are viewed in the FreeRTOS+Trace PC application.

This page provides quick start instructions only. Refer to the help menu in the FreeRTOS+Trace application for more detailed information.

Steps to trace enable your RTOS application:

Add the trace recorder source files into your RTOS project
Update your application to initialise the trace, then start and stop a trace recording
Extract a trace recording from the target for viewing in FreeRTOS+Trace

Add The Trace Recorder Source Files Into Your RTOS Project

The trace recorder source files viewed in the project that builds the FreeRTOS+Trace Win32 simulator demo

Inclusion of trcKernelPort.h in the same project. Click to enlarge.

The trace recorder source code is located in the /FreeRTOS-Plus/Source/FreeRTOS-Plus-Trace directory of the main FreeRTOS .zip file download.

The trace recorder requires a configuration header file called trcConfig.h. A template trcConfig.h file is located in the ConfigurationTemplate sub-directory.

Add the following trace recorder source files to a working FreeRTOS project:
1. trcBase.c
2. trcHardwarePort.c
3. trcKernel.c
4. trcKernelPort.c
5. trcUser.c
Add /FreeRTOS-Plus/Source/FreeRTOS-Plus-Trace/include to the compiler's include path.
Create a trcConfig.h configuration file by editing a copy of the template provided. Full instructions are provided in the comments within the header file itself.
Set configUSE_TRACE_FACILITY to 1 in FreeRTOSConfig.h.
Include the trcKernelPort.h header file at the bottom of your project's FreeRTOSConfig.h configuration file.

Depending on the port in use it may also be necessary to define the TRACE_ENTER_CRITICAL_SECTION() and TRACE_EXIT_CRITICAL_SECTION() macros. A #error in the source files will inform you if this is the case, and provide further instruction.

Also depending on the port and development environment it may be necessary to use the pre-processor to prevent the configuration file from being included from assembly files. For example, in IAR this can be done as follows...

/* The IAR C compiler automatically defines __ICCARM__. */ #ifdef __ICCARM__ #include "trcKernelPortFreeRTOS.h" #endif Preventing the RTOS trace header file from being included from assembly files when using the IAR compiler

...and in MPLAB it can be achieved as follows:

/* The MPLAB assembler automatically defines __LANGUAGE_ASSEMBLY. */ #ifndef __LANGUAGE_ASSEMBLY #include "trcKernelPortFreeRTOS.h" #endif Preventing the RTOS trace header file from being included from assembly files when using the MPLAB compiler

Update Your Application to Initialise the Trace, Then Start and Stop a Trace Recording

The trace recorder is initialised by calling vTraceInitTraceData(). The trace recorder must be initialised before any FreeRTOS API functions are called, so it is recommended to call vTraceInitTraceData() at the top of main().

To start a recording call uiTraceStart(). To stop a recording call vTraceStop(). It is not necessary to stop a recording before extracting the recorded data.

Extract a Trace Recording from the Target for Viewing in FreeRTOS+Trace

The recorded data is stored within the target hardware's RAM in a variable called RecorderData, which itself is pointed to by a variable called RecorderDataPtr. To view the recording it is necessary to dump the contents of the targets RAM to a disk file, from where it can be opened using FreeRTOS+Trace's File menu. The RAM that is saved to a file only needs to contain the RecorderData variable - it can start and end at any memory address because FreeRTOS+Trace will automatically find the recording within the saved data.

Most debuggers are able to save RAM contents to a file, and the FreeRTOS+Trace help file provides instructions on using the IAR, ST-Link, Rowley CrossStudio, Keil uVision, and Renesas HEW tools. There are a few other environments that have direct built-in or plug-in FreeRTOS+Trace support. These are listed below.

J-Link Users (all build environments and targets)
If you are using a J-Link debug interface then the recorded data can be retrieved directly from within FreeRTOS+Trace using the J-Link menu.

The J-Link menu item in FreeRTOS+Trace
Atmel Studio
If you are using Atmel Studio 6 then Atmel's MemoryLogger extension, available from the Atmel Gallery, automatically detects the path to FreeRTOS+Trace, if installed, and gives you a single-click upload and refresh. You can use the extension while debugging, and optionally get an automatic refresh of the trace data each time the MCU is halted.
MPLAB X
If you are using MPLAB X then an MPLAB plug-in allows you to save the recorded data to disk so it can be opened from within FreeRTOS+Trace.
To install the plug-in into MPLAB X:
1. Extract the .nbm file from the provided zip file.
2. In MPLAB, select Tools->Plugins, then in the Plugins dialog, select the Downloaded tab and then click Add Plugins...".
3. Select org-percepio-freertostraceplugin.nbm from the zip file.
4. Restart MPLAB and enable the plugin by selecting Tools->Embedded->FreeRTOS+Trace Plugin.
Eclipse
Finally, although Eclispe does not (yet) have built in support, as there are so many Eclipse users it is worth highlighting how to dump RAM to a disk in that environment. This is demonstrated in the image below (LPCXpresso shown in the image).

Using the memory export facility in Eclipse to save
the RAM that contains RecorderData to a disk file