Adding TraceRecorder in MPLAB X IDE Projects

This guide shows how to integrate the Percepio TraceRecorder library into an existing MPLAB X IDE project using FreeRTOS. This guide is based on a Microchip demo project where TraceRecorder was added, like in the steps below.

In this setup, snapshots are saved from an in-memory trace buffer (the RingBuffer streamport module) using an MPLAB X IDE plugin. Tracealyzer also supports continuous trace streaming, for example via J-Link debug probes or Ethernet. We aim to provide Microchip-specific examples on trace streaming in the near future. If something is unclear, please also check the general getting-started guides here.

If you are using Zephyr, the TraceRecorder integration is already part of Zephyr’s Kconfig tree, which makes setup much easier. See our dedicated Zephyr integration guide for instructions.

1. Copy the TraceRecorder Library

1. Locate the TraceRecorder source in your Tracealyzer installation under:
   Tracealyzer/FreeRTOS/TraceRecorder
2. Copy the entire TraceRecorder folder into your MPLAB project source directory (e.g., apps/rtos/freertos/basic_freertos/firmware/src)

2. Add TraceRecorder Files in MPLAB

1. In the Projects panel, right-click your source folder →
   Add > Existing Items from Folders… → Select the TraceRecorder folder.
2. Remove unused folders:
   • Right-click TraceRecorder/Extras → Remove from Project
   • Inside TraceRecorder/streamports, keep only RingBuffer. Remove others.
3. For easy access, right-click TraceRecorder/config → Add Existing Items… → Select all .h files

3. Update the TraceRecorder configuration

In trcConfig.h:
Replace:

#error "Trace Recorder: Please include your processor's header file here and remove this line."

With:

#include "device.h"

Then set:

#define TRC_CFG_HARDWARE_PORT              TRC_HARDWARE_PORT_ARM_Cortex_M // For Arm-based devices like PIC32Cx and SAM.
#define TRC_CFG_INCLUDE_OSTICK_EVENTS      0    // Optional: Skips recording OS tick events for longer traces
#define TRC_CFG_ENABLE_STACK_MONITOR       1    // Enables periodic task stack usage checks

Optional:

#define TRC_CFG_CTRL_TASK_DELAY            100  // Milliseconds between stack checks

In trcKernelPortConfig.h:
Set your FreeRTOS version:

#define TRC_CFG_FREERTOS_VERSION   TRC_FREERTOS_VERSION_11_1_0     // Verify version in the FreeRTOS source files

4. Add Include Paths

1. Right-click the project → Properties
2. Go to:
   xc32-gcc > Preprocessing and Messages > Include Directories
3. Add:

     TraceRecorder/include
     TraceRecorder/config
     TraceRecorder/streamports/RingBuffer/include
     TraceRecorder/streamports/RingBuffer/config

5. Start TraceRecorder

In SYS_Initialize, add:

    #include "trcRecorder.h"   // At the end of the include statements

    xTraceEnable(TRC_START);   // As first line in SYS_Initialize

6. Configure FreeRTOS to use TraceRecorder

1. Find FreeRTOSConfig.h via Navigate > Go to File
2. Ensure you have:

    #define configUSE_TRACE_FACILITY    1

3. At the bottom of the file, add:

    #ifndef __LANGUAGE_ASSEMBLY
    #include "trcRecorder.h"
    #endif

This enables trace hooks for FreeRTOS kernel events.

7. Build and Debug

• Build the project and ensure there are no build errors or warnings.
• Note: If you’re trying to run this in the MPLAB simulator, timestamps won’t work due to lack of DWT cycle counter support. All events will appear at timestamp 0.

8. Viewing the Trace

1. Install the Tracealyzer Export Plugin (see instructions here)
2. Open the plugin via Tools > Embedded > Tracealyzer Export Plugin (must be opened before debugging starts)
3. Start a debug session
4. Ensure the application has executed past xTraceEnable(TRC_START)
5. Halt execution
6. Click “Save Trace” in the plugin window
7. Check the plugin log for any issues
8. Open the trace file in Tracealyzer:
   File > Open > Open File

Need Help?

Feel free to contact Percepio in case you have questions.