Merge branch 'task/make_task_snapshot_public' into 'master'

sudeep-mohanty · sudeep-mohanty · commit df1e1c2b73ab · 2025-09-17T10:48:43.000+02:00
refactor(freertos): Make task snapshot debug API public

Closes IDF-10038 and IDF-8143

See merge request espressif/esp-idf!41871
diff --git a/components/esp_gdbstub/private_include/esp_gdbstub_common.h b/components/esp_gdbstub/private_include/esp_gdbstub_common.h
@@ -16,7 +16,7 @@
 #ifdef CONFIG_ESP_GDBSTUB_SUPPORT_TASKS
 #include "freertos/FreeRTOS.h"
 #include "freertos/task.h"
-#include "esp_private/freertos_debug.h"
+#include "freertos/freertos_debug.h"
 #endif // CONFIG_ESP_GDBSTUB_SUPPORT_TASKS
 
 /* Internal error codes used by the routines that parse the incoming gdb packet */
diff --git a/components/esp_gdbstub/src/port/riscv/gdbstub_riscv.c b/components/esp_gdbstub/src/port/riscv/gdbstub_riscv.c
@@ -13,7 +13,7 @@
 #include "rv_decode.h"
 #include "sdkconfig.h"
 #include "esp_private/crosscore_int.h"
-#include "esp_private/freertos_debug.h"
+#include "freertos/freertos_debug.h"
 #include "freertos/portmacro.h"
 #include "freertos/FreeRTOS.h"
 #include "freertos/FreeRTOSConfig.h"
diff --git a/components/esp_system/port/arch/riscv/debug_helpers.c b/components/esp_system/port/arch/riscv/debug_helpers.c
@@ -9,7 +9,7 @@
 #include "sdkconfig.h"
 #include "freertos/FreeRTOS.h"
 #include "freertos/task.h"
-#include "esp_private/freertos_debug.h"
+#include "freertos/freertos_debug.h"
 #include "esp_err.h"
 #include "esp_private/esp_system_attr.h"
 #include "esp_private/esp_cpu_internal.h"
diff --git a/components/esp_system/port/arch/xtensa/debug_helpers.c b/components/esp_system/port/arch/xtensa/debug_helpers.c
@@ -16,7 +16,7 @@
 #include "esp_debug_helpers.h"
 #include "esp_cpu_utils.h"
 #include "esp_private/panic_internal.h"
-#include "esp_private/freertos_debug.h"
+#include "freertos/freertos_debug.h"
 #include "esp_rom_sys.h"
 #include "xtensa_context.h"
 #include "freertos/FreeRTOS.h"
diff --git a/components/esp_system/task_wdt/task_wdt.c b/components/esp_system/task_wdt/task_wdt.c
@@ -12,7 +12,7 @@
 #include "sdkconfig.h"
 #include "freertos/FreeRTOS.h"
 #include "freertos/task.h"
-#include "esp_private/freertos_debug.h"
+#include "freertos/freertos_debug.h"
 #include "esp_err.h"
 #include "esp_attr.h"
 #include "esp_check.h"
diff --git a/components/espcoredump/include_core_dump/esp_core_dump_common.h b/components/espcoredump/include_core_dump/esp_core_dump_common.h
@@ -7,7 +7,7 @@
 #define ESP_CORE_DUMP_COMMON_H_
 
 #include "freertos/FreeRTOS.h"
-#include "esp_private/freertos_debug.h"
+#include "freertos/freertos_debug.h"
 #include "esp_app_format.h"
 #include "esp_core_dump_types.h"
 
diff --git a/components/espcoredump/src/core_dump_common.c b/components/espcoredump/src/core_dump_common.c
@@ -9,7 +9,7 @@
 #include <stdbool.h>
 #include "soc/soc_memory_layout.h"
 #include "freertos/FreeRTOS.h"
