1. Add the TraceRecorder files

   Include the common TraceRecorder source files and the FreeRTOS kernel port. When using the GitHub repository, the relevant directories are:

   • config/
   • include/
   • kernelports/FreeRTOS/
   • kernelports/FreeRTOS/config/
   • kernelports/FreeRTOS/include/

   Add the necessary include paths to your project.

2. Configure FreeRTOS

   In FreeRTOSConfig.h, enable trace support and include the recorder header:
   #define configUSE_TRACE_FACILITY 1

   Add the following at the end of FreeRTOSConfig.h, subject to any compiler-specific restrictions for assembly files:
   #if ( configUSE_TRACE_FACILITY == 1 )

   #include "trcRecorder.h"

   #endif

   In trcKernelPortConfig.h, configure TRC_CFG_FREERTOS_VERSION to match your FreeRTOS version.

   In trcConfig.h, set TRC_CFG_HARDWARE_PORT to the hardware port matching your target architecture. Include the processor header if required by that hardware port.

3. Integrate the stream port

   Add the source files, headers, and configuration for your selected stream port. Configure its transport-specific settings in trcStreamPortConfig.h.

   For J-Link RTT, configure the RTT buffers and transfer mode as needed. For network-based ports, configure the transport and buffering settings required by the implementation.

4. Initialize tracing

   Call the appropriate recorder initialization and start functions after hardware setup. For a typical application:
   xTraceEnable(TRC_START);

   For host-controlled streaming, use TRC_START_FROM_HOST where supported. Hardware ports that depend on the RTOS tick source may require initialization before creating RTOS objects and enabling tracing after the scheduler starts.

Reference: TraceRecorder on FreeRTOS

TraceRecorder is available as a configurable Zephyr module in supported integrations. Source inclusion is handled by the build system when the required options are enabled.

1. Enable tracing

   Add the following to prj.conf:
   CONFIG_TRACING=y

   CONFIG_PERCEPIO_TRACERECORDER=y

   CONFIG_PERCEPIO_TRC_CFG_CTRL_TASK_STACK_SIZE=1024

    

2. Select the stream port

   For example, to stream through SEGGER J-Link RTT:
   CONFIG_PERCEPIO_TRC_CFG_STREAM_PORT_RTT=y

   For ARM ITM, use:
   CONFIG_PERCEPIO_TRC_CFG_STREAM_PORT_ITM=y

   Select only the stream port intended for your configuration.

3. Configure the recorder start mode

   For host-controlled streaming, use:
   CONFIG_PERCEPIO_TRC_START_MODE_START_FROM_HOST=y

   This allows Tracealyzer to start recording through a host command without blocking application startup.

   Alternatively, CONFIG_PERCEPIO_TRC_START_MODE_START_AWAIT_HOST=y waits for a host command before the application proceeds. Use this only when the startup behavior is appropriate for your application.

4. Configure buffering and transport settings

   For RTT, review the relevant options, including:

   • CONFIG_PERCEPIO_TRC_CFG_STREAM_PORT_RTT_UP_BUFFER_SIZE
   • CONFIG_PERCEPIO_TRC_CFG_STREAM_PORT_RTT_DOWN_BUFFER_SIZE
   • CONFIG_PERCEPIO_TRC_CFG_STREAM_PORT_RTT_UP_BUFFER_INDEX
   • CONFIG_PERCEPIO_TRC_CFG_STREAM_PORT_RTT_DOWN_BUFFER_INDEX
   • CONFIG_PERCEPIO_TRC_CFG_STREAM_PORT_RTT_MODE

   The up buffer transfers data from target to host; the down buffer receives commands from host to target. Buffer indices must match the settings in Tracealyzer.

   The control task settings CONFIG_PERCEPIO_TRC_CFG_CTRL_TASK_PRIORITY, CONFIG_PERCEPIO_TRC_CFG_CTRL_TASK_DELAY, and CONFIG_PERCEPIO_TRC_CFG_CTRL_TASK_STACK_SIZE control the task that handles recorder commands and, for applicable ports, data transfer.

