Using FreeRTOS+Trace

Introduction

• 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:

1. Add the trace recorder source files into your RTOS project
2. Update your application to initialise the trace, then start and stop a trace recording
3. 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 requires a configuration header file called trcConfig.h. A template trcConfig.h file is located in the ConfigurationTemplate sub-directory.

1. 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

2. Add /FreeRTOS-Plus/Source/FreeRTOS-Plus-Trace/include to the compiler's include path.

3. 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.

4. Set configUSE_TRACE_FACILITY to 1 in FreeRTOSConfig.h.

5. Include the trcKernelPort.h header file at the bottom of your project's FreeRTOSConfig.h configuration file.

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
						

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

/* The MPLAB assembler automatically defines __LANGUAGE_ASSEMBLY. */
#ifndef __LANGUAGE_ASSEMBLY
    #include "trcKernelPortFreeRTOS.h"
#endif
						

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

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

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