Merge branch 'change/freertos_make_task_snapshot_private' into 'master'

refactor(freertos/task_snapshot): Make task snapshot private

Closes IDF-8182

See merge request espressif/esp-idf!26115

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 "freertos/task_snapshot.h"
+#include "esp_private/freertos_debug.h"
 #endif // CONFIG_ESP_GDBSTUB_SUPPORT_TASKS
 
 /* Internal error codes used by the routines that parse the incoming gdb packet */

components/esp_gdbstub/src/port/riscv/gdbstub_riscv.c

@@ -11,6 +11,7 @@
 #include "rv_decode.h"
 #include "sdkconfig.h"
 #include "esp_private/crosscore_int.h"
+#include "esp_private/freertos_debug.h"
 
 extern volatile esp_gdbstub_frame_t *temp_regs_frame;
 
@@ -85,15 +86,7 @@ void esp_gdbstub_int(__attribute__((unused)) void *frame)
    /* Pointer to saved frame is in pxCurrentTCB
     * See rtos_int_enter function
     */
-    /* Todo: Provide IDF interface for getting pxCurrentTCB (IDF-8182) */
-    int core_id = esp_cpu_get_core_id();
-#if CONFIG_FREERTOS_USE_KERNEL_10_5_1
-    extern void **pxCurrentTCBs;
-    dummy_tcb_t *tcb = (dummy_tcb_t *) &pxCurrentTCBs[core_id];
-#else
-    extern void **pxCurrentTCB;
-    dummy_tcb_t *tcb = (dummy_tcb_t *) &pxCurrentTCB[core_id];
-#endif /* CONFIG_FREERTOS_USE_KERNEL_10_5_1 */
+    dummy_tcb_t *tcb = (dummy_tcb_t *)pvTaskGetCurrentTCBForCore(esp_cpu_get_core_id());
     gdbstub_handle_uart_int((esp_gdbstub_frame_t *)tcb->top_of_stack);
 }
 

components/esp_system/task_wdt/task_wdt.c

@@ -11,7 +11,7 @@
 #include "sdkconfig.h"
 #include "freertos/FreeRTOS.h"
 #include "freertos/task.h"
-#include "freertos/task_snapshot.h"
+#include "esp_private/freertos_debug.h"
 #include "esp_err.h"
 #include "esp_attr.h"
 #include "esp_check.h"

components/espcoredump/src/core_dump_common.c

@@ -8,7 +8,7 @@
 #include "sdkconfig.h"
 #include "soc/soc_memory_layout.h"
 #include "freertos/FreeRTOS.h"
-#include "freertos/task_snapshot.h"
+#include "esp_private/freertos_debug.h"
 #include "esp_rom_sys.h"
 #include "esp_core_dump_port.h"
 #include "esp_core_dump_common.h"

components/freertos/Kconfig

@@ -490,14 +490,6 @@ menu "FreeRTOS"
                 When enabled the selected Non-ISR FreeRTOS functions will be placed into Flash memory instead of IRAM.
                 This saves up to 8KB of IRAM depending on which functions are used.
 
-        config FREERTOS_PLACE_SNAPSHOT_FUNS_INTO_FLASH
-            bool "Place task snapshot functions into flash"
-            default n
-            depends on !ESP_PANIC_HANDLER_IRAM
-            help
-                When enabled, the functions related to snapshots, such as vTaskGetSnapshot or uxTaskGetSnapshotAll,
-                will be placed in flash. Note that if enabled, these functions cannot be called when cache is disabled.
-
         config FREERTOS_CHECK_PORT_CRITICAL_COMPLIANCE
             # Todo: Check if we still need this (IDF-4986)
             bool "Tests compliance with Vanilla FreeRTOS port*_CRITICAL calls"
@@ -536,10 +528,18 @@ menu "FreeRTOS"
             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 always enabled. This
+        # 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
+
 endmenu # FreeRTOS

components/freertos/esp_additions/freertos_tasks_c_additions.h

@@ -8,7 +8,7 @@
 #include "esp_assert.h"
 #include "freertos/idf_additions.h"
 #if CONFIG_FREERTOS_ENABLE_TASK_SNAPSHOT
-    #include "freertos/task_snapshot.h"
+    #include "esp_private/freertos_debug.h"
 #endif /* CONFIG_FREERTOS_ENABLE_TASK_SNAPSHOT */
 #include "esp_private/freertos_idf_additions_priv.h"
 
