ESP-IDF¶

The sections below covers the information necessary for using the FreeRTOS trace recorder using Espressif’s ESP-IDF framework and ESP32 targets.

Getting Started with Tracealyzer for ESP-IDF FreeRTOS¶

ESP-IDF features an application level tracing library apptrace, which allows for the transfer of trace data from target to host using a JTAG adapter and OpenOCD. To configure Tracealyzer to interface with the apptrace system via GDB use the following steps:

First of all, you will need to modify the ESP-IDF codebase you are using. Please refer to: Required ESP-IDF code modifications
Get Tracealyzer from https://percepio.com/downloadform. In the registration form, make sure to select FreeRTOS as Target Platform. The download link is emailed to you and usually arrives within 1 minute.
Install Tracealyzer and select Help -> ESP-IDF FreeRTOS Trace Recorder to locate the Trace Recorder ESP-IDF component in the installation directory.
Note the path of the Trace Recorder ESP-IDF component.
In your ESP IDF project folder, open CMakeLists.txt.
To include the Tracealyzer component, it will need to be added to the EXTRA_COMPONENT_DIRS CMake variable. To do this (assuming that you already haven’t added any external component to the EXTRA_COMPONENT_DIRS variable), add the following: set(EXTRA_COMPONENT_DIRS <path_to_your_tracerecorder_directory>/ESP-IDF_FreeRTOS/TraceRecorder/kernelports/ESP-IDF_FreeRTOS)
- Replace <path_to_your_tracerecorder_directory> with the actual path to your TraceRecorder directory which you previously noted down (step 3)
Open a terminal in your ESP IDF project directory and run idf.py menuconfig
Navigate to Component config->Application Level Tracing
- If you’re using ESP-IDF V4.2, select the Trace memory option for Data Destination.
- If you’re using ESP-IDF V4.3, V4.4 or V5.0, select the JTAG option for Data Destination.
Navigate back to the main menu and go to Percepio Trace Recorder
Check the Tracealyzer Tracing Enable option
Save the settings by pressing S.
Exit the configuration UI by pressing Q
To be able to receive data in Tracealyzer, an instance of OpenOCD will need to be running. Instructions on how to use OpenOCD with the ESP-IDF platform can be found in the ESP IDF documentation.
In Tracealyzer, open settings, navigate to PSF-Streaming Settings, and choose Target Connection: GDB.
Navigate to GDB Settings.
Set Path to GDB to the GDB executable provided by Espressif (xtensa-esp32-elf-gdb.exe).
Set Path to Image to your projects .elf file.

Configure Commands to Initialize as follows:

target remote localhost:3333
!tz wait 1000
set mem inaccessible-by-default off
flushregs
set remote hardware-watchpoint-limit 2
set remote hardware-breakpoint-limit 2

Configure Commands to Start Stream.
- If you have configured Percepio Trace Recorder->Recorder Start Mode to Start From Host, enter the following:
  mon esp apptrace start "file://$(TZ_OUT)" 0 -1 -1 0 0 mon resume
- If you have configured Percepio Trace Recorder->Recorder Start Mode to Start, enter the following:
  mon reset halt mon esp apptrace start "file://$(TZ_OUT)" 0 -1 -1 0 0 mon resume
Configure Commands to End Stream as follows:
```
mon esp apptrace stop
```
Set Trace Data is Received by to GDB Writes Data to Output Specified by $(TZ_OUT).

Modifying the openocd configuration files¶

To be able to run both a debugger and Tracealyzer at the same time, the openocd configuration files will need to be modified to allow for multiple connections.

Open the configuration file for the target you’re using, in this example, the esp32s2 target is used.
- If you’re using ESP-IDF V5.0:
  
  On Linux, the path to the aforementioned configuration file is: $HOME/.espressif/tools/openocd-esp32/v0.12.0-esp32-20230419/openocd-esp32/share/openocd/scripts/target/esp32s2.cfg
  
  On Windows, the path to the aforementioned configuration file is: C:\esp\tools\openocd-esp32\v0.12.0-esp32-20230419\openocd-esp32\share\openocd\scripts\target\esp32s2.cfg
- If you’re using ESP-IDF V4.4:
  
  On Linux, the path to the aforementioned configuration file is: $HOME/.espressif/tools/openocd-esp32/v0.11.0-esp32-20221026/openocd-esp32/share/openocd/scripts/target/esp32s2.cfg
  
  On Windows, the path to the aforementioned configuration file is: C:\esp\tools\openocd-esp32\v0.11.0-esp32-20221026\openocd-esp32\share\openocd\scripts\target\esp32s2.cfg
