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:

  1. First of all, you will need to modify the ESP-IDF codebase you are using. Please refer to: Required ESP-IDF code modifications

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

  3. Install Tracealyzer and select Help -> ESP-IDF FreeRTOS Trace Recorder to locate the Trace Recorder ESP-IDF component in the installation directory.

  4. Note the path of the Trace Recorder ESP-IDF component.

  5. In your ESP IDF project folder, open CMakeLists.txt.

  6. 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)

  7. Open a terminal in your ESP IDF project directory and run idf.py menuconfig

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

  9. Navigate back to the main menu and go to Percepio Trace Recorder

  10. Check the Tracealyzer Tracing Enable option

  11. Save the settings by pressing S.

  12. Exit the configuration UI by pressing Q

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

  14. In Tracealyzer, open settings, navigate to PSF-Streaming Settings, and choose Target Connection: GDB.

  15. Navigate to GDB Settings.

  16. Set Path to GDB to the GDB executable provided by Espressif (xtensa-esp32-elf-gdb.exe).

  17. Set Path to Image to your projects .elf file.

  18. 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
    
  19. 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
      
  20. Configure Commands to End Stream as follows:

    mon esp apptrace stop
    
  21. 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.

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

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

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

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

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

  2. After the aforementioned function, add the following code:

    #if CONFIG_PERCEPIO_TRACERECORDER_ENABLED
        xTraceInitialize();
    #endif /*CONFIG_PERCEPIO_TRACERECORDER_ENABLED*/
    
  3. In the same file (startup.c), navigate to #if CONFIG_APPTRACE_ENABLE

  4. 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*/
    
  5. Open FreeRTOS.h located in the components/freertos/include/freertos directory of ESP-IDF.

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

  1. Open cpu_start.c located in either components/esp32s2 (for esp32s2) or components/esp32 (for esp32).

  2. Navigate to void start_cpu0_default(void).

  3. 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*/
    
  4. 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*/
    
  5. Open components/freertos/include/freertos/FreeRTOS.h

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

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