change(app_trace): add dest parameter to down buffer config

erhankur · espressif-bot · commit 8a2692edb6c2 · 2025-07-17T12:36:39.000+08:00
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,7 +46,12 @@ 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
diff --git a/components/app_trace/include/esp_app_trace.h b/components/app_trace/include/esp_app_trace.h
@@ -17,7 +17,7 @@ extern "C" {
 /**
  * Application trace data destinations bits.
  */
- typedef enum {
+typedef enum {
     ESP_APPTRACE_DEST_JTAG,                         ///< JTAG destination
     ESP_APPTRACE_DEST_UART,                         ///< UART destination
     ESP_APPTRACE_DEST_MAX,
@@ -37,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.
diff --git a/components/app_trace/sys_view/esp/SEGGER_RTT_esp.c b/components/app_trace/sys_view/esp/SEGGER_RTT_esp.c
@@ -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/docs/en/api-guides/app_trace.rst b/docs/en/api-guides/app_trace.rst
@@ -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_JTAG, 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,7 +142,11 @@ 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));
+        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!");
@@ -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_JTAG, 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
@@ -61,6 +61,24 @@ Removed extra data buffering option. `CONFIG_APPTRACE_PENDING_DATA_SIZE_MAX` is
 
 Removed deprecated `ESP_APPTRACE_DEST_TRAX` enum value. Use `ESP_APPTRACE_DEST_JTAG` instead.
 
+The :cpp:func:`esp_apptrace_down_buffer_config` function now requires a destination parameter and returns an error code for proper error handling.
+
+Old Version:
+
+.. code-block:: c
+
+    esp_apptrace_down_buffer_config(down_buf, sizeof(down_buf));
+
+Update to:
+
+.. code-block:: c
+
+    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;
+    }
+
 FreeRTOS
 --------
 
diff --git a/docs/zh_CN/api-guides/app_trace.rst b/docs/zh_CN/api-guides/app_trace.rst
@@ -115,9 +115,13 @@ ESP-IDF 中提供了应用层跟踪功能，用于分析应用程序的行为。
       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_JTAG, 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,7 +142,11 @@ ESP-IDF 中提供了应用层跟踪功能，用于分析应用程序的行为。
       size_t sz = 32;
 
       /* 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;
+      }
       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!");
@@ -150,7 +158,7 @@ ESP-IDF 中提供了应用层跟踪功能，用于分析应用程序的行为。
       } else {
           printf("No data");
       }
-      esp_err_t res = esp_apptrace_down_buffer_put(ESP_APPTRACE_DEST_JTAG, 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!");

Original file line number	Diff line number	Diff line change
`@@ -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 **************************`