# 应用级追踪

[English]

## 概述

ESP-IDF 支持用于程序行为分析的 应用级追踪 功能。在 menuconfig 中启用该功能后，即可通过 JTAG 接口在主机和 ESP32-C3 之间传输任意数据，最小化程序的执行开销。

在程序运行时，开发人员可使用该库向主机发送应用程序的特定执行状态，并接收来自应用程序的命令或其他信息。该库的主要用例包括：

1. 收集特定应用程序的数据，参见 特定应用程序的跟踪。

2. 向主机发送轻量级日志，参见 记录日志到主机。

3. 系统行为分析，参见 基于 SEGGER SystemView 的系统行为分析。

## 应用示例

- system/app_trace_to_plot 演示了如何使用应用层跟踪库通过 JTAG 发送并绘制虚拟传感器数据到主机上，提供了比通过 UART 记录更快的替代方案。

- system/app_trace_basic 演示了如何使用应用层跟踪库通过 JTAG 向主机记录消息，提供了比 UART 记录更快的替代方案。

## API 参考

### Header File

- components/app_trace/include/esp_app_trace.h

- This header file can be included with:

  >     #include "esp_app_trace.h"

- This header file is a part of the API provided by the `app_trace` component. To declare that your component depends on `app_trace`, add the following to your CMakeLists.txt:

  >     REQUIRES app_trace

  > or

  >     PRIV_REQUIRES app_trace

### Functions

esp_apptrace_config_t esp_apptrace_get_user_params(void)

  Get custom trace initialization parameters (optional callback)

  This is an optional callback function that user applications can implement to provide custom trace configuration. A weak default implementation exists in the app_trace component that returns menuconfig defaults (APPTRACE_CONFIG_DEFAULT()). User applications can override this by providing their own implementation.

  This function is called during early system initialization (before app_main) on all cores.

esp_err_t esp_apptrace_down_buffer_config(uint8_t *buf, uint32_t size)

  Configures down buffer.

  备注

  Needs to be called before attempting to receive any data using esp_apptrace_down_buffer_get and esp_apptrace_read. This function does not protect internal data by lock.

  参数:

    - buf -- Address of buffer to use for down channel (host to target) data.

    - size -- Size of the buffer.

  返回:

    ESP_OK on success, otherwise see esp_err_t

uint8_t *esp_apptrace_buffer_get(uint32_t size, uint32_t tmo)

  Allocates buffer for trace data. Once the data in the buffer is ready to be sent, esp_apptrace_buffer_put must be called to indicate it.

  参数:

    - size -- Size of data to write to trace buffer.

    - tmo -- Timeout for operation (in us). Use ESP_APPTRACE_TMO_INFINITE to wait indefinitely.

  返回:

    non-NULL on success, otherwise NULL.

esp_err_t esp_apptrace_buffer_put(uint8_t *ptr, uint32_t tmo)

  Indicates that the data in the buffer is ready to be sent. This function is a counterpart of and must be preceded by 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 indefinitely.

  返回:

    ESP_OK on success, otherwise see esp_err_t

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

  Writes data to trace buffer.

  参数:

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

  返回:

    ESP_OK on success, otherwise see esp_err_t

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

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

  参数:

    - tmo -- Timeout for operation (in us). Use ESP_APPTRACE_TMO_INFINITE to wait indefinitely.

    - fmt -- Address of format string.

    - ap -- List of arguments.

  返回:

    Number of bytes written.

int esp_apptrace_vprintf(const char *fmt, va_list ap)

  vprintf-like function to send log messages to host.

  参数:

    - fmt -- Address of format string.

    - ap -- List of arguments.

  返回:

    Number of bytes written.

esp_err_t esp_apptrace_flush(uint32_t tmo)

  Flushes remaining data in trace buffer to host.

  参数:

    tmo -- Timeout for operation (in us). Use ESP_APPTRACE_TMO_INFINITE to wait indefinitely.

  返回:

    ESP_OK on success, otherwise see esp_err_t

esp_err_t esp_apptrace_flush_nolock(uint32_t min_sz, uint32_t tmo)

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

  参数:

    - min_sz -- Threshold for flushing data. If current filling level is above this value, data will be flushed. JTAG destinations only.

    - tmo -- Timeout for operation (in us). Use ESP_APPTRACE_TMO_INFINITE to wait indefinitely.

  返回:

    ESP_OK on success, otherwise see esp_err_t

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

  Reads host data from trace buffer.

  参数:

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

  返回:

    ESP_OK on success, otherwise see esp_err_t

uint8_t *esp_apptrace_down_buffer_get(uint32_t *size, uint32_t tmo)

  Retrieves incoming data buffer if any. Once data in the buffer is processed, esp_apptrace_down_buffer_put must be called to indicate it.

  参数:

    - size -- Address to store size of available data in down buffer. Must be initialized with requested value.

    - tmo -- Timeout for operation (in us). Use ESP_APPTRACE_TMO_INFINITE to wait indefinitely.

  返回:

    non-NULL on success, otherwise NULL.

