Getting Started with Percepio View on FreeRTOS

Percepio View relies on Percepio TraceRecorder to provide trace data. This library is provided in the Percepio View installation folder and needs to be added to your project. Percepio View is limited to snapshot traces. This means that the events are stored in a target-side memory buffer, from which you can save snapshots (memory dumps) using your debugger. The device must be halted when saving a snapshot, for example stopped on a breakpoint. Percepio View supports x86-64 computers running Windows or Linux. Arm-based host computers are not yet supported.

To record long traces by real-time trace streaming, consider upgrading to Percepio Profile or Percepio Tracealyzer.

Installing the application

  • Windows: Download and run the installer.
  • Linux: Download the archive. The standalone version is recommended for most users. Then refer to the Running Tracealyzer on Linux guide. Start the application by running ./launch-tz.sh.

Adding TraceRecorder in your project

1. Locate the TraceRecorder folder in your Percepio View installation. This is found in the “FreeRTOS” directory. A shortcut is available in the Help menu.

TraceRecorder

2. Copy the the following source files to your project and make sure they are included in your build:

  • TraceRecorder/*.c
  • TraceRecorder/streamports/RingBuffer/trcStreamPort.c

3. Copy the following directories to your project and add them in your “include paths”:

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

4. In config/trcConfig.h: Remove this line #error “Trace Recorder: Please include your processor’s header file here and remove this line.”. This is just a reminder. For some hardware ports (e.g. Arm Cortex-M), you need to add your processor include file (for example “stm32l4xx.h”) and this is a suitable place for it. If you are uncertain, skip this #include to begin with. If TraceRecorder builds without errors, this include is not needed.

5. In config/trcConfig.h set TRC_CFG_HARDWARE_PORT to a “hardware port” matching your processor. For Arm Cortex-M devices, use TRC_HARDWARE_PORT_ARM_Cortex_M. All available hardware ports are listed in include/trcDefines.h. If you don’t find a match for your processor type, you can make your own hardware port, or you may contact Percepio about commercial engineering services.

6. In config/trcKernelPortConfig.h, set TRC_CFG_FREERTOS_VERSION to match your FreeRTOS version. Check your FreeRTOS source files if you are uncertain.

Note:If using version 4.10.x, don’t change the setting TRC_CFG_RECORDER_MODE. Use the default setting TRC_RECORDER_MODE_STREAMING also for snapshot tracing. This setting is deprecated and will be removed in v4.11.

7. In FreeRTOSConfig.h, make sure that configUSE_TRACE_FACILITY is set to 1. If not defined, add #define configUSE_TRACE_FACILITY 1.

8. In FreeRTOSConfig.h, add #include “trcRecorder.h” in the end (after all #defines).

Note: If using IAR Embedded Workbench, add #ifndef __IASMARM__ … #endif guard around the include.

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

Note: If using Microchip MPLAB X IDE, add #ifndef __LANGUAGE_ASSEMBLY … #endif guard around the include.

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

9. Call xTraceEnable(TRC_START) in your main function to initialize and start the recorder. This should be done as early as possible, before any RTOS objects (tasks etc.) have been created.

Another option is to call xTraceInitialize() instead (also as early as possible). This initializes the library without starting the tracing. Then call xTraceEnable() at a later point to start the tracing. This method is needed for Cortex-M0 devices and other Arm devices lacking the DWT unit. For such devices, make sure to call xTraceEnable() after the FreeRTOS scheduler has been started, for example in vApplicationDaemonTaskStartupHook().

Saving and Viewing Traces

Build your project and start a debug session. Run for a while and halt the device, e.g. on a breakpoint.

If using a GCC toolchain:

  • Open the debug console in your IDE, where you can type in GDB commands.
  • Run the following gdb command: “dump binary value trace.bin *RecorderDataPtr” (no quotes)
  • (If using VS Code, you need to add “-exec” before the gdb command: “-exec dump binary value trace.bin *RecorderDataPtr”)

For frequent use, consider setting up the GDB integration, or use the Percepio Trace Exporter plugin for Eclipse IDEs. For setup instructions, see https://percepio.com/tracealyzer/gettingstarted/snapshots-eclipse-gdb. When setting up the plugin, note that the executable for Percepio View/Profile is called “Tracealyzer”.

If using IAR Embedded Workbench for Arm, see instructions for “snapshot mode” on https://percepio.com/iar.

If using other development tools, see the Percepio View user manual (Help menu), under “Creating and Loading Traces” -> “Percepio TraceRecorder” -> “Snapshot Trace”.

Finally, open the trace file in Percepio View by selecting File -> Open -> Open File. If using WIndows, you can also drag the file to the Percepio View window.

Questions

If you have technical questions, please post them in the FreeRTOS Forum. Make sure to set “Percepio” as category.