Merge branch 'refactor/freertos_task_snapshot_option' into 'master'

refactor(freertos): Remove option for Task Snapshot See merge request espressif/esp-idf!25610
2023-08-29 14:19:55 +08:00
parent abc89df287 6adcb64ad4
commit f1c71b75fa
9 changed files with 48 additions and 36 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
 */
@@ -10,11 +10,12 @@
 #include "freertos/FreeRTOS.h"
 #include "freertos/task.h"

+/* *INDENT-OFF* */
 #ifdef __cplusplus
-extern "C" {
+    extern "C" {
 #endif
+/* *INDENT-ON* */

-#if CONFIG_FREERTOS_ENABLE_TASK_SNAPSHOT || defined __DOXYGEN__
 /**
 * @brief Task Snapshot structure
 *
@@ -23,10 +24,10 @@ extern "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*/
+    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;

 /**
@@ -35,7 +36,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 +48,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.
@@ -56,13 +55,13 @@ TaskHandle_t pxTaskGetNext( TaskHandle_t pxTask );
 * @param[out] pxTaskSnapshot Snapshot of the task
 * @return pdTRUE if operation was successful else pdFALSE
 */
-BaseType_t vTaskGetSnapshot( TaskHandle_t pxTask, TaskSnapshot_t *pxTaskSnapshot );
+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.
@@ -71,10 +70,12 @@ BaseType_t vTaskGetSnapshot( TaskHandle_t pxTask, TaskSnapshot_t *pxTaskSnapshot
 * @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 );
-
-#endif // CONFIG_FREERTOS_ENABLE_TASK_SNAPSHOT || defined __DOXYGEN__
+UBaseType_t uxTaskGetSnapshotAll( TaskSnapshot_t * const pxTaskSnapshotArray,
+                                  const UBaseType_t uxArrayLength,
+                                  UBaseType_t * const pxTCBSize );

+/* *INDENT-OFF* */
 #ifdef __cplusplus
-}
+    }
 #endif
+/* *INDENT-ON* */
--- 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``.


@@ -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
 ^^^^^^^^^^^^^^