# ESP Trace

[中文]

## Overview

The `esp_trace` component is the entry point for ESP-IDF tracing. It provides the public tracing API, manages the active trace session, and connects the selected encoder, such as SEGGER SystemView, with the selected transport, such as apptrace.

For a conceptual overview, architecture, and usage guides, see Tracing.

## Application Examples

- system/tracing/esp_trace_custom_library demonstrates how to integrate an external trace library (encoder) with the `esp_trace` core.

## API Reference

### Types

typedef struct esp_trace_handle *esp_trace_handle_t

  Trace session handle.

  Opaque handle representing an active trace session.

struct esp_trace_open_params_t

  Parameters for opening a trace session.

  This structure configures all aspects of a trace session, including the core behavior, encoder (trace library), and transport (communication channel).

  Public Members

  const esp_trace_config_t *core_cfg

    Core trace system configuration (optional)

    Currently reserved for future use.

  const char *encoder_name

    Encoder name (required)

    Must match the name of an encoder registered via ESP_TRACE_REGISTER_ENCODER(). The esp_trace component ships no encoder itself; encoders are provided by external components (for example, espressif/esp_sysview registers a SystemView encoder).

  const void *encoder_cfg

    Encoder-specific configuration (optional)

    If NULL, encoder uses its default configuration. The structure type depends on the encoder being used. See encoder-specific documentation.

  const char *transport_name

    Transport name (required)

    Must match a registered transport name. Built-in transports:

    - "apptrace" - Uses app_trace for JTAG or UART communication

    - "usb_serial_jtag" - Streams trace data over the USB Serial JTAG peripheral

  const void *transport_cfg

    Transport-specific configuration (optional)

    If NULL, transport uses its default configuration. The structure type depends on the transport being used:

    - For "apptrace": `esp_apptrace_config_t*`

    See transport-specific documentation for details.

struct esp_trace_config

  Core trace system configuration.

  Reserved for future core-level trace configuration.

  Public Members

  int reserved

    Reserved for future use.

enum esp_trace_link_types_t

  Trace transport link type.

  Values:

  enumerator ESP_TRACE_LINK_UNKNOWN

    Unknown or unavailable link type.

  enumerator ESP_TRACE_LINK_DEBUG_PROBE

    Debug probe link, for example JTAG through OpenOCD.

  enumerator ESP_TRACE_LINK_UART

    UART link.

  enumerator ESP_TRACE_LINK_USB_SERIAL_JTAG

    USB Serial JTAG link.

### Adapter Types

struct esp_trace_encoder_vtable_t

  Encoder Virtual Table.

  Defines the interface for trace encoders (libraries).

  Warning

  Runtime callbacks (write, flush, take_lock, give_lock, panic_handler) must not call FreeRTOS / IDF APIs that themselves trigger trace hooks (e.g. vTaskDelay, xQueue*, xSemaphore*) — doing so re-enters the tracing path and can deadlock on the encoder lock or crash in ISR context.

  Public Members

  esp_err_t (*init)(esp_trace_encoder_t *enc, const void *enc_cfg)

    Initialize encoder.

    Param enc:

      Encoder instance

    Param enc_cfg:

      Encoder-specific configuration

    Return:

      ESP_OK on success, error code otherwise

  esp_err_t (*write)(esp_trace_encoder_t *enc, const void *data, size_t size, uint32_t tmo)

    Write trace data.

    Param enc:

      Encoder instance

    Param data:

      Data buffer to write

    Param size:

      Size of data in bytes

    Param tmo:

      Timeout in microseconds

    Return:

      ESP_OK on success, error code otherwise

  void (*panic_handler)(esp_trace_encoder_t *enc, const void *info)

    Panic handler.

    Param enc:

      Encoder instance

    Param info:

      Panic information

  esp_err_t (*start)(esp_trace_encoder_t *enc)

    Resume trace event emission.

  esp_err_t (*stop)(esp_trace_encoder_t *enc)

    Pause trace event emission.

  esp_err_t (*flush)(esp_trace_encoder_t *enc)

    Flush pending trace data through the encoder.

  unsigned int (*take_lock)(esp_trace_encoder_t *enc, uint32_t tmo_us)

    Take encoder lock. Callers should pass ESP_TRACE_TMO_INFINITE unless they explicitly check the return value — pairing a failed take with give_lock() causes a spinlock owner-mismatch assert.

    Param enc:

      Encoder instance

    Param tmo:

      Timeout in microseconds

    Return:

      Lock state (for recursive locking) or 0 on failure

  void (*give_lock)(esp_trace_encoder_t *enc, unsigned int_state)

    Give encoder lock.

    Param enc:

      Encoder instance

    Param int_state:

      The interrupt state

  void (*function_enter)(esp_trace_encoder_t *enc, void *func, void *call_site)

    Send a function entry event.

    Param enc:

      Encoder instance

    Param func:

      Start address of the entered function

    Param call_site:

      Return address in the caller

  void (*function_exit)(esp_trace_encoder_t *enc, void *func, void *call_site)

    Send a function exit event.

    Param enc:

      Encoder instance

    Param func:

      Start address of the exited function

    Param call_site:

      Return address in the caller

struct esp_trace_encoder

  Encoder structure, represents an active trace library instance.

  Public Members

  const esp_trace_encoder_vtable_t *vt

    Pointer to encoder vtable.

  esp_trace_transport_t *tp

    Pointer to transport instance.

  void *ctx

    Encoder specific context.

enum esp_trace_transport_cfg_key_t

  Transport configuration keys.

  Standard configuration keys that encoders can use to configure transport behavior.

  Values:

  enumerator ESP_TRACE_TRANSPORT_CFG_HEADER_SIZE

    (uint32_t*) Trace header size in bytes

  enumerator ESP_TRACE_TRANSPORT_CFG_FLUSH_TMO

    (uint32_t*) Flush timeout in microseconds

  enumerator ESP_TRACE_TRANSPORT_CFG_FLUSH_THRESH

    (uint32_t*) Flush threshold in bytes