@@ -1181,6 +1181,26 @@ UBaseType_t uxTaskGetSnapshotAll( TaskSnapshot_t * const pxTaskSnapshotArray,
 }
 /*----------------------------------------------------------*/
 
+/* ----------------------------------------------------- Misc ----------------------------------------------------- */
+
+void * pvTaskGetCurrentTCBForCore( BaseType_t xCoreID )
+{
+    void * pvRet;
+
+    configASSERT( ( xCoreID >= 0 ) && ( xCoreID < configNUM_CORES ) );
+    #if CONFIG_FREERTOS_USE_KERNEL_10_5_1
+        pvRet = ( void * ) pxCurrentTCBs[ xCoreID ];
+    #else /* CONFIG_FREERTOS_USE_KERNEL_10_5_1 */
+        #if CONFIG_FREERTOS_SMP
+            /* SMP FreeRTOS defines pxCurrentTCB as a macro function call */
+            pvRet = pxCurrentTCB;
+        #else /* CONFIG_FREERTOS_SMP */
+            pvRet = ( void * ) pxCurrentTCB[ xCoreID ];
+        #endif /* CONFIG_FREERTOS_SMP */
+    #endif /* CONFIG_FREERTOS_USE_KERNEL_10_5_1 */
+    return pvRet;
+}
+
 /* ----------------------------------------------------- OpenOCD ---------------------------------------------------- */
 
 #if CONFIG_FREERTOS_DEBUG_OCDAWARE

components/freertos/esp_additions/include/esp_private/freertos_debug.h

@@ -0,0 +1,99 @@
+/*
+ * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include "sdkconfig.h"
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+
+/*
+ * This header contains private API used by various ESP-IDF debugging features (e.g., esp_gdbstub).
+ */
+
+/* *INDENT-OFF* */
+#ifdef __cplusplus
+    extern "C" {
+#endif
+/* *INDENT-ON* */
+
+/* -------------------------------------------------- Task Snapshot ------------------------------------------------- */
+
+/**
+ * @brief Task Snapshot structure
+ *
+ * - Used with the uxTaskGetSnapshotAll() function to save memory snapshot of each task in the system.
+ * - We need this structure because TCB_t is defined (hidden) in tasks.c.
+ */
+typedef struct xTASK_SNAPSHOT
+{
+    void * pxTCB;               /*!< Address of the task control block. */
+    StackType_t * pxTopOfStack; /*!< Points to the location of the last item placed on the tasks stack. */
+    StackType_t * pxEndOfStack; /*!< Points to the end of the stack. pxTopOfStack < pxEndOfStack, stack grows hi2lo
+                                 *  pxTopOfStack > pxEndOfStack, stack grows lo2hi*/
+} TaskSnapshot_t;
+
+/**
+ * @brief Iterate over all tasks in the system
+ *
+ * - This function can be used to iterate over every task in the system
+ * - The first call to this function must set pxTask to NULL
+ * - When all functions have been iterated, this function will return NULL.
+ *
+ * @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.
+ * @param pxTask Handle of the previous task (or NULL on the first call of this function)
+ * @return TaskHandle_t Handle of the next task (or NULL when all tasks have been iterated over)
+ */
+TaskHandle_t pxTaskGetNext( TaskHandle_t pxTask );
+
+/**
+ * @brief Fill a TaskSnapshot_t structure for specified task.
+ *
+ * - 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.
+ * @param[in] pxTask Task's handle
+ * @param[out] pxTaskSnapshot Snapshot of the task
+ * @return pdTRUE if operation was successful else pdFALSE
+ */
+BaseType_t vTaskGetSnapshot( TaskHandle_t pxTask,
+                             TaskSnapshot_t * pxTaskSnapshot );
+
+/**
+ * @brief Fill an array of TaskSnapshot_t structures for every task in the system
+ *
+ * - 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.
+ * @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
+ * @return UBaseType_t
+ */
+UBaseType_t uxTaskGetSnapshotAll( TaskSnapshot_t * const pxTaskSnapshotArray,
+                                  const UBaseType_t uxArrayLength,
+                                  UBaseType_t * const pxTCBSize );
+
+/* ----------------------------------------------------- Misc ----------------------------------------------------- */
+
+/**
+ * @brief Get a void pointer to the current TCB of a particular core
+ *
+ * @note This function provides no guarantee that the return TCB will still be the current task (or that the task still
+ * exists) when it returns. It is the caller's responsibility to ensure that the task does not get scheduled or deleted.
+ * @param xCoreID The core to query
+ * @return Void pointer to current TCB
+ */
+void * pvTaskGetCurrentTCBForCore( BaseType_t xCoreID );
+
+/* *INDENT-OFF* */
+#ifdef __cplusplus
+    }
+#endif
+/* *INDENT-ON* */

