Application Level Tracing

Overview

IDF provides useful feature for program behaviour analysis: application level tracing. It is implemented in the corresponding library and can be enabled via menuconfig. This feature allows to transfer arbitrary data between host and ESP32 via JTAG interface with small overhead on program execution. Developers can use this library to send application specific state of execution to the host and receive commands or other type of info in the opposite direction at runtime. The main use cases of this library are:

  1. Collecting application specific data, see Application Specific Tracing
  2. Lightweight logging to the host, see Logging to Host
  3. System behaviour analysis, see System Behaviour Analysis with SEGGER SystemView

API Reference

Functions

esp_err_t esp_apptrace_init()

Initializes application tracing module.

Note
Should be called before any esp_apptrace_xxx call.
Return
ESP_OK on success, otherwise see esp_err_t

void esp_apptrace_down_buffer_config(uint8_t *buf, uint32_t size)

Configures down buffer.

Note
Needs to be called before initiating any data transfer using esp_apptrace_buffer_get and esp_apptrace_write. This function does not protect internal data by lock.
Parameters
  • buf: Address of buffer to use for down channel (host to target) data.
  • size: Size of the buffer.

uint8_t *esp_apptrace_buffer_get(esp_apptrace_dest_t dest, uint32_t size, uint32_t tmo)

Allocates buffer for trace data. After data in buffer are ready to be sent off esp_apptrace_buffer_put must be called to indicate it.

Return
non-NULL on success, otherwise NULL.
Parameters
  • dest: Indicates HW interface to send data.
  • size: Size of data to write to trace buffer.
  • tmo: Timeout for operation (in us). Use ESP_APPTRACE_TMO_INFINITE to wait indefinetly.

esp_err_t esp_apptrace_buffer_put(esp_apptrace_dest_t dest, uint8_t *ptr, uint32_t tmo)

Indicates that the data in buffer are ready to be sent off. This function is a counterpart of and must be preceeded by esp_apptrace_buffer_get.

Return
ESP_OK on success, otherwise see esp_err_t
Parameters
  • dest: Indicates HW interface to send data. Should be identical to the same parameter in call to esp_apptrace_buffer_get.
  • ptr: Address of trace buffer to release. Should be the value returned by call to esp_apptrace_buffer_get.
  • tmo: Timeout for operation (in us). Use ESP_APPTRACE_TMO_INFINITE to wait indefinetly.

esp_err_t esp_apptrace_write(esp_apptrace_dest_t dest, const void *data, uint32_t size, uint32_t tmo)

Writes data to trace buffer.

Return
ESP_OK on success, otherwise see esp_err_t
Parameters
  • dest: Indicates HW interface to send data.
  • data: Address of data to write to trace buffer.
  • size: Size of data to write to trace buffer.
  • tmo: Timeout for operation (in us). Use ESP_APPTRACE_TMO_INFINITE to wait indefinetly.

int esp_apptrace_vprintf_to(esp_apptrace_dest_t dest, uint32_t tmo, const char *fmt, va_list ap)

vprintf-like function to sent log messages to host via specified HW interface.

Return
Number of bytes written.
Parameters
  • dest: Indicates HW interface to send data.
  • tmo: Timeout for operation (in us). Use ESP_APPTRACE_TMO_INFINITE to wait indefinetly.
  • fmt: Address of format string.
  • ap: List of arguments.

int esp_apptrace_vprintf(const char *fmt, va_list ap)

vprintf-like function to sent log messages to host.

Return
Number of bytes written.
Parameters
  • fmt: Address of format string.
  • ap: List of arguments.

esp_err_t esp_apptrace_flush(esp_apptrace_dest_t dest, uint32_t tmo)

Flushes remaining data in trace buffer to host.

Return
ESP_OK on success, otherwise see esp_err_t
Parameters
  • dest: Indicates HW interface to flush data on.
  • tmo: Timeout for operation (in us). Use ESP_APPTRACE_TMO_INFINITE to wait indefinetly.

esp_err_t esp_apptrace_flush_nolock(esp_apptrace_dest_t dest, uint32_t min_sz, uint32_t tmo)

Flushes remaining data in trace buffer to host without locking internal data. This is special version of esp_apptrace_flush which should be called from panic handler.

Return
ESP_OK on success, otherwise see esp_err_t
Parameters
  • dest: Indicates HW interface to flush data on.
  • min_sz: Threshold for flushing data. If current filling level is above this value, data will be flushed. TRAX destinations only.
  • tmo: Timeout for operation (in us). Use ESP_APPTRACE_TMO_INFINITE to wait indefinetly.

esp_err_t esp_apptrace_read(esp_apptrace_dest_t dest, void *data, uint32_t *size, uint32_t tmo)

Reads host data from trace buffer.