- If you’re using ESP-IDF V4.3 or V4.2:
  
  On Linux, the path to the aforementioned configuration file is: $HOME/.espressif/tools/openocd-esp32/v0.11.0-esp32-20220706/openocd-esp32/share/openocd/scripts/target/esp32s2.cfg
  
  On Windows, the path to the aforementioned configuration file is: C:\esp\tools\openocd-esp32\v0.11.0-esp32-20220706\openocd-esp32\share\openocd\scripts\target\esp32s2.cfg
On the line before source [find target/xtensa-core-esp32s2.cfg], add the following: $_TARGETNAME configure -gdb-max-connections 3

Required ESP-IDF code modifications¶

Depending on the version of esp-idf you are using, a few modifications will need to be made to the ESP-IDF codebase. Please refer to the sections below for the appropriate instructions which corresponds to your ESP-IDF version.

Integration ESP-IDF V5.0¶

The following section cover the integration of the Percepio trace recorder with ESP-IDF V5.0.

Open FreeRTOS.h located in the components/freertos/FreeRTOS-Kernel/include/freertos directory of ESP-IDF.

After #include freertos/FreeRTOSConfig.h, add the following code:

#ifdef CONFIG_PERCEPIO_TRACERECORDER_ENABLED
    #include <trcRecorder.h>
#endif

Integration ESP-IDF V4.4 and ESP-IDF V4.3¶

The following section cover the integration of the the Percepio trace recorder with ESP-IDF V4.4 and ESP-IDF V4.3.

Open startup.c located in the “components/esp_system” directory of ESP-IDF and locate esp_newlib_time_init().

After the aforementioned function, add the following code:

#if CONFIG_PERCEPIO_TRACERECORDER_ENABLED
    xTraceInitialize();
#endif /*CONFIG_PERCEPIO_TRACERECORDER_ENABLED*/

In the same file (startup.c), navigate to #if CONFIG_APPTRACE_ENABLE

after assert(err == ESP_OK && "Failed to init apptrace module on PRO CPU!");, add the following block of code

#if CONFIG_PERCEPIO_TRACERECORDER_ENABLED
    #if CONFIG_PERCEPIO_RECORDER_CFG_START_MODE_START == 1
        xTraceEnable(TRC_START);
    #elif CONFIG_PERCEPIO_RECORDER_CFG_START_MODE_START_AWAIT_HOST == 1
        xTraceEnable(TRC_START_AWAIT_HOST);
    #elif CONFIG_PERCEPIO_RECORDER_CFG_START_MODE_START_FROM_HOST == 1
        xTraceEnable(TRC_START_FROM_HOST);
    #else
        xTraceInitialize();
    #endif
#endif /*CONFIG_PERCEPIO_TRACERECORDER_ENABLED*/

Open FreeRTOS.h located in the components/freertos/include/freertos directory of ESP-IDF.

After #include freertos/FreeRTOSConfig.h, add the following code:

#ifdef CONFIG_PERCEPIO_TRACERECORDER_ENABLED
    #include <trcRecorder.h>
#endif

Integration ESP-IDF V4.2¶

The following section cover the integration of the Percepio trace recorder with ESP-IDF V4.2.

Open cpu_start.c located in either components/esp32s2 (for esp32s2) or components/esp32 (for esp32).
Navigate to void start_cpu0_default(void).

Within the aforementioned function, after intr_matrix_clear(), add the following piece of code:

#if CONFIG_PERCEPIO_TRACERECORDER_ENABLED
            xTraceInitialize();
#endif /*CONFIG_PERCEPIO_TRACERECORDER_ENABLED*/

Still within the function (start_cpu0_default), after assert(err == ESP_OK && "Failed to init apptrace module on PRO CPU!");, add the following code:

#if CONFIG_PERCEPIO_TRACERECORDER_ENABLED
    #if CONFIG_PERCEPIO_RECORDER_CFG_START_MODE_START == 1
        xTraceEnable(TRC_START);
    #elif CONFIG_PERCEPIO_RECORDER_CFG_START_MODE_START_AWAIT_HOST == 1
        xTraceEnable(TRC_START_AWAIT_HOST);
    #elif CONFIG_PERCEPIO_RECORDER_CFG_START_MODE_START_FROM_HOST == 1
        xTraceEnable(TRC_START_FROM_HOST);
    #else
        xTraceInitialize();
    #endif
#endif /*CONFIG_PERCEPIO_TRACERECORDER_ENABLED*/

Open components/freertos/include/freertos/FreeRTOS.h

After #include "freertos/FreeRTOSConfig.h", add:

#ifdef CONFIG_PERCEPIO_TRACERECORDER_ENABLED
    #include <trcRecorder.h>
#endif