struct esp_trace_transport_vtable_t

  Transport Virtual Table.

  Defines the interface for trace transports.

  Warning

  Runtime callbacks (read, write, flush_nolock, panic_handler) must not call FreeRTOS / IDF APIs that themselves trigger trace hooks (e.g. vTaskDelay, xQueue*, xSemaphore*) — they are invoked from inside the encoder's lock and from ISR context, so re-entering the tracing path can deadlock or assert.

  Public Members

  esp_err_t (*init)(esp_trace_transport_t *tp, const void *tp_cfg)

    Initialize transport.

    Param tp:

      Transport instance

    Param tp_cfg:

      Transport-specific configuration

    Return:

      ESP_OK on success, error code otherwise

  esp_err_t (*set_config)(esp_trace_transport_t *tp, esp_trace_transport_cfg_key_t key, const void *value)

    Set transport configuration.

    Param tp:

      Transport instance

    Param key:

      Configuration key

    Param value:

      Configuration value

    Return:

      ESP_OK on success, error code otherwise

  esp_err_t (*get_config)(esp_trace_transport_t *tp, esp_trace_transport_cfg_key_t key, void *value)

    Get transport configuration.

    Param tp:

      Transport instance

    Param key:

      Configuration key

    Param value:

      Pointer to store configuration value

    Return:

      ESP_OK on success, error code otherwise

  esp_err_t (*read)(esp_trace_transport_t *tp, void *data, size_t *size, uint32_t tmo)

    Read trace data.

    Param tp:

      Transport instance

    Param data:

      Buffer to read data into

    Param size:

      Pointer to size (in: buffer size, out: bytes read)

    Param tmo:

      Timeout in microseconds

    Return:

      ESP_OK on success, error code otherwise

  esp_err_t (*write)(esp_trace_transport_t *tp, const void *data, size_t size, uint32_t tmo)

    Write trace data.

    Param tp:

      Transport instance

    Param data:

      Data buffer to write

    Param size:

      Size of data in bytes

    Param tmo:

      Timeout in microseconds

    Return:

      ESP_OK on success, error code otherwise

  esp_err_t (*flush_nolock)(esp_trace_transport_t *tp)

    Flush without lock.

    The transport should use its internally stored flush configuration (timeout, threshold) that was set during initialization.

    Param tp:

      Transport instance

    Return:

      ESP_OK on success, error code otherwise

  esp_err_t (*down_buffer_config)(esp_trace_transport_t *tp, uint8_t *buf, uint32_t size)

    Configure down buffer.

    Param tp:

      Transport instance

    Param buf:

      Buffer pointer

    Param size:

      Buffer size in bytes

    Return:

      ESP_OK on success, error code otherwise

  bool (*is_host_connected)(esp_trace_transport_t *tp)

    Check if host is connected.

    Param tp:

      Transport instance

    Return:

      true if host is connected, false otherwise

  esp_trace_link_types_t (*get_link_type)(esp_trace_transport_t *tp)

    Get link type.

    See also

    esp_trace_link_types_t

    Param tp:

      Transport instance

    Return:

      Link type

  void (*panic_handler)(esp_trace_transport_t *tp, const void *info)

    Panic handler.

    Param tp:

      Transport instance

    Param info:

      Panic information

struct esp_trace_transport

  Transport structure representing an active transport instance.

  Public Members

  const esp_trace_transport_vtable_t *vt

    Pointer to transport vtable.

  void *ctx

    Transport-specific context.

### Functions

esp_trace_open_params_t esp_trace_get_user_params(void)

  Get trace initialization parameters for early system initialization.

  User applications need to implement this function to provide a custom trace configuration. This function is called during system initialization before any other trace functions are called.

  Returns:

    Configuration

esp_trace_handle_t esp_trace_get_active_handle(void)

  Get the active trace handle.

  Returns:

    The active trace handle

esp_err_t esp_trace_write(esp_trace_handle_t handle, const void *data, size_t size, unsigned long tmo)

  Write data to the trace handle.

  Parameters:

    - handle -- The trace handle

    - data -- The data to write

    - size -- The size of the data

    - tmo -- The timeout in us

  Returns:

    ESP_OK on success, otherwise see esp_err_t

esp_err_t esp_trace_start(void)

  Resume trace event emission on the active session.

  Returns:

    ESP_OK on success, otherwise see esp_err_t

esp_err_t esp_trace_stop(void)

  Pause trace event emission on the active session.

  Returns:

    ESP_OK on success, otherwise see esp_err_t

esp_err_t esp_trace_flush(void)

  Flush pending trace data through the encoder.

  Returns:

    ESP_OK on success, otherwise see esp_err_t

bool esp_trace_is_host_connected(esp_trace_handle_t handle)

  Check if the host is connected.

  Parameters:

    handle -- The trace handle

  Returns:

    true if the host is connected, otherwise false

esp_trace_link_types_t esp_trace_get_link_type(esp_trace_handle_t handle)

  Get the link type.

  See also

  esp_trace_link_types_t

  Parameters:

    handle -- The trace handle

  Returns:

    The link type

void esp_trace_panic_handler(const void *info)

  Panic flush the trace handle. This function is called from panic handler.

  Parameters:

    info -- Panic info passed from the panic handler

Was this page helpful?

- Thank you! We received your feedback.
- If you have any comments, fill in Espressif Documentation Feedback Form.

- We value your feedback.
- Let us know how we can improve this page by filling in Espressif Documentation Feedback Form.