Merge branch 'apptrace_breaking_changes' into 'master'

erhankur · erhankur · commit fb3e616750c1 · 2025-07-17T17:45:31.000+02:00
Apptrace breaking changes

Closes IDF-9993 and IDF-4316

See merge request espressif/esp-idf!40380
diff --git a/components/app_trace/Kconfig b/components/app_trace/Kconfig
@@ -8,7 +8,7 @@ menu "Application Level Tracing"
 
         config APPTRACE_DEST_JTAG
             bool "JTAG"
-            select APPTRACE_DEST_TRAX if IDF_TARGET_ARCH_XTENSA
+            select APPTRACE_TRAX_ENABLE if IDF_TARGET_ARCH_XTENSA
             select APPTRACE_MEMBUFS_APPTRACE_PROTO_ENABLE
             select APPTRACE_ENABLE
 
@@ -135,7 +135,7 @@ menu "Application Level Tracing"
             UART task priority. In case of high events rate,
             this parameter could be changed up to (configMAX_PRIORITIES-1).
 
-    config APPTRACE_DEST_TRAX
+    config APPTRACE_TRAX_ENABLE
         bool
         depends on IDF_TARGET_ARCH_XTENSA && !ESP32_TRAX && !ESP32S2_TRAX && !ESP32S3_TRAX
         select ESP32_MEMMAP_TRACEMEM
@@ -186,7 +186,7 @@ menu "Application Level Tracing"
 
     config APPTRACE_BUF_SIZE
         int "Size of the apptrace buffer"
-        depends on APPTRACE_MEMBUFS_APPTRACE_PROTO_ENABLE && !APPTRACE_DEST_TRAX
+        depends on APPTRACE_MEMBUFS_APPTRACE_PROTO_ENABLE && !APPTRACE_TRAX_ENABLE
         default 16384
         help
             Size of the memory buffer for trace data in bytes.
diff --git a/components/app_trace/app_trace.c b/components/app_trace/app_trace.c
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2017-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2017-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0 OR MIT
  */
@@ -80,31 +80,30 @@ ESP_SYSTEM_INIT_FN(esp_apptrace_init, SECONDARY, ESP_SYSTEM_INIT_ALL_CORES, 115)
     return esp_apptrace_init();
 }
 
-void esp_apptrace_down_buffer_config(uint8_t *buf, uint32_t size)
+esp_err_t esp_apptrace_down_buffer_config(esp_apptrace_dest_t dest, uint8_t *buf, uint32_t size)
 {
     esp_apptrace_channel_t *ch;
 
+    if (dest >= ESP_APPTRACE_DEST_MAX) {
+        return ESP_ERR_INVALID_ARG;
+    }
+    if (buf == NULL || size == 0) {
+        return ESP_ERR_INVALID_ARG;
+    }
     if (!s_inited) {
-        return;
-    }
-    // currently down buffer is supported for JTAG interface only
-    // TODO: one more argument should be added to this function to specify HW interface: JTAG, UART0 etc
-    ch = &s_trace_channels[ESP_APPTRACE_DEST_JTAG];
-    if (ch->hw != NULL) {
-        if (ch->hw->down_buffer_config != NULL) {
-            ch->hw->down_buffer_config(ch->hw_data, buf, size);
-        }
-    } else {
-        ESP_APPTRACE_LOGD("Trace destination for JTAG not supported!");
+        return ESP_ERR_INVALID_STATE;
     }
-    ch = &s_trace_channels[ESP_APPTRACE_DEST_UART];
-    if (ch->hw != NULL) {
-        if (ch->hw->down_buffer_config != NULL) {
-            ch->hw->down_buffer_config(ch->hw_data, buf, size);
-        }
-    } else {
-        ESP_APPTRACE_LOGD("Trace destination for UART not supported!");
+
+    ch = &s_trace_channels[dest];
+    if (ch->hw == NULL) {
+        ESP_APPTRACE_LOGE("Trace destination %d not supported!", dest);
+        return ESP_FAIL;
+    }
+    if (ch->hw->down_buffer_config != NULL) {
+        ch->hw->down_buffer_config(ch->hw_data, buf, size);
     }
+
+    return ESP_OK;
 }
 
 uint8_t *esp_apptrace_down_buffer_get(esp_apptrace_dest_t dest, uint32_t *size, uint32_t user_tmo)
diff --git a/components/app_trace/gcov/gcov_rtio.c b/components/app_trace/gcov/gcov_rtio.c
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2017-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2017-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -46,14 +46,19 @@ void gcov_dump_task(void *pvParameter)
         goto gcov_exit;
     }
     ESP_EARLY_LOGV(TAG, "Config apptrace down buf");