components/freertos/esp_additions/include/freertos/task_snapshot.h

@@ -3,79 +3,7 @@
  *
  * SPDX-License-Identifier: Apache-2.0
  */
-
 #pragma once
 
-#include "sdkconfig.h"
-#include "freertos/FreeRTOS.h"
-#include "freertos/task.h"
-
-/* *INDENT-OFF* */
-#ifdef __cplusplus
-    extern "C" {
-#endif
-/* *INDENT-ON* */
-
-/**
- * @brief Task Snapshot structure
- *
- * - Used with the uxTaskGetSnapshotAll() function to save memory snapshot of each task in the system.
- * - We need this structure because TCB_t is defined (hidden) in tasks.c.
- */
-typedef struct xTASK_SNAPSHOT
-{
-    void * pxTCB;               /*!< Address of the task control block. */
-    StackType_t * pxTopOfStack; /*!< Points to the location of the last item placed on the tasks stack. */
-    StackType_t * pxEndOfStack; /*!< Points to the end of the stack. pxTopOfStack < pxEndOfStack, stack grows hi2lo
-                                 *  pxTopOfStack > pxEndOfStack, stack grows lo2hi*/
-} TaskSnapshot_t;
-
-/**
- * @brief Iterate over all tasks in the system
- *
- * - This function can be used to iterate over every task in the system
- * - The first call to this function must set pxTask to NULL
- * - When all functions have been iterated, this function will return NULL.
- *
- * @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.
- * @param pxTask Handle of the previous task (or NULL on the first call of this function)
- * @return TaskHandle_t Handle of the next task (or NULL when all tasks have been iterated over)
- */
-TaskHandle_t pxTaskGetNext( TaskHandle_t pxTask );
-
-/**
- * @brief Fill a TaskSnapshot_t structure for specified task.
- *
- * - 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.
- * @param[in] pxTask Task's handle
- * @param[out] pxTaskSnapshot Snapshot of the task
- * @return pdTRUE if operation was successful else pdFALSE
- */
-BaseType_t vTaskGetSnapshot( TaskHandle_t pxTask,
-                             TaskSnapshot_t * pxTaskSnapshot );
-
-/**
- * @brief Fill an array of TaskSnapshot_t structures for every task in the system
- *
- * - 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.
- * @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
- * @return UBaseType_t
- */
-UBaseType_t uxTaskGetSnapshotAll( TaskSnapshot_t * const pxTaskSnapshotArray,
-                                  const UBaseType_t uxArrayLength,
-                                  UBaseType_t * const pxTCBSize );
-
-/* *INDENT-OFF* */
-#ifdef __cplusplus
-    }
-#endif
-/* *INDENT-ON* */
+#warning freertos/task_snapshot.h header is no longer used, and will be removed in future versions.
+#include "esp_private/freertos_debug.h"

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 "freertos/task_snapshot.h"
+#include "esp_private/freertos_debug.h"
 #include "esp_cpu.h"
 #include "esp_rom_sys.h"
 #include "unity.h"

docs/doxygen/Doxyfile

@@ -214,7 +214,6 @@ INPUT = \
     $(PROJECT_PATH)/components/fatfs/diskio/diskio_wl.h \
     $(PROJECT_PATH)/components/fatfs/vfs/esp_vfs_fat.h \
     $(PROJECT_PATH)/components/freertos/esp_additions/include/freertos/idf_additions.h \
-    $(PROJECT_PATH)/components/freertos/esp_additions/include/freertos/task_snapshot.h \
     $(PROJECT_PATH)/components/freertos/FreeRTOS-Kernel/include/freertos/event_groups.h \
     $(PROJECT_PATH)/components/freertos/FreeRTOS-Kernel/include/freertos/message_buffer.h \
     $(PROJECT_PATH)/components/freertos/FreeRTOS-Kernel/include/freertos/queue.h \

docs/en/api-guides/performance/ram-usage.rst

@@ -148,7 +148,6 @@ The following options will reduce IRAM usage of some ESP-IDF features:
 .. list::
 
     - Enable :ref:`CONFIG_FREERTOS_PLACE_FUNCTIONS_INTO_FLASH`. Provided these functions are not incorrectly used from ISRs, this option is safe to enable in all configurations.