esp_err_t esp_apptrace_down_buffer_put(uint8_t *ptr, uint32_t tmo)

  Indicates that the data in the down buffer is processed. This function is a counterpart of and must be preceded by 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 indefinitely.

  返回:

    ESP_OK on success, otherwise see esp_err_t

bool esp_apptrace_host_is_connected(void)

  Checks whether host is connected.

  返回:

    true if host is connected, otherwise false

esp_apptrace_dest_t esp_apptrace_get_destination(void)

  Gets the destination of the application trace.

  返回:

    The destination of the application trace.

esp_err_t esp_apptrace_set_header_size(esp_apptrace_header_size_t header_size)

  Sets the header size of the application trace packet.

  参数:

    header_size -- The header size to set.

  返回:

    ESP_OK on success, otherwise see esp_err_t

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

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

  参数:

    - path -- Path to file.

    - mode -- Mode string. See fopen for details.

  返回:

    non zero file handle on success, otherwise 0

int esp_apptrace_fclose(void *stream)

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

  参数:

    stream -- File handle returned by esp_apptrace_fopen.

  返回:

    Zero on success, otherwise non-zero. See fclose for details.

size_t esp_apptrace_fwrite(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.

  参数:

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

  返回:

    Number of written items. See fwrite for details.

size_t esp_apptrace_fread(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.

  参数:

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

  返回:

    Number of read items. See fread for details.

int esp_apptrace_fseek(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.

  参数:

    - stream -- File handle returned by esp_apptrace_fopen.

    - offset -- Offset. See fseek for details.

    - whence -- Position in file. See fseek for details.

  返回:

    Zero on success, otherwise non-zero. See fseek for details.

int esp_apptrace_ftell(void *stream)

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

  参数:

    stream -- File handle returned by esp_apptrace_fopen.

  返回:

    Current position in file. See ftell for details.

int esp_apptrace_fstop(void)

  Indicates to the host that all file operations are complete. 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.).

  返回:

    ESP_OK on success, otherwise see esp_err_t

int esp_apptrace_feof(void *stream)

  Test end-of-file indicator on a stream. This function has the same semantic as 'feof' except for the first argument.

  参数:

    stream -- File handle returned by esp_apptrace_fopen.

  返回:

    Non-Zero if end-of-file indicator is set for stream. See feof for details.

### Macros

APPTRACE_JTAG_CONFIG_DEFAULT()

APPTRACE_UART_CONFIG_DEFAULT()

APPTRACE_CONFIG_DEFAULT()

### Header File

- components/app_trace/include/esp_sysview_trace.h

- This header file can be included with:

  >     #include "esp_sysview_trace.h"

- This header file is a part of the API provided by the `app_trace` component. To declare that your component depends on `app_trace`, add the following to your CMakeLists.txt:

  >     REQUIRES app_trace

  > or

  >     PRIV_REQUIRES app_trace

### Functions

static inline esp_err_t esp_sysview_flush(uint32_t tmo)

  Flushes remaining data in SystemView trace buffer to host.

  参数:

    tmo -- Timeout for operation (in us). Use ESP_APPTRACE_TMO_INFINITE to wait indefinitely.

  返回:

    ESP_OK.

int esp_sysview_vprintf(const char *format, va_list args)

  vprintf-like function to sent log messages to the host.

  参数:

    - format -- Address of format string.

    - args -- List of arguments.

  返回:

    Number of bytes written.

esp_err_t esp_sysview_heap_trace_start(uint32_t tmo)

  Starts SystemView heap tracing.

  参数:

    tmo -- Timeout (in us) to wait for the host to be connected. Use -1 to wait forever.

  返回:

    ESP_OK on success, ESP_ERR_TIMEOUT if operation has been timed out.

esp_err_t esp_sysview_heap_trace_stop(void)

  Stops SystemView heap tracing.

  返回:

    ESP_OK.

void esp_sysview_heap_trace_alloc(void *addr, uint32_t size, const void *callers)

  Sends heap allocation event to the host.

  参数:

    - addr -- Address of allocated block.

    - size -- Size of allocated block.

    - callers -- Pointer to array with callstack addresses. Array size must be CONFIG_HEAP_TRACING_STACK_DEPTH.

void esp_sysview_heap_trace_free(void *addr, const void *callers)

  Sends heap de-allocation event to the host.

  参数:

    - addr -- Address of de-allocated block.

    - callers -- Pointer to array with callstack addresses. Array size must be CONFIG_HEAP_TRACING_STACK_DEPTH.

此文档对您有帮助吗？

- 反馈已收到，谢谢！
- 如果您有其他意见，欢迎填写乐鑫文档反馈表。

- 我们重视您的反馈。
- 您可以填写乐鑫文档反馈表告诉我们如何改进该文档。