From 8ad2be798060a5cd21b9040ab392fe8f8e648ff3 Mon Sep 17 00:00:00 2001 From: Krzysztof Date: Mon, 2 Mar 2026 15:28:36 +0800 Subject: [PATCH] docs(debugging): Add debug helpers API reference --- .../esp_system/include/esp_debug_helpers.h | 18 +++++++++--------- docs/doxygen/Doxyfile | 1 + .../api-reference/system/misc_system_api.rst | 13 +++++++++++++ .../api-reference/system/misc_system_api.rst | 13 +++++++++++++ 4 files changed, 36 insertions(+), 9 deletions(-) diff --git a/components/esp_system/include/esp_debug_helpers.h b/components/esp_system/include/esp_debug_helpers.h index cc9840f7bc..d74a37d1ae 100644 --- a/components/esp_system/include/esp_debug_helpers.h +++ b/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; /** diff --git a/docs/doxygen/Doxyfile b/docs/doxygen/Doxyfile index 3260e42625..5d65b097fc 100644 --- a/docs/doxygen/Doxyfile +++ b/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 \ diff --git a/docs/en/api-reference/system/misc_system_api.rst b/docs/en/api-reference/system/misc_system_api.rst index 1b0475966a..79a1946948 100644 --- a/docs/en/api-reference/system/misc_system_api.rst +++ b/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 diff --git a/docs/zh_CN/api-reference/system/misc_system_api.rst b/docs/zh_CN/api-reference/system/misc_system_api.rst index 90c6fbd71e..4b5f912897 100644 --- a/docs/zh_CN/api-reference/system/misc_system_api.rst +++ b/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