-    - Enable :ref:`CONFIG_FREERTOS_PLACE_SNAPSHOT_FUNS_INTO_FLASH`. Enabling this option places snapshot-related functions, such as ``vTaskGetSnapshot`` or ``uxTaskGetSnapshotAll``, in flash.
     - Enable :ref:`CONFIG_RINGBUF_PLACE_FUNCTIONS_INTO_FLASH`. Provided these functions are not incorrectly used from ISRs, this option is safe to enable in all configurations.
     - Enable :ref:`CONFIG_RINGBUF_PLACE_ISR_FUNCTIONS_INTO_FLASH`. This option is not safe to use if the ISR ringbuf functions are used from an IRAM interrupt context, e.g., if :ref:`CONFIG_UART_ISR_IN_IRAM` is enabled. For the ESP-IDF drivers where this is the case, you can get an error at run-time when installing the driver in question.
     :SOC_WIFI_SUPPORTED: - Disabling Wi-Fi options :ref:`CONFIG_ESP_WIFI_IRAM_OPT` and/or :ref:`CONFIG_ESP_WIFI_RX_IRAM_OPT` options frees available IRAM at the cost of Wi-Fi performance.

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

@@ -16,7 +16,6 @@ ESP-IDF adds various new features to supplement the capabilities of FreeRTOS as
 - **Ring buffers**: Ring buffers provide a FIFO buffer that can accept entries of arbitrary lengths.
 - **ESP-IDF Tick and Idle Hooks**: ESP-IDF provides multiple custom tick interrupt hooks and idle task hooks that are more numerous and more flexible when compared to FreeRTOS tick and idle hooks.
 - **Thread Local Storage Pointer (TLSP) Deletion Callbacks**: TLSP Deletion callbacks are run automatically when a task is deleted, thus allowing users to clean up their TLSPs automatically.
-- **Task Snapshots**: These functions are used by post-mortem debugging features (e.g., core dump) to get a snapshot of each FreeRTOS task.
 - **IDF Additional API**: ESP-IDF specific functions added to augment the features of FreeRTOS.
 - **Component Specific Properties**: Currently added only one component specific property ``ORIG_INCLUDE_PATH``.
 
@@ -436,20 +435,6 @@ When implementing TLSP callbacks, users should note the following:
 - The callback **must never attempt to block or yield** and critical sections should be kept as short as possible
 - The callback is called shortly before a deleted task's memory is freed. Thus, the callback can either be called from :cpp:func:`vTaskDelete` itself, or from the idle task.
 
-.. -------------------------------------------------- Task Snapshot ----------------------------------------------------
-
-Task Snapshot
--------------
-
-The Task Snapshot functions provide port-mortem debugging features (e.g., core dump) via a simple API to get a snapshot of all current tasks in the system. Each task snapshot includes information such as:
-
-- A pointer to the task's Task Control Block (TCB) structure
-- The top of the task's stack (i.e., current stack pointer)
-
-.. warning::
-
-    Task Snapshot must only be called when FreeRTOS is no longer running, such as after the system has crashed.
-
 .. --------------------------------------------- ESP-IDF Additional API ------------------------------------------------
 
 .. _freertos-idf-additional-api:
@@ -484,11 +469,6 @@ Hooks API
 
 .. include-build-file:: inc/esp_freertos_hooks.inc
 
-Task Snapshot API
-^^^^^^^^^^^^^^^^^
-
-.. include-build-file:: inc/task_snapshot.inc
-
 Additional API
 ^^^^^^^^^^^^^^
 

docs/en/migration-guides/release-5.x/5.2/index.rst

@@ -8,4 +8,5 @@ Migration from 5.1 to 5.2
 
     peripherals
     protocols
+    system
     wifi

docs/en/migration-guides/release-5.x/5.2/system.rst

@@ -0,0 +1,14 @@
+System
+======
+
+:link_to_translation:`zh_CN:[中文]`
+
+FreeRTOS
+--------
+
+Task Snapshot
+^^^^^^^^^^^^^
+
+The Task Snapshot API has been made private due to a lack of a practical way for the API to be used from user code (the scheduler must be halted before the API can be called).
+
+As a result, the ``#include "freertos/task_snapshot.h"`` include path has been deprecated.

docs/zh_CN/api-guides/performance/ram-usage.rst