Return
ESP_OK on success, otherwise see esp_err_t
Parameters
  • dest: Indicates HW interface to read the data on.
  • data: Address of buffer to put data from trace buffer.
  • size: Pointer to store size of read data. Before call to this function pointed memory must hold requested size of data
  • tmo: Timeout for operation (in us). Use ESP_APPTRACE_TMO_INFINITE to wait indefinetly.

uint8_t *esp_apptrace_down_buffer_get(esp_apptrace_dest_t dest, uint32_t *size, uint32_t tmo)

Rertrieves incoming data buffer if any. After data in buffer are processed esp_apptrace_down_buffer_put must be called to indicate it.

Return
non-NULL on success, otherwise NULL.
Parameters
  • dest: Indicates HW interface to receive data.
  • size: Address to store size of available data in down buffer. Must be initializaed with requested value.
  • tmo: Timeout for operation (in us). Use ESP_APPTRACE_TMO_INFINITE to wait indefinetly.

esp_err_t esp_apptrace_down_buffer_put(esp_apptrace_dest_t dest, uint8_t *ptr, uint32_t tmo)

Indicates that the data in down buffer are processesd. This function is a counterpart of and must be preceeded by esp_apptrace_down_buffer_get.

Return
ESP_OK on success, otherwise see esp_err_t
Parameters
  • dest: Indicates HW interface to receive data. Should be identical to the same parameter in call to esp_apptrace_down_buffer_get.
  • ptr: Address of trace buffer to release. Should be the value returned by call to esp_apptrace_down_buffer_get.
  • tmo: Timeout for operation (in us). Use ESP_APPTRACE_TMO_INFINITE to wait indefinetly.

bool esp_apptrace_host_is_connected(esp_apptrace_dest_t dest)

Checks whether host is connected.

Return
true if host is connected, otherwise false
Parameters
  • dest: Indicates HW interface to use.

void *esp_apptrace_fopen(esp_apptrace_dest_t dest, const char *path, const char *mode)

Opens file on host. This function has the same semantic as ‘fopen’ except for the first argument.

Return
non zero file handle on success, otherwise 0
Parameters
  • dest: Indicates HW interface to use.
  • path: Path to file.
  • mode: Mode string. See fopen for details.

int esp_apptrace_fclose(esp_apptrace_dest_t dest, void *stream)

Closes file on host. This function has the same semantic as ‘fclose’ except for the first argument.

Return
Zero on success, otherwise non-zero. See fclose for details.
Parameters
  • dest: Indicates HW interface to use.
  • stream: File handle returned by esp_apptrace_fopen.

size_t esp_apptrace_fwrite(esp_apptrace_dest_t dest, const void *ptr, size_t size, size_t nmemb, void *stream)

Writes to file on host. This function has the same semantic as ‘fwrite’ except for the first argument.

Return
Number of written items. See fwrite for details.
Parameters
  • dest: Indicates HW interface to use.
  • ptr: Address of data to write.
  • size: Size of an item.
  • nmemb: Number of items to write.
  • stream: File handle returned by esp_apptrace_fopen.

size_t esp_apptrace_fread(esp_apptrace_dest_t dest, void *ptr, size_t size, size_t nmemb, void *stream)

Read file on host. This function has the same semantic as ‘fread’ except for the first argument.

Return
Number of read items. See fread for details.
Parameters
  • dest: Indicates HW interface to use.
  • ptr: Address to store read data.
  • size: Size of an item.
  • nmemb: Number of items to read.
  • stream: File handle returned by esp_apptrace_fopen.

int esp_apptrace_fseek(esp_apptrace_dest_t dest, void *stream, long offset, int whence)

Set position indicator in file on host. This function has the same semantic as ‘fseek’ except for the first argument.

Return
Zero on success, otherwise non-zero. See fseek for details.
Parameters
  • dest: Indicates HW interface to use.
  • stream: File handle returned by esp_apptrace_fopen.
  • offset: Offset. See fseek for details.
  • whence: Position in file. See fseek for details.

int esp_apptrace_ftell(esp_apptrace_dest_t dest, void *stream)

Get current position indicator for file on host. This function has the same semantic as ‘ftell’ except for the first argument.

Return
Current position in file. See ftell for details.
Parameters
  • dest: Indicates HW interface to use.
  • stream: File handle returned by esp_apptrace_fopen.

int esp_apptrace_fstop(esp_apptrace_dest_t dest)

Indicates to the host that all file operations are completed. This function should be called after all file operations are finished and indicate to the host that it can perform cleanup operations (close open files etc.).

Return
ESP_OK on success, otherwise see esp_err_t
Parameters
  • dest: Indicates HW interface to use.

void esp_gcov_dump(void)

Triggers gcov info dump. This function waits for the host to connect to target before dumping data.

Enumerations

enum esp_apptrace_dest_t

Application trace data destinations bits.

Values:

ESP_APPTRACE_DEST_TRAX = 0x1

JTAG destination.

ESP_APPTRACE_DEST_UART0 = 0x2

UART destination.