-#include "esp_private/freertos_debug.h"
+#include "freertos/freertos_debug.h"
 #include "esp_rom_sys.h"
 #include "esp_core_dump_port.h"
 #include "esp_core_dump_common.h"
diff --git a/components/freertos/Kconfig b/components/freertos/Kconfig
@@ -639,21 +639,6 @@ menu "FreeRTOS"
         help
             Hidden option, gets selected by CONFIG_ESP_DEBUG_OCDAWARE
 
-    config FREERTOS_ENABLE_TASK_SNAPSHOT
-        # Invisible option that is always enabled. Task Snapshot APIs are now private thus are always enabled. This
-        # option is kept here in case any user code conditionally depends on this option.
-        # Todo: Remove in v6.0 (IDF-8143)
-        bool
-        default y
-
-    config FREERTOS_PLACE_SNAPSHOT_FUNS_INTO_FLASH
-        # Invisible option that is always enabled. Task Snapshot APIs are now private API thus are always placed into
-        # flash by default. This option is kept here in case any user code conditionally depends on this option.
-        # Todo: Remove in v6.0 (IDF-8143)
-        bool
-        default y
-        depends on !ESP_PANIC_HANDLER_IRAM
-
     config FREERTOS_NUMBER_OF_CORES
         # Invisible option to configure the number of cores on which FreeRTOS runs
         # Todo: Unhide this option and deprecate CONFIG_FREERTOS_UNICORE (IDF-9156)
diff --git a/components/freertos/esp_additions/freertos_tasks_c_additions.h b/components/freertos/esp_additions/freertos_tasks_c_additions.h
@@ -9,9 +9,7 @@
 #include "esp_heap_caps.h"
 #include "esp_compiler.h"
 #include "freertos/idf_additions.h"
-#if CONFIG_FREERTOS_ENABLE_TASK_SNAPSHOT
-    #include "esp_private/freertos_debug.h"
-#endif /* CONFIG_FREERTOS_ENABLE_TASK_SNAPSHOT */
+#include "freertos/freertos_debug.h"
 #include "esp_private/freertos_idf_additions_priv.h"
 
 /**
diff --git a/components/freertos/esp_additions/include/freertos/freertos_debug.h b/components/freertos/esp_additions/include/freertos/freertos_debug.h
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -11,7 +11,9 @@
 #include "freertos/task.h"
 
 /*
- * This header contains private API used by various ESP-IDF debugging features (e.g., esp_gdbstub).
+ * This header contains public API for FreeRTOS debugging features including task snapshots.
+ * These APIs are used by ESP-IDF debugging features (e.g., esp_gdbstub, core dump) and
+ * external frameworks (e.g., ESP Insights) for debugging and monitoring purposes.
  */
 
 /* *INDENT-OFF* */
@@ -71,7 +73,9 @@ int xTaskGetNext( TaskIterator_t * xIterator );
  * - This function is used by the panic handler to get the snapshot of a particular task.
  *
  * @note This function should only be called when FreeRTOS is no longer running (e.g., during a panic) as this function
- *       does not acquire any locks.
+ *       does not acquire any locks. For safe usage with scheduler running, use vTaskSuspendAll() before calling
+ *       this function and xTaskResumeAll() after.
+ *
  * @param[in] pxTask Task's handle
  * @param[out] pxTaskSnapshot Snapshot of the task
  * @return pdTRUE if operation was successful else pdFALSE
