refactor(freertos): Remove option for Task Snapshot

Previously, Task Snapshot could be conditionally built based on the
CONFIG_FREERTOS_ENABLE_TASK_SNAPSHOT option. However, there is no overhead
with always enabling Task Snapshot functions, as the linker will remove any
functions if they are not called.

This commit...

- removes all ESP-IDF dependencies on the CONFIG_FREERTOS_ENABLE_TASK_SNAPSHOT
option so that Task Snapshot functions are always available.
- Makes CONFIG_FREERTOS_ENABLE_TASK_SNAPSHOT a hidden option to maintain
compatibility with user code.
- adds documentation regarding Task Snapshot.

components/esp_gdbstub/Kconfig

@@ -4,7 +4,6 @@ menu "GDB Stub"
     # menu in the target component.
     config ESP_GDBSTUB_ENABLED
         bool
-        select FREERTOS_ENABLE_TASK_SNAPSHOT
 
     config ESP_SYSTEM_GDBSTUB_RUNTIME
         bool "GDBStub at runtime"

components/esp_system/Kconfig

@@ -411,7 +411,6 @@ menu "ESP System Settings"
     config ESP_TASK_WDT_EN
         bool "Enable Task Watchdog Timer"
         default y
-        select FREERTOS_ENABLE_TASK_SNAPSHOT
         help
             The Task Watchdog Timer can be used to make sure individual tasks are still
             running. Enabling this option will enable the Task Watchdog Timer. It can be

components/espcoredump/Kconfig

@@ -14,11 +14,9 @@ menu "Core dump"
 
         config ESP_COREDUMP_ENABLE_TO_FLASH
             bool "Flash"
-            select FREERTOS_ENABLE_TASK_SNAPSHOT
             select ESP_COREDUMP_ENABLE
         config ESP_COREDUMP_ENABLE_TO_UART
             bool "UART"
-            select FREERTOS_ENABLE_TASK_SNAPSHOT
             select ESP_COREDUMP_ENABLE
         config ESP_COREDUMP_ENABLE_TO_NONE
             bool "None"

components/freertos/Kconfig

@@ -486,7 +486,7 @@ menu "FreeRTOS"
         config FREERTOS_PLACE_SNAPSHOT_FUNS_INTO_FLASH
             bool "Place task snapshot functions into flash"
             default n
-            depends on FREERTOS_ENABLE_TASK_SNAPSHOT && !ESP_PANIC_HANDLER_IRAM
+            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.
@@ -499,13 +499,6 @@ menu "FreeRTOS"
                 If enabled, context of port*_CRITICAL calls (ISR or Non-ISR) would be checked to be in compliance with
                 Vanilla FreeRTOS. e.g Calling port*_CRITICAL from ISR context would cause assert failure
 
-        config FREERTOS_ENABLE_TASK_SNAPSHOT
-            bool "Enable task snapshot functions"
-            default y
-            help
-                When enabled, the functions related to snapshots, such as vTaskGetSnapshot or uxTaskGetSnapshotAll, are
-                compiled and linked. Task snapshots are used by Task Watchdog (TWDT), GDB Stub and Core dump.
-
     endmenu # Port
 
     # Hidden or compatibility options
@@ -535,4 +528,11 @@ 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 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
+
 endmenu # FreeRTOS

components/freertos/esp_additions/freertos_tasks_c_additions.h

@@ -64,8 +64,6 @@ struct _reent *__getreent(void)
  *
  * ------------------------------------------------------------------------------------------------------------------ */
 
-#if CONFIG_FREERTOS_ENABLE_TASK_SNAPSHOT
-
 #include "freertos/task_snapshot.h"
 
 /**
@@ -246,7 +244,6 @@ UBaseType_t uxTaskGetSnapshotAll( TaskSnapshot_t * const pxTaskSnapshotArray, co
     *pxTCBSize = sizeof(TCB_t);
     return uxArrayNumFilled;
 }
-#endif // CONFIG_FREERTOS_ENABLE_TASK_SNAPSHOT
 
 /* ----------------------------------------------------- OpenOCD -------------------------------------------------------
  *

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

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2021 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -14,7 +14,6 @@
 extern "C" {
 #endif
 
-#if CONFIG_FREERTOS_ENABLE_TASK_SNAPSHOT || defined __DOXYGEN__
 /**
  * @brief Task Snapshot structure
  *
@@ -35,7 +34,6 @@ typedef struct xTASK_SNAPSHOT
  * - 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.
- * - This function is only available when CONFIG_FREERTOS_ENABLE_TASK_SNAPSHOT is set to 1.
  *
  * @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.
@@ -48,7 +46,6 @@ 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.
- * - This function is only available when CONFIG_FREERTOS_ENABLE_TASK_SNAPSHOT is set to 1.
  *
  * @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.
@@ -62,7 +59,6 @@ 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
- * - This function is only available when CONFIG_FREERTOS_ENABLE_TASK_SNAPSHOT is set to 1.
  *
  * @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.
@@ -73,8 +69,6 @@ BaseType_t vTaskGetSnapshot( TaskHandle_t pxTask, TaskSnapshot_t *pxTaskSnapshot
  */
 UBaseType_t uxTaskGetSnapshotAll( TaskSnapshot_t * const pxTaskSnapshotArray, const UBaseType_t uxArrayLength, UBaseType_t * const pxTCBSize );
 
-#endif // CONFIG_FREERTOS_ENABLE_TASK_SNAPSHOT || defined __DOXYGEN__
-
 #ifdef __cplusplus
 }
 #endif

components/freertos/test_apps/freertos/port/test_tasks_snapshot.c

@@ -5,8 +5,6 @@
  */
 
 #include "sdkconfig.h"
-
-#if CONFIG_FREERTOS_ENABLE_TASK_SNAPSHOT
 #include <stdio.h>
 #include <stdbool.h>
 #include "freertos/FreeRTOS.h"
@@ -187,5 +185,3 @@ TEST_CASE("Task snapshot: Iterate", "[freertos]")
     check_snapshots(task_list, num_tasks, task_snapshots, num_snapshots);
     teardown(task_list, num_tasks, old_priority);
 }
-
-#endif // CONFIG_FREERTOS_ENABLE_TASK_SNAPSHOT

docs/doxygen/Doxyfile

@@ -195,6 +195,7 @@ 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-reference/system/freertos_additions.rst

@@ -16,6 +16,8 @@ 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``.
 
 
@@ -434,7 +436,21 @@ 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.
 
-.. ----------------------------------------------- ESP-IDF Additional API --------------------------------------------------
+.. -------------------------------------------------- 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:
 
@@ -468,6 +484,11 @@ Hooks API
 
 .. include-build-file:: inc/esp_freertos_hooks.inc
 
+Task Snapshot API
+^^^^^^^^^^^^^^^^^
+
+.. include-build-file:: inc/task_snapshot.inc
+
 Additional API
 ^^^^^^^^^^^^^^