5. Rebuild the application

   Perform a pristine build after enabling TraceRecorder or changing relevant tracing configuration:
   west build -p always

   In Tracealyzer, add the Zephyr build directory under File → Settings → Project Settings → Definition File Paths when required by the integration.

   Reference: TraceRecorder on Zephyr

1. Add the TraceRecorder files

   Include the common source files and the ThreadX kernel port. For a GitHub-based integration, use:

   • config/
   • include/
   • kernelports/ThreadX/
   • The corresponding ThreadX kernel-port configuration and include directories.

   Add the required header paths to the build.

2. Configure ThreadX

   In tx_user.h, enable event tracing:
   #define TX_ENABLE_EVENT_TRACE

   Ensure TX_INCLUDE_USER_DEFINE_FILE is defined so ThreadX includes the user configuration.

   Include trcRecorder.h at the end of tx_api.h, following the platform integration instructions.

   In trcConfig.h, configure TRC_CFG_HARDWARE_PORT for the target architecture.

   In trcKernelPortConfig.h, configure TRC_CFG_CPU_CLOCK_HZ to match the frequency of the timer used for trace timestamps.

3. Configure the stream port

   Add the selected port’s implementation and configure trcStreamPortConfig.h as required by the transport.

   For J-Link RTT, verify the RTT buffer settings and ensure that any existing SEGGER RTT implementation is compatible with the one used by TraceRecorder.

4. Initialize tracing

   Call xTraceEnable() near the beginning of tx_application_define, following the integration requirements.

   Use TRC_START_FROM_HOST for non-blocking host-controlled streaming or TRC_START_AWAIT_HOST when the application must wait for a host command.

5. Apply compiler instrumentation requirements

   Some ThreadX integrations require additional compiler configuration to instrument kernel calls. The documented GCC setup uses the trcCTI.h mechanism and corresponding build flags. Follow the requirements for your compiler and integration version.

Reference: TraceRecorder on ThreadX

ESP-IDF uses FreeRTOS and provides a TraceRecorder integration configured through ESP-IDF’s component system and menuconfig.

1. Add the TraceRecorder component

   In the project’s top-level CMakeLists.txt, add the TraceRecorder ESP-IDF kernel-port directory to EXTRA_COMPONENT_DIRS:
   set(EXTRA_COMPONENT_DIRS "<TraceRecorderPath>/kernelports/ESP-IDF_FreeRTOS")

   Replace the path with the actual location of the TraceRecorder integration.

   Ensure that the project configuration does not exclude the component from the build. In FreeRTOS.h, add the recorder include after FreeRTOSConfig.h as described in the platform guide:
   #ifdef CONFIG_PERCEPIO_TRACERECORDER_ENABLED

   #include <trcRecorder.h>

   #endif

    

2. Configure TraceRecorder

   Rebuild the project, then open the ESP-IDF configuration menu:
   idf.py menuconfig

   Navigate to Percepio TraceRecorder, enable the recorder, and select the stream port.

3. Select the transport
   • TCP/IP: Configure the network stack, target connection, internal buffer, and control task. A control task stack size of 512 bytes or greater is recommended by the current Percepio guide for TCP streaming.
   • UDP: Configure the host IP address and UDP port, enable the required network stack settings, and match the host connection parameters.
   • ESP-IDF AppTrace: Configure the debug connection and set the application-level trace destination to JTAG. Configure the GDB/OpenOCD connection as required.

   For TCP/IP and UDP, enable LwIP core locking when required by the integration. Adjust buffer sizes and control task settings according to throughput and memory requirements.

4. Rebuild and flash

   Perform a clean full build after changing the component integration or stream-port configuration. Flash the application and verify that the selected transport is operational.

Reference: TraceRecorder on ESP-IDF

For other supported platforms, use the matching TraceRecorder kernel port or platform-specific integration.

1. Add or enable the TraceRecorder integration using the platform’s build system.
2. Configure the hardware timestamp source.
3. Select and enable a supported stream port.
4. Configure transport-specific settings and required drivers.
5. Initialize the recorder and select the appropriate start behavior.