@@ -85,11 +89,13 @@ BaseType_t vTaskGetSnapshot( TaskHandle_t pxTask,
  * - This function is used by the panic handler to get a snapshot of all tasks in the system
  *
  * @note This function should only be called when FreeRTOS is no longer running (e.g., during a panic) as this function
- *        does not acquire any locks.
+ *        does not acquire any locks. For safe usage with scheduler running, use vTaskSuspendAll() before calling
+ *        this function and xTaskResumeAll() after.
+ *
  * @param[out] pxTaskSnapshotArray Array of TaskSnapshot_t structures filled by this function
  * @param[in] uxArrayLength Length of the provided array
  * @param[out] pxTCBSize Size of the a task's TCB structure (can be set to NULL)
- * @return UBaseType_t
+ * @return UBaseType_t Number of task snapshots filled in the array
  */
 UBaseType_t uxTaskGetSnapshotAll( TaskSnapshot_t * const pxTaskSnapshotArray,
                                   const UBaseType_t uxArrayLength,
diff --git a/components/freertos/esp_additions/include/freertos/task_snapshot.h b/components/freertos/esp_additions/include/freertos/task_snapshot.h
@@ -1,9 +1,9 @@
 /*
- * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
 #pragma once
 
-#warning freertos/task_snapshot.h header is no longer used, and will be removed in future versions.
-#include "esp_private/freertos_debug.h"
+#warning "freertos/task_snapshot.h is deprecated. Use freertos/freertos_debug.h instead. This compatibility header will be removed in ESP-IDF v7.0."
+#include "freertos/freertos_debug.h"
diff --git a/components/freertos/linker_common.lf b/components/freertos/linker_common.lf
@@ -18,15 +18,19 @@ entries:
     # Placement Rules (Task Snapshot):
     #   - Default: Place all functions in flash.
     #   - CONFIG_FREERTOS_IN_IRAM: Place all functions in internal RAM for performance optimization.
-    #   - vTaskGetSnapshot is omitted on purpose as it is used to by the Task Watchdog (TWDT) interrupt handler, we want
-    #     to always keep it in IRAM unless CONFIG_FREERTOS_PLACE_ISR_FUNCTIONS_INTO_FLASH is enabled in which case
-    #     we can place it in flash.
+    #   - ESP_PANIC_HANDLER_IRAM: Place task snapshot functions in IRAM for panic handling.
+    #   - vTaskGetSnapshot is used by the Task Watchdog (TWDT) interrupt handler, so it's kept in IRAM
+    #     unless CONFIG_FREERTOS_PLACE_ISR_FUNCTIONS_INTO_FLASH is enabled.
     #
     # ------------------------------------------------------------------------------------------------------------------
     if FREERTOS_SMP = n && FREERTOS_UNICORE = n:
         tasks:xTaskIncrementTickOtherCores (noflash_text)
     if FREERTOS_PLACE_ISR_FUNCTIONS_INTO_FLASH = n:
         tasks:vTaskGetSnapshot (noflash_text)
+    if ESP_PANIC_HANDLER_IRAM = y:
+        tasks:vTaskGetSnapshot (noflash_text)
+        tasks:uxTaskGetSnapshotAll (noflash_text)
+        tasks:xTaskGetNext (noflash_text)
 
     # ------------------------------------------------------------------------------------------------------------------
     # idf_additions.c
diff --git a/components/freertos/test_apps/freertos/port/test_tasks_snapshot.c b/components/freertos/test_apps/freertos/port/test_tasks_snapshot.c
@@ -9,7 +9,7 @@
 #include <stdbool.h>
 #include "freertos/FreeRTOS.h"
 #include "freertos/task.h"
-#include "esp_private/freertos_debug.h"
+#include "freertos/freertos_debug.h"
 #include "esp_cpu.h"
 #include "esp_rom_sys.h"
 #include "unity.h"
@@ -126,7 +126,7 @@ static void teardown(TaskHandle_t *task_list, int num_tasks, UBaseType_t old_pri
     // Signal to the other core that it can exit the loop
     stop_flag = true;
 #endif // !CONFIG_FREERTOS_UNICORE
-    // Reenable interrupts on the current core.
+    // Re-enable interrupts on the current core.
     taskENABLE_INTERRUPTS();
 
     for (int i = 0; i < num_tasks; i++) {
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
@@ -134,13 +134,25 @@ The following compatibility functions have been removed in ESP-IDF v6.0. These f
 
 The function :cpp:func:`pxTaskGetStackStart` has been deprecated. Use :cpp:func:`xTaskGetStackStart` instead for improved type safety.
 
+**API Added**
+
+Task snapshot APIs have been made public due to their usage by external frameworks like ESP Insights. The APIs are now available through ``freertos/freertos_debug.h`` instead of the deprecated ``freertos/task_snapshot.h``.
+For safe usage with scheduler running, use ``vTaskSuspendAll()`` before calling snapshot functions and ``xTaskResumeAll()`` after.
+
 **Memory Placement**
 
-To reduce IRAM usage, the default placement for most FreeRTOS functions has been changed from IRAM to Flash. Consequently, the ``CONFIG_FREERTOS_PLACE_FUNCTIONS_INTO_FLASH`` option has been removed. This change saves a significant amount of IRAM but may have a slight performance impact. For performance-critical applications, the previous behavior can be restored by enabling the new :ref:`CONFIG_FREERTOS_IN_IRAM` option.
+- To reduce IRAM usage, the default placement for most FreeRTOS functions has been changed from IRAM to Flash. Consequently, the ``CONFIG_FREERTOS_PLACE_FUNCTIONS_INTO_FLASH`` option has been removed. This change saves a significant amount of IRAM but may have a slight performance impact. For performance-critical applications, the previous behavior can be restored by enabling the new :ref:`CONFIG_FREERTOS_IN_IRAM` option.
+- When deciding whether to enable ``CONFIG_FREERTOS_IN_IRAM``, consider conducting performance testing to measure the actual impact on your specific use case. Performance differences between Flash and IRAM configurations can vary depending on flash cache efficiency, API usage patterns, and system load.
+- A baseline performance test is provided in ``components/freertos/test_apps/freertos/performance/test_freertos_api_performance.c`` that measures the execution time of commonly used FreeRTOS APIs. This test can help you evaluate the performance impact of memory placement for your target hardware and application requirements.
+- Task snapshot functions are automatically placed in IRAM when ``CONFIG_ESP_PANIC_HANDLER_IRAM`` is enabled, ensuring they remain accessible during panic handling
+- ``vTaskGetSnapshot`` is kept in IRAM unless ``CONFIG_FREERTOS_PLACE_ISR_FUNCTIONS_INTO_FLASH`` is enabled, as it's used by the Task Watchdog interrupt handler.
+
+**Removed Configuration Options:**
 
-When deciding whether to enable ``CONFIG_FREERTOS_IN_IRAM``, consider conducting performance testing to measure the actual impact on your specific use case. Performance differences between Flash and IRAM configurations can vary depending on flash cache efficiency, API usage patterns, and system load.
+The following hidden (and always true) configuration options have been removed:
 
-A baseline performance test is provided in ``components/freertos/test_apps/freertos/performance/test_freertos_api_performance.c`` that measures the execution time of commonly used FreeRTOS APIs. This test can help you evaluate the performance impact of memory placement for your target hardware and application requirements.
+- ``CONFIG_FREERTOS_ENABLE_TASK_SNAPSHOT``
+- ``CONFIG_FREERTOS_PLACE_SNAPSHOT_FUNS_INTO_FLASH``
 
 Ring Buffer
 -----------
diff --git a/docs/zh_CN/migration-guides/release-6.x/6.0/system.rst b/docs/zh_CN/migration-guides/release-6.x/6.0/system.rst
@@ -134,13 +134,25 @@ FreeRTOS
 
 函数 :cpp:func:`pxTaskGetStackStart` 已弃用。请使用 :cpp:func:`xTaskGetStackStart` 替代以提高类型安全性。
 
+**新增 API**
+
+由于 ESP Insights 等外部框架的使用需求，任务快照 API 已重新设为公开。这些 API 现在通过 ``freertos/freertos_debug.h`` 提供，而不是已弃用的 ``freertos/task_snapshot.h``。
+为了在调度器运行时安全使用，请在调用快照函数前使用 ``vTaskSuspendAll()``，调用后使用 ``xTaskResumeAll()``。
+
 **内存布局**
 
-为了减少 IRAM 的使用，大多数 FreeRTOS 函数的默认位置已从 IRAM 更改为 flash。因此，``CONFIG_FREERTOS_PLACE_FUNCTIONS_INTO_FLASH`` 选项已被移除。这项变更可显著节省 IRAM 空间，但可能会对性能造成轻微影响。如果应用对性能有严苛要求，可通过启用新增的 :ref:`CONFIG_FREERTOS_IN_IRAM` 选项来恢复原先配置。
+- 为了减少 IRAM 的使用，大多数 FreeRTOS 函数的默认位置已从 IRAM 更改为 flash。因此，``CONFIG_FREERTOS_PLACE_FUNCTIONS_INTO_FLASH`` 选项已被移除。这项变更可显著节省 IRAM 空间，但可能会对性能造成轻微影响。如果应用对性能有严苛要求，可通过启用新增的 :ref:`CONFIG_FREERTOS_IN_IRAM` 选项来恢复原先配置。
+- 在决定是否启用 ``CONFIG_FREERTOS_IN_IRAM`` 时，建议进行性能测试以评估对具体应用场景的实际影响。flash 和 IRAM 配置的性能差异会受 flash 缓存效率、API 调用模式和系统负载等因素影响。
+- ``components/freertos/test_apps/freertos/performance/test_freertos_api_performance.c`` 中提供了基准性能测试，可测量常用 FreeRTOS API 的执行时间。该测试有助于根据目标硬件和应用需求评估内存布局调整带来的性能影响。
+- 当启用 ``CONFIG_ESP_PANIC_HANDLER_IRAM`` 时，任务快照函数会自动放置在 IRAM 中，确保在恐慌处理期间仍可访问
+- ``vTaskGetSnapshot`` 会保持在 IRAM 中，除非启用了 ``CONFIG_FREERTOS_PLACE_ISR_FUNCTIONS_INTO_FLASH``，因为它被任务看门狗中断处理程序使用。
+
+**已移除的配置选项：**
 
-在决定是否启用 ``CONFIG_FREERTOS_IN_IRAM`` 时，建议进行性能测试以评估对具体应用场景的实际影响。flash 和 IRAM 配置的性能差异会受 flash 缓存效率、API 调用模式和系统负载等因素影响。
+以下隐藏（且始终为真）的配置选项已被移除：
 
-``components/freertos/test_apps/freertos/performance/test_freertos_api_performance.c`` 中提供了基准性能测试，可测量常用 FreeRTOS API 的执行时间。该测试有助于根据目标硬件和应用需求评估内存布局调整带来的性能影响。
+- ``CONFIG_FREERTOS_ENABLE_TASK_SNAPSHOT``
+- ``CONFIG_FREERTOS_PLACE_SNAPSHOT_FUNS_INTO_FLASH``
 
 环形缓冲区
 ----------
diff --git a/tools/idf_py_actions/hints.yml b/tools/idf_py_actions/hints.yml
@@ -241,6 +241,10 @@
     hint: "{} was removed. Please use esp_jpeg component from IDF component manager instead.\nPlease look out for component in 'https://components.espressif.com' and add using 'idf.py add-dependency' command.\nRefer to the migration guide for more details."
     match_to_output: True
 
+-
+    re: "fatal error: esp_private/freertos_debug.h: No such file or directory"
+    hint: "esp_private/freertos_debug.h has been moved to freertos/freertos_debug.h.\nThe task snapshot APIs are now public. Update your include to use the new public header."
+
 -
     re: "(fatal error: tcpip_adapter.h: No such file or directory|error: implicit declaration of function 'tcpip_adapter_init')"
     hint: "TCP/IP adapter compatibility layer has been removed. Please migrate to ESP-NETIF.\nRefer to the Networking migration guide, section TCP/IP adapter, for more details."
