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.
2024-10-05 20:47:46 -04:00 · 2023-08-28 19:17:24 +08:00 · 2023-08-28 19:17:24 +08:00 · 659ec67967
commit 659ec67967
parent e05455e592
9 changed files with 33 additions and 28 deletions
--- a/components/esp_gdbstub/Kconfig
+++ b/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"
--- a/components/esp_system/Kconfig
+++ b/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
--- a/components/espcoredump/Kconfig
+++ b/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"
--- a/components/freertos/Kconfig
+++ b/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
--- a/components/freertos/esp_additions/freertos_tasks_c_additions.h
+++ b/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 -------------------------------------------------------
 *
--- a/components/freertos/esp_additions/include/freertos/task_snapshot.h
+++ b/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
--- a/components/freertos/test_apps/freertos/port/test_tasks_snapshot.c
+++ b/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
--- a/docs/doxygen/Doxyfile
+++ b/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 \
--- a/docs/en/api-reference/system/freertos_additions.rst
+++ b/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``.


@ -256,7 +258,7 @@ Allow-Split buffers will attempt to **split the item into two parts** when the f
 Referring to the diagram above, the 16 bytes of free space at the tail of the buffer is insufficient to store the 28 byte item. Therefore, the item is split into two parts (8 and 20 bytes) and written as two parts to the buffer.

 .. note::
-    
+
    Allow-Split buffers treat both parts of the split item as two separate items, therefore call :cpp:func:`xRingbufferReceiveSplit` instead of :cpp:func:`xRingbufferReceive` to receive both parts of a split item in a thread safe manner.

 .. packetdiag:: ../../../_static/diagrams/ring-buffer/ring_buffer_wrap_byte_buf.diag
@ -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
 ^^^^^^^^^^^^^^