-    esp_apptrace_down_buffer_config(down_buf, ESP_GCOV_DOWN_BUF_SIZE);
+    esp_err_t res = esp_apptrace_down_buffer_config(ESP_APPTRACE_DEST_JTAG, down_buf, ESP_GCOV_DOWN_BUF_SIZE);
+    if (res != ESP_OK) {
+        ESP_EARLY_LOGE(TAG, "Failed to config apptrace down buf (%d)!", res);
+        dump_result = res;
+        goto gcov_exit;
+    }
     ESP_EARLY_LOGV(TAG, "Dump data...");
     __gcov_dump();
     // reset dump status to allow incremental data accumulation
     __gcov_reset();
     free(down_buf);
     ESP_EARLY_LOGV(TAG, "Finish file transfer session");
-    dump_result = esp_apptrace_fstop(ESP_APPTRACE_DEST_TRAX);
+    dump_result = esp_apptrace_fstop(ESP_APPTRACE_DEST_JTAG);
     if (dump_result != ESP_OK) {
         ESP_EARLY_LOGE(TAG, "Failed to send files transfer stop cmd (%d)!", dump_result);
     }
@@ -119,7 +124,7 @@ void esp_gcov_dump(void)
 {
     ESP_EARLY_LOGV(TAG, "%s", __FUNCTION__);
 
-    while (!esp_apptrace_host_is_connected(ESP_APPTRACE_DEST_TRAX)) {
+    while (!esp_apptrace_host_is_connected(ESP_APPTRACE_DEST_JTAG)) {
         vTaskDelay(pdMS_TO_TICKS(10));
     }
 
@@ -134,48 +139,48 @@ void esp_gcov_dump(void)
 void *gcov_rtio_fopen(const char *path, const char *mode)
 {
     ESP_EARLY_LOGV(TAG, "%s '%s' '%s'", __FUNCTION__, path, mode);
-    void *f = esp_apptrace_fopen(ESP_APPTRACE_DEST_TRAX, path, mode);
+    void *f = esp_apptrace_fopen(ESP_APPTRACE_DEST_JTAG, path, mode);
     ESP_EARLY_LOGV(TAG, "%s ret %p", __FUNCTION__, f);
     return f;
 }
 
 int gcov_rtio_fclose(void *stream)
 {
     ESP_EARLY_LOGV(TAG, "%s", __FUNCTION__);
-    return esp_apptrace_fclose(ESP_APPTRACE_DEST_TRAX, stream);
+    return esp_apptrace_fclose(ESP_APPTRACE_DEST_JTAG, stream);
 }
 
 size_t gcov_rtio_fread(void *ptr, size_t size, size_t nmemb, void *stream)
 {
     ESP_EARLY_LOGV(TAG, "%s read %u", __FUNCTION__, size * nmemb);
-    size_t sz = esp_apptrace_fread(ESP_APPTRACE_DEST_TRAX, ptr, size, nmemb, stream);
+    size_t sz = esp_apptrace_fread(ESP_APPTRACE_DEST_JTAG, ptr, size, nmemb, stream);
     ESP_EARLY_LOGV(TAG, "%s actually read %u", __FUNCTION__, sz);
     return sz;
 }
 
 size_t gcov_rtio_fwrite(const void *ptr, size_t size, size_t nmemb, void *stream)
 {
     ESP_EARLY_LOGV(TAG, "%s", __FUNCTION__);
-    return esp_apptrace_fwrite(ESP_APPTRACE_DEST_TRAX, ptr, size, nmemb, stream);
+    return esp_apptrace_fwrite(ESP_APPTRACE_DEST_JTAG, ptr, size, nmemb, stream);
 }
 
 int gcov_rtio_fseek(void *stream, long offset, int whence)
 {
-    int ret = esp_apptrace_fseek(ESP_APPTRACE_DEST_TRAX, stream, offset, whence);
+    int ret = esp_apptrace_fseek(ESP_APPTRACE_DEST_JTAG, stream, offset, whence);
     ESP_EARLY_LOGV(TAG, "%s(%p %ld %d) = %d", __FUNCTION__, stream, offset, whence, ret);
     return ret;
 }
 
 long gcov_rtio_ftell(void *stream)
 {
-    long ret = esp_apptrace_ftell(ESP_APPTRACE_DEST_TRAX, stream);
+    long ret = esp_apptrace_ftell(ESP_APPTRACE_DEST_JTAG, stream);
     ESP_EARLY_LOGV(TAG, "%s(%p) = %ld", __FUNCTION__, stream, ret);
     return ret;
 }
 
 int gcov_rtio_feof(void *stream)
 {
-    int ret = esp_apptrace_feof(ESP_APPTRACE_DEST_TRAX, stream);
+    int ret = esp_apptrace_feof(ESP_APPTRACE_DEST_JTAG, stream);
     ESP_EARLY_LOGV(TAG, "%s(%p) = %d", __FUNCTION__, stream, ret);
     return ret;
 }
diff --git a/components/app_trace/include/esp_app_trace.h b/components/app_trace/include/esp_app_trace.h
@@ -18,11 +18,9 @@ extern "C" {
  * Application trace data destinations bits.
  */
 typedef enum {
-    ESP_APPTRACE_DEST_JTAG = 1,                         ///< JTAG destination
-    ESP_APPTRACE_DEST_TRAX = ESP_APPTRACE_DEST_JTAG,    ///< xxx_TRAX name is obsolete, use more common xxx_JTAG
-    ESP_APPTRACE_DEST_UART,                             ///< UART destination
-    ESP_APPTRACE_DEST_MAX = ESP_APPTRACE_DEST_UART + 1,
-    ESP_APPTRACE_DEST_NUM
+    ESP_APPTRACE_DEST_JTAG,                         ///< JTAG destination
+    ESP_APPTRACE_DEST_UART,                         ///< UART destination
+    ESP_APPTRACE_DEST_MAX,
 } esp_apptrace_dest_t;
 
 /**
@@ -39,10 +37,13 @@ esp_err_t esp_apptrace_init(void);
  *        @note 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.
  *
+ * @param dest Indicates HW interface to configure.
  * @param buf Address of buffer to use for down channel (host to target) data.
  * @param size Size of the buffer.
+ *
+ * @return ESP_OK on success, otherwise see esp_err_t
  */
-void esp_apptrace_down_buffer_config(uint8_t *buf, uint32_t size);
+esp_err_t esp_apptrace_down_buffer_config(esp_apptrace_dest_t dest, uint8_t *buf, uint32_t size);
 
 /**
  * @brief Allocates buffer for trace data.
@@ -117,7 +118,7 @@ esp_err_t esp_apptrace_flush(esp_apptrace_dest_t dest, uint32_t tmo);
  *        This is a special version of esp_apptrace_flush which should be called from panic handler.
  *
  * @param dest   Indicates HW interface to flush data on.
- * @param min_sz Threshold for flushing data. If current filling level is above this value, data will be flushed. TRAX destinations only.
+ * @param min_sz Threshold for flushing data. If current filling level is above this value, data will be flushed. JTAG destinations only.
  * @param tmo    Timeout for operation (in us). Use ESP_APPTRACE_TMO_INFINITE to wait indefinitely.
  *
  * @return ESP_OK on success, otherwise see esp_err_t
diff --git a/components/app_trace/sys_view/esp/SEGGER_RTT_esp.c b/components/app_trace/sys_view/esp/SEGGER_RTT_esp.c
@@ -42,7 +42,7 @@ static uint8_t s_down_buf[SYSVIEW_DOWN_BUF_SIZE];
 #endif // CONFIG_APPTRACE_SV_DEST_CPU_0
 
 #elif CONFIG_APPTRACE_SV_DEST_JTAG || (CONFIG_APPTRACE_ENABLE && CONFIG_APPTRACE_DEST_UART_NONE)
-#define ESP_APPTRACE_DEST_SYSVIEW ESP_APPTRACE_DEST_TRAX
+#define ESP_APPTRACE_DEST_SYSVIEW ESP_APPTRACE_DEST_JTAG
 #endif
 
 /*********************************************************************
@@ -60,7 +60,7 @@ static uint8_t s_down_buf[SYSVIEW_DOWN_BUF_SIZE];
 *    Flushes buffered events.
 *
 *  Parameters
-*    min_sz  Threshold for flushing data. If current filling level is above this value, data will be flushed. TRAX destinations only.
+*    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.
 *
 *  Return value
@@ -91,7 +91,7 @@ void SEGGER_RTT_ESP_FlushNoLock(unsigned long min_sz, unsigned long tmo)
 *    Flushes buffered events.
 *
 *  Parameters
-*    min_sz  Threshold for flushing data. If current filling level is above this value, data will be flushed. TRAX destinations only.
+*    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.
 *
 *  Return value
@@ -288,8 +288,7 @@ int SEGGER_RTT_ConfigUpBuffer(unsigned BufferIndex, const char* sName, void* pBu
 */
 int SEGGER_RTT_ConfigDownBuffer(unsigned BufferIndex, const char* sName, void* pBuffer, unsigned BufferSize, unsigned Flags)
 {
-    esp_apptrace_down_buffer_config(s_down_buf, sizeof(s_down_buf));
-    return 0;
+    return esp_apptrace_down_buffer_config(ESP_APPTRACE_DEST_SYSVIEW, s_down_buf, sizeof(s_down_buf));
 }
 
 /*************************** Init hook ****************************
diff --git a/components/app_trace/test_apps/main/test_trace.c b/components/app_trace/test_apps/main/test_trace.c
@@ -67,9 +67,9 @@ const static char *TAG = "esp_apptrace_test";
 #define ESP_APPTRACE_TEST_LOGO( format, ... )  ESP_APPTRACE_TEST_LOG_LEVEL(E, ESP_LOG_NONE, format, ##__VA_ARGS__)
 
 #if CONFIG_APPTRACE_SV_ENABLE == 0
-#define ESP_APPTRACE_TEST_WRITE(_b_, _s_)            esp_apptrace_write(ESP_APPTRACE_DEST_TRAX, _b_, _s_, ESP_APPTRACE_TMO_INFINITE)
-#define ESP_APPTRACE_TEST_WRITE_FROM_ISR(_b_, _s_)   esp_apptrace_write(ESP_APPTRACE_DEST_TRAX, _b_, _s_, 0UL)
-#define ESP_APPTRACE_TEST_WRITE_NOWAIT(_b_, _s_)     esp_apptrace_write(ESP_APPTRACE_DEST_TRAX, _b_, _s_, 0)
+#define ESP_APPTRACE_TEST_WRITE(_b_, _s_)            esp_apptrace_write(ESP_APPTRACE_DEST_JTAG, _b_, _s_, ESP_APPTRACE_TMO_INFINITE)
+#define ESP_APPTRACE_TEST_WRITE_FROM_ISR(_b_, _s_)   esp_apptrace_write(ESP_APPTRACE_DEST_JTAG, _b_, _s_, 0UL)
+#define ESP_APPTRACE_TEST_WRITE_NOWAIT(_b_, _s_)     esp_apptrace_write(ESP_APPTRACE_DEST_JTAG, _b_, _s_, 0)
 
 typedef struct {
     uint8_t *buf;
@@ -625,7 +625,7 @@ static int esp_logtrace_printf(const char *fmt, ...)
 
     va_start(ap, fmt);
 
-    int ret = esp_apptrace_vprintf_to(ESP_APPTRACE_DEST_TRAX, ESP_APPTRACE_TMO_INFINITE, fmt, ap);
+    int ret = esp_apptrace_vprintf_to(ESP_APPTRACE_DEST_JTAG, ESP_APPTRACE_TMO_INFINITE, fmt, ap);
 
     va_end(ap);
 
@@ -657,7 +657,7 @@ static void esp_logtrace_task(void *p)
             break;
         }
     }
-    esp_err_t ret = esp_apptrace_flush(ESP_APPTRACE_DEST_TRAX, ESP_APPTRACE_TMO_INFINITE);
+    esp_err_t ret = esp_apptrace_flush(ESP_APPTRACE_DEST_JTAG, ESP_APPTRACE_TMO_INFINITE);
     if (ret != ESP_OK) {
         ESP_APPTRACE_TEST_LOGE("Failed to flush printf buf (%d)!", ret);
     }
diff --git a/components/esp_system/panic.c b/components/esp_system/panic.c
@@ -361,7 +361,7 @@ void esp_panic_handler(panic_info_t *info)
 #if CONFIG_APPTRACE_SV_ENABLE
         SEGGER_RTT_ESP_FlushNoLock(CONFIG_APPTRACE_POSTMORTEM_FLUSH_THRESH, APPTRACE_ONPANIC_HOST_FLUSH_TMO);
 #else
-        esp_apptrace_flush_nolock(ESP_APPTRACE_DEST_TRAX, CONFIG_APPTRACE_POSTMORTEM_FLUSH_THRESH,
+        esp_apptrace_flush_nolock(ESP_APPTRACE_DEST_JTAG, CONFIG_APPTRACE_POSTMORTEM_FLUSH_THRESH,
                                   APPTRACE_ONPANIC_HOST_FLUSH_TMO);
 #endif
 #endif
@@ -401,7 +401,7 @@ void esp_panic_handler(panic_info_t *info)
 #if CONFIG_APPTRACE_SV_ENABLE
     SEGGER_RTT_ESP_FlushNoLock(CONFIG_APPTRACE_POSTMORTEM_FLUSH_THRESH, APPTRACE_ONPANIC_HOST_FLUSH_TMO);
 #else
-    esp_apptrace_flush_nolock(ESP_APPTRACE_DEST_TRAX, CONFIG_APPTRACE_POSTMORTEM_FLUSH_THRESH,
+    esp_apptrace_flush_nolock(ESP_APPTRACE_DEST_JTAG, CONFIG_APPTRACE_POSTMORTEM_FLUSH_THRESH,
                               APPTRACE_ONPANIC_HOST_FLUSH_TMO);
 #endif
 #endif // CONFIG_APPTRACE_ENABLE
@@ -472,7 +472,7 @@ void __attribute__((noreturn, no_sanitize_undefined)) panic_abort(const char *de
 #if CONFIG_APPTRACE_SV_ENABLE
     SEGGER_RTT_ESP_FlushNoLock(CONFIG_APPTRACE_POSTMORTEM_FLUSH_THRESH, APPTRACE_ONPANIC_HOST_FLUSH_TMO);
 #else
-    esp_apptrace_flush_nolock(ESP_APPTRACE_DEST_TRAX, CONFIG_APPTRACE_POSTMORTEM_FLUSH_THRESH,
+    esp_apptrace_flush_nolock(ESP_APPTRACE_DEST_JTAG, CONFIG_APPTRACE_POSTMORTEM_FLUSH_THRESH,
                               APPTRACE_ONPANIC_HOST_FLUSH_TMO);
 #endif
 #endif
diff --git a/docs/en/api-guides/app_trace.rst b/docs/en/api-guides/app_trace.rst
@@ -78,7 +78,7 @@ In general, users should decide what type of data should be transferred in every
         #include "esp_app_trace.h"
         ...
         char buf[] = "Hello World!";
-        esp_err_t res = esp_apptrace_write(ESP_APPTRACE_DEST_TRAX, buf, strlen(buf), ESP_APPTRACE_TMO_INFINITE);
+        esp_err_t res = esp_apptrace_write(ESP_APPTRACE_DEST_JTAG, buf, strlen(buf), ESP_APPTRACE_TMO_INFINITE);
         if (res != ESP_OK) {
             ESP_LOGE(TAG, "Failed to write data to host!");
             return res;
@@ -91,13 +91,13 @@ In general, users should decide what type of data should be transferred in every
         #include "esp_app_trace.h"
         ...
         int number = 10;
-        char *ptr = (char *)esp_apptrace_buffer_get(ESP_APPTRACE_DEST_TRAX, 32, 100/*tmo in us*/);
+        char *ptr = (char *)esp_apptrace_buffer_get(ESP_APPTRACE_DEST_JTAG, 32, 100/*tmo in us*/);
         if (ptr == NULL) {
             ESP_LOGE(TAG, "Failed to get buffer!");
             return ESP_FAIL;
         }
         sprintf(ptr, "Here is the number %d", number);
-        esp_err_t res = esp_apptrace_buffer_put(ESP_APPTRACE_DEST_TRAX, ptr, 100/*tmo in us*/);
+        esp_err_t res = esp_apptrace_buffer_put(ESP_APPTRACE_DEST_JTAG, ptr, 100/*tmo in us*/);
         if (res != ESP_OK) {
             /* in case of error host tracing tool (e.g., OpenOCD) will report incomplete user buffer */
             ESP_LOGE(TAG, "Failed to put buffer!");
@@ -115,9 +115,13 @@ In general, users should decide what type of data should be transferred in every
         size_t sz = sizeof(buf);
 
         /* config down buffer */
-        esp_apptrace_down_buffer_config(down_buf, sizeof(down_buf));
+        esp_err_t res = esp_apptrace_down_buffer_config(ESP_APPTRACE_DEST_JTAG, down_buf, sizeof(down_buf));
+        if (res != ESP_OK) {
+            ESP_LOGE(TAG, "Failed to config down buffer!");
+            return res;
+        }
         /* check for incoming data and read them if any */
-        esp_err_t res = esp_apptrace_read(ESP_APPTRACE_DEST_TRAX, buf, &sz, 0/*do not wait*/);
+        res = esp_apptrace_read(ESP_APPTRACE_DEST_JTAG, buf, &sz, 0/*do not wait*/);
         if (res != ESP_OK) {
             ESP_LOGE(TAG, "Failed to read data from host!");
             return res;
@@ -138,8 +142,12 @@ In general, users should decide what type of data should be transferred in every
         size_t sz = 32;
 
         /* config down buffer */
-        esp_apptrace_down_buffer_config(down_buf, sizeof(down_buf));
-        char *ptr = (char *)esp_apptrace_down_buffer_get(ESP_APPTRACE_DEST_TRAX, &sz, 100/*tmo in us*/);
+        esp_err_t res = esp_apptrace_down_buffer_config(ESP_APPTRACE_DEST_JTAG, down_buf, sizeof(down_buf));
+        if (res != ESP_OK) {
+            ESP_LOGE(TAG, "Failed to config down buffer!");
+            return res;
+        }
+        char *ptr = (char *)esp_apptrace_down_buffer_get(ESP_APPTRACE_DEST_JTAG, &sz, 100/*tmo in us*/);
         if (ptr == NULL) {
             ESP_LOGE(TAG, "Failed to get buffer!");
             return ESP_FAIL;
@@ -150,7 +158,7 @@ In general, users should decide what type of data should be transferred in every
         } else {
             printf("No data");
         }
-        esp_err_t res = esp_apptrace_down_buffer_put(ESP_APPTRACE_DEST_TRAX, ptr, 100/*tmo in us*/);
+        res = esp_apptrace_down_buffer_put(ESP_APPTRACE_DEST_JTAG, ptr, 100/*tmo in us*/);
         if (res != ESP_OK) {
             /* in case of error host tracing tool (e.g., OpenOCD) will report incomplete user buffer */
             ESP_LOGE(TAG, "Failed to put buffer!");
diff --git a/docs/en/migration-guides/release-6.x/6.0/system.rst b/docs/en/migration-guides/release-6.x/6.0/system.rst
diff --git a/docs/zh_CN/api-guides/app_trace.rst b/docs/zh_CN/api-guides/app_trace.rst
diff --git a/examples/network/simple_sniffer/main/Kconfig.projbuild b/examples/network/simple_sniffer/main/Kconfig.projbuild
diff --git a/examples/network/simple_sniffer/main/cmd_pcap.c b/examples/network/simple_sniffer/main/cmd_pcap.c

Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,5 @@`
`1`	`1`	`/*`
`2`		`- * SPDX-FileCopyrightText: 2017-2024 Espressif Systems (Shanghai) CO LTD`
	`2`	`+ * SPDX-FileCopyrightText: 2017-2025 Espressif Systems (Shanghai) CO LTD`
`3`	`3`	`*`
`4`	`4`	`* SPDX-License-Identifier: Apache-2.0`
`5`	`5`	`*/`
`@@ -46,14 +46,19 @@ void gcov_dump_task(void *pvParameter)`
`46`	`46`	`goto gcov_exit;`
`47`	`47`	`}`
`48`	`48`	`ESP_EARLY_LOGV(TAG, "Config apptrace down buf");`
`49`		`- esp_apptrace_down_buffer_config(down_buf, ESP_GCOV_DOWN_BUF_SIZE);`
	`49`	`+ esp_err_t res = esp_apptrace_down_buffer_config(ESP_APPTRACE_DEST_JTAG, down_buf, ESP_GCOV_DOWN_BUF_SIZE);`
	`50`	`+ if (res != ESP_OK) {`
	`51`	`+ ESP_EARLY_LOGE(TAG, "Failed to config apptrace down buf (%d)!", res);`
	`52`	`+ dump_result = res;`
	`53`	`+ goto gcov_exit;`
	`54`	`+ }`
`50`	`55`	`ESP_EARLY_LOGV(TAG, "Dump data...");`
`51`	`56`	`__gcov_dump();`
`52`	`57`	`// reset dump status to allow incremental data accumulation`
`53`	`58`	`__gcov_reset();`
`54`	`59`	`free(down_buf);`
`55`	`60`	`ESP_EARLY_LOGV(TAG, "Finish file transfer session");`
`56`		`- dump_result = esp_apptrace_fstop(ESP_APPTRACE_DEST_TRAX);`
	`61`	`+ dump_result = esp_apptrace_fstop(ESP_APPTRACE_DEST_JTAG);`
`57`	`62`	`if (dump_result != ESP_OK) {`
`58`	`63`	`ESP_EARLY_LOGE(TAG, "Failed to send files transfer stop cmd (%d)!", dump_result);`
`59`	`64`	`}`
`@@ -119,7 +124,7 @@ void esp_gcov_dump(void)`
`119`	`124`	`{`
`120`	`125`	`ESP_EARLY_LOGV(TAG, "%s", __FUNCTION__);`
`121`	`126`
`122`		`- while (!esp_apptrace_host_is_connected(ESP_APPTRACE_DEST_TRAX)) {`
	`127`	`+ while (!esp_apptrace_host_is_connected(ESP_APPTRACE_DEST_JTAG)) {`
`123`	`128`	`vTaskDelay(pdMS_TO_TICKS(10));`
`124`	`129`	`}`
`125`	`130`
`@@ -134,48 +139,48 @@ void esp_gcov_dump(void)`
`134`	`139`	`void gcov_rtio_fopen(const char path, const char *mode)`
`135`	`140`	`{`
`136`	`141`	`ESP_EARLY_LOGV(TAG, "%s '%s' '%s'", __FUNCTION__, path, mode);`
`137`		`- void *f = esp_apptrace_fopen(ESP_APPTRACE_DEST_TRAX, path, mode);`
	`142`	`+ void *f = esp_apptrace_fopen(ESP_APPTRACE_DEST_JTAG, path, mode);`
`138`	`143`	`ESP_EARLY_LOGV(TAG, "%s ret %p", __FUNCTION__, f);`
`139`	`144`	`return f;`
`140`	`145`	`}`
`141`	`146`
`142`	`147`	`int gcov_rtio_fclose(void *stream)`
`143`	`148`	`{`
`144`	`149`	`ESP_EARLY_LOGV(TAG, "%s", __FUNCTION__);`
`145`		`- return esp_apptrace_fclose(ESP_APPTRACE_DEST_TRAX, stream);`
	`150`	`+ return esp_apptrace_fclose(ESP_APPTRACE_DEST_JTAG, stream);`
`146`	`151`	`}`
`147`	`152`
`148`	`153`	`size_t gcov_rtio_fread(void ptr, size_t size, size_t nmemb, void stream)`
`149`	`154`	`{`
`150`	`155`	`ESP_EARLY_LOGV(TAG, "%s read %u", __FUNCTION__, size * nmemb);`
`151`		`- size_t sz = esp_apptrace_fread(ESP_APPTRACE_DEST_TRAX, ptr, size, nmemb, stream);`
	`156`	`+ size_t sz = esp_apptrace_fread(ESP_APPTRACE_DEST_JTAG, ptr, size, nmemb, stream);`
`152`	`157`	`ESP_EARLY_LOGV(TAG, "%s actually read %u", __FUNCTION__, sz);`
`153`	`158`	`return sz;`
`154`	`159`	`}`
`155`	`160`
`156`	`161`	`size_t gcov_rtio_fwrite(const void ptr, size_t size, size_t nmemb, void stream)`
`157`	`162`	`{`
`158`	`163`	`ESP_EARLY_LOGV(TAG, "%s", __FUNCTION__);`
`159`		`- return esp_apptrace_fwrite(ESP_APPTRACE_DEST_TRAX, ptr, size, nmemb, stream);`
	`164`	`+ return esp_apptrace_fwrite(ESP_APPTRACE_DEST_JTAG, ptr, size, nmemb, stream);`
`160`	`165`	`}`
`161`	`166`
`162`	`167`	`int gcov_rtio_fseek(void *stream, long offset, int whence)`
`163`	`168`	`{`
`164`		`- int ret = esp_apptrace_fseek(ESP_APPTRACE_DEST_TRAX, stream, offset, whence);`
	`169`	`+ int ret = esp_apptrace_fseek(ESP_APPTRACE_DEST_JTAG, stream, offset, whence);`
`165`	`170`	`ESP_EARLY_LOGV(TAG, "%s(%p %ld %d) = %d", __FUNCTION__, stream, offset, whence, ret);`
`166`	`171`	`return ret;`
`167`	`172`	`}`
`168`	`173`
`169`	`174`	`long gcov_rtio_ftell(void *stream)`
`170`	`175`	`{`
`171`		`- long ret = esp_apptrace_ftell(ESP_APPTRACE_DEST_TRAX, stream);`
	`176`	`+ long ret = esp_apptrace_ftell(ESP_APPTRACE_DEST_JTAG, stream);`
`172`	`177`	`ESP_EARLY_LOGV(TAG, "%s(%p) = %ld", __FUNCTION__, stream, ret);`
`173`	`178`	`return ret;`
`174`	`179`	`}`
`175`	`180`
`176`	`181`	`int gcov_rtio_feof(void *stream)`
`177`	`182`	`{`
`178`		`- int ret = esp_apptrace_feof(ESP_APPTRACE_DEST_TRAX, stream);`
	`183`	`+ int ret = esp_apptrace_feof(ESP_APPTRACE_DEST_JTAG, stream);`
`179`	`184`	`ESP_EARLY_LOGV(TAG, "%s(%p) = %d", __FUNCTION__, stream, ret);`
`180`	`185`	`return ret;`
`181`	`186`	`}`
Original file line number	Diff line number	Diff line change
`@@ -42,7 +42,7 @@ static uint8_t s_down_buf[SYSVIEW_DOWN_BUF_SIZE];`
`42`	`42`	`#endif // CONFIG_APPTRACE_SV_DEST_CPU_0`
`43`	`43`
`44`	`44`	`#elif CONFIG_APPTRACE_SV_DEST_JTAG \|\| (CONFIG_APPTRACE_ENABLE && CONFIG_APPTRACE_DEST_UART_NONE)`
`45`		`-#define ESP_APPTRACE_DEST_SYSVIEW ESP_APPTRACE_DEST_TRAX`
	`45`	`+#define ESP_APPTRACE_DEST_SYSVIEW ESP_APPTRACE_DEST_JTAG`
`46`	`46`	`#endif`
`47`	`47`
`48`	`48`	`/*********************************************************************`
`@@ -60,7 +60,7 @@ static uint8_t s_down_buf[SYSVIEW_DOWN_BUF_SIZE];`
`60`	`60`	`* Flushes buffered events.`
`61`	`61`	`*`
`62`	`62`	`* Parameters`
`63`		`-* min_sz Threshold for flushing data. If current filling level is above this value, data will be flushed. TRAX destinations only.`
	`63`	`+* min_sz Threshold for flushing data. If current filling level is above this value, data will be flushed. JTAG destinations only.`
`64`	`64`	`* tmo Timeout for operation (in us). Use ESP_APPTRACE_TMO_INFINITE to wait indefinitely.`
`65`	`65`	`*`
`66`	`66`	`* Return value`
`@@ -91,7 +91,7 @@ void SEGGER_RTT_ESP_FlushNoLock(unsigned long min_sz, unsigned long tmo)`
`91`	`91`	`* Flushes buffered events.`
`92`	`92`	`*`
`93`	`93`	`* Parameters`
`94`		`-* min_sz Threshold for flushing data. If current filling level is above this value, data will be flushed. TRAX destinations only.`
	`94`	`+* min_sz Threshold for flushing data. If current filling level is above this value, data will be flushed. JTAG destinations only.`
`95`	`95`	`* tmo Timeout for operation (in us). Use ESP_APPTRACE_TMO_INFINITE to wait indefinitely.`
`96`	`96`	`*`
`97`	`97`	`* Return value`
`@@ -288,8 +288,7 @@ int SEGGER_RTT_ConfigUpBuffer(unsigned BufferIndex, const char* sName, void* pBu`
`288`	`288`	`*/`
`289`	`289`	`int SEGGER_RTT_ConfigDownBuffer(unsigned BufferIndex, const char* sName, void* pBuffer, unsigned BufferSize, unsigned Flags)`
`290`	`290`	`{`
`291`		`- esp_apptrace_down_buffer_config(s_down_buf, sizeof(s_down_buf));`
`292`		`- return 0;`
	`291`	`+ return esp_apptrace_down_buffer_config(ESP_APPTRACE_DEST_SYSVIEW, s_down_buf, sizeof(s_down_buf));`
`293`	`292`	`}`
`294`	`293`
`295`	`294`	`/************************* Init hook **************************`