Merge branch 'bugfix/add_esp_debug_helpers_api' into 'master'

docs(debugging): Add debug helpers API reference

Closes DOC-13896

See merge request espressif/esp-idf!46187

components/esp_system/include/esp_debug_helpers.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -17,8 +17,8 @@ extern "C" {
 #include "esp_err.h"
 #include "esp_cpu.h"
 
-/*
- * @brief   Structure used for backtracing
+/**
+ * @brief Structure used for backtracing.
  *
  * This structure stores the backtrace information of a particular stack frame
  * (i.e. the PC and SP). This structure is used iteratively with the
@@ -26,14 +26,14 @@ extern "C" {
  * single stack. The next_pc represents the PC of the current frame's caller, thus
  * a next_pc of 0 indicates that the current frame is the last frame on the stack.
  *
- * @note    Call esp_backtrace_get_start() to obtain initialization values for
- *          this structure
+ * @note Call esp_backtrace_get_start() to obtain initialization values for
+ *       this structure.
  */
 typedef struct {
-    uint32_t pc;       /* PC of the current frame */
-    uint32_t sp;       /* SP of the current frame */
-    uint32_t next_pc;  /* PC of the current frame's caller */
-    const void *exc_frame;  /* Pointer to the full frame data structure, if applicable */
+    uint32_t pc;              /**< PC of the current frame */
+    uint32_t sp;              /**< SP of the current frame */
+    uint32_t next_pc;         /**< PC of the current frame's caller */
+    const void *exc_frame;    /**< Pointer to the full frame data structure, if applicable */
 } esp_backtrace_frame_t;
 
 /**

docs/doxygen/Doxyfile

@@ -236,6 +236,7 @@ INPUT = \
     $(PROJECT_PATH)/components/esp_ringbuf/include/freertos/ringbuf.h \
     $(PROJECT_PATH)/components/esp_rom/include/esp_rom_sys.h \
     $(PROJECT_PATH)/components/esp_security/include/esp_ds.h \
+    $(PROJECT_PATH)/components/esp_system/include/esp_debug_helpers.h \
     $(PROJECT_PATH)/components/esp_system/include/esp_expression_with_stack.h \
     $(PROJECT_PATH)/components/esp_system/include/esp_freertos_hooks.h \
     $(PROJECT_PATH)/components/esp_system/include/esp_ipc_isr.h \

docs/en/api-reference/system/misc_system_api.rst

@@ -213,6 +213,18 @@ To get the version at build time, additional version macros are provided. They c
       #endif
 
 
+Debug Helpers
+-------------
+
+The debug helper APIs in ``esp_debug_helpers.h`` provide utilities for run-time debugging and stack backtrace output.
+
+- :cpp:func:`esp_backtrace_print` prints the current stack backtrace.
+- :cpp:func:`esp_backtrace_print_all_tasks` prints backtraces for all tasks.
+- :cpp:func:`esp_backtrace_get_start` and :cpp:func:`esp_backtrace_get_next_frame` allow manual iteration over backtrace frames.
+
+These APIs are useful when diagnosing crashes, watchdog timeouts, or unexpected control flow.
+
+
 .. _app-version:
 
 App Version
@@ -237,4 +249,5 @@ API Reference
 .. include-build-file:: inc/esp_mac.inc
 .. include-build-file:: inc/esp_chip_info.inc
 .. include-build-file:: inc/esp_cpu.inc
+.. include-build-file:: inc/esp_debug_helpers.inc
 .. include-build-file:: inc/esp_app_desc.inc

docs/zh_CN/api-reference/system/misc_system_api.rst

@@ -213,6 +213,18 @@ SDK 版本
       #endif
 
 
+调试辅助功能
+-----------------
+
+``esp_debug_helpers.h`` 中的调试辅助 API 提供了运行时调试和堆栈回溯输出相关功能。
+
+- :cpp:func:`esp_backtrace_print` 用于打印当前堆栈回溯。
+- :cpp:func:`esp_backtrace_print_all_tasks` 用于打印所有任务的堆栈回溯。
+- :cpp:func:`esp_backtrace_get_start` 和 :cpp:func:`esp_backtrace_get_next_frame` 用于手动遍历回溯帧。
+
+这些 API 适用于诊断崩溃、看门狗超时或异常控制流等问题。
+
+
 .. _app-version:
 
 应用程序版本
@@ -237,4 +249,5 @@ API 参考
 .. include-build-file:: inc/esp_mac.inc
 .. include-build-file:: inc/esp_chip_info.inc
 .. include-build-file:: inc/esp_cpu.inc
+.. include-build-file:: inc/esp_debug_helpers.inc
 .. include-build-file:: inc/esp_app_desc.inc