refactor(freertos/task_snapshot): Make task snapshot private

Task snapshot API were never intended to be called from user code. This commit makes task snapshot a private API thus moves `#include "freertos/task_snapshot.h"` to `#include "esp_private/freertos_debug.h"`. Task snapshot related Kconfig options have also been hidden. Note: Added 'freertos_common' mapping to ldgen mapping execptions lists due to inlining of 'freertos_debug.h' functions.
2024-10-05 20:47:46 -04:00 · 2023-09-21 17:17:49 +08:00 · 2023-09-21 17:17:49 +08:00 · 9968a48c36
commit 9968a48c36
parent fbc31c8f15
12 changed files with 19 additions and 37 deletions
--- 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 "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 */
--- a/components/esp_system/task_wdt/task_wdt.c
+++ b/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"
--- a/components/espcoredump/src/core_dump_common.c
+++ b/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"
--- a/components/freertos/Kconfig
+++ b/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
--- a/components/freertos/esp_additions/freertos_tasks_c_additions.h
+++ b/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"

--- a/components/freertos/esp_additions/include/esp_private/freertos_debug.h
+++ b/components/freertos/esp_additions/include/esp_private/freertos_debug.h
@ -10,6 +10,10 @@
 #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" {
--- 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 "freertos/task_snapshot.h"
+#include "esp_private/freertos_debug.h"
 #include "esp_cpu.h"
 #include "esp_rom_sys.h"
 #include "unity.h"
--- a/docs/doxygen/Doxyfile
+++ b/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 \
--- a/docs/en/api-guides/performance/ram-usage.rst
+++ b/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.
--- a/docs/en/api-reference/system/freertos_additions.rst
+++ b/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
 ^^^^^^^^^^^^^^

--- a/docs/zh_CN/api-guides/performance/ram-usage.rst
+++ b/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 性能。
--- a/tools/ci/check_ldgen_mapping_exceptions.txt
+++ b/tools/ci/check_ldgen_mapping_exceptions.txt
@ -2,3 +2,4 @@ libc
 sha256_coredump
 gcc
 clang_rt_builtins
+freertos_common