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

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?