@@ -148,7 +148,6 @@ IRAM 优化
 .. list::
 
     - 启用 :ref:`CONFIG_FREERTOS_PLACE_FUNCTIONS_INTO_FLASH`。只要没有从 ISR 中错误地调用这些函数，就可以在所有配置中安全启用此选项。
-    - 启用 :ref:`CONFIG_FREERTOS_PLACE_SNAPSHOT_FUNS_INTO_FLASH`。启用此选项，将在 flash 中放置与快照相关的函数，如 ``vTaskGetSnapshot`` 或 ``uxTaskGetSnapshotAll``。
     - 启用 :ref:`CONFIG_RINGBUF_PLACE_FUNCTIONS_INTO_FLASH`。只要没有从 ISR 中错误地调用这些函数，就可以在所有配置中安全启用此选项。
     - 启用 :ref:`CONFIG_RINGBUF_PLACE_ISR_FUNCTIONS_INTO_FLASH`。如果从 IRAM 中的中断上下文中使用 ISR ringbuf 函数，例如启用了 :ref:`CONFIG_UART_ISR_IN_IRAM`，则无法安全使用此选项。在此情况下，安装 ESP-IDF 相关驱动程序时，将在运行时报错。
     :SOC_WIFI_SUPPORTED: - 禁用 Wi-Fi 选项 :ref:`CONFIG_ESP_WIFI_IRAM_OPT` 和/或 :ref:`CONFIG_ESP_WIFI_RX_IRAM_OPT` 会释放可用 IRAM，但会牺牲部分 Wi-Fi 性能。

docs/zh_CN/migration-guides/release-5.x/5.2/index.rst

@@ -8,4 +8,5 @@
 
     peripherals
     protocols
+    system
     wifi

docs/zh_CN/migration-guides/release-5.x/5.2/system.rst

@@ -0,0 +1 @@
+.. include:: ../../../../en/migration-guides/release-5.x/5.2/system.rst

tools/ci/check_ldgen_mapping_exceptions.txt

@@ -2,3 +2,4 @@ libc
 sha256_coredump
 gcc
 clang_rt_builtins
+freertos_common

tools/idf_py_actions/hints.yml

@@ -137,14 +137,6 @@
     re: "error: implicit declaration of function '(eTaskStateGet|pcTaskGetTaskName|pcTimerGetTimerName|pcQueueGetQueueName|vTaskGetTaskInfo|xTaskGetIdleRunTimeCounter)'"
     hint: "You are maybe using pre FreeRTOS V8.0.0 APIs. The backward compatibility of such APIs is no longer enabled by default. Please turn on CONFIG_FREERTOS_ENABLE_BACKWARD_COMPATIBILITY explicitly to use such APIs."
     match_to_output: True
--
-    re: "error: unknown type name 'TaskSnapshot_t'"
-    hint: "The header file task_snapshot.h is no longer included as part of freertos/task.h. Users need to include freertos/task_snapshot.h explicitly."
-    match_to_output: True
--
-    re: "error: implicit declaration of function '(pxTaskGetNext|vTaskGetSnapshot|uxTaskGetSnapshotAll)'"
-    hint: "The header file task_snapshot.h is no longer included as part of freertos/task.h. Users need to include freertos/task_snapshot.h explicitly."
-    match_to_output: True
 -
     re: "error: implicit declaration of function '(portENTER_CRITICAL_NESTED|portEXIT_CRITICAL_NESTED|vPortCPUInitializeMutex|vPortCPUAcquireMutex|vPortCPUAcquireMutexTimeout|vPortCPUReleaseMutex)'"
     hint: "The header file portmacro_deprecated.h has been removed. Users should refer the migration guide for alternative functions."

tools/test_idf_py/error_output.yml

@@ -46,9 +46,6 @@
 "error: invalid use of incomplete typedef 'esp_tls_t'\n":
     "HINT: The struct 'esp_tls_t' has now been made private - its elements can be only be accessed/modified through respective getter/setter functions. Please refer to the migration guide for more information."
 
-"error: unknown type name 'TaskSnapshot_t'\n":
-    'HINT: The header file task_snapshot.h is no longer included as part of freertos/task.h. Users need to include freertos/task_snapshot.h explicitly.'
-
 "Failed to resolve component 'component'\n":
     "HINT: The component component could not be found. This could be because: component name was misspelled, the component was not added to the build, the component has been moved to the IDF component manager or has been removed and refactored into some other component.\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 about moved components.\nRefer to the build-system guide for more details about how components are found and included in the build."