From 9968a48c36f4fa6d224cf73462f9409971329641 Mon Sep 17 00:00:00 2001 From: Darian Leung Date: Thu, 21 Sep 2023 17:17:49 +0800 Subject: [PATCH] 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. --- .../private_include/esp_gdbstub_common.h | 2 +- components/esp_system/task_wdt/task_wdt.c | 2 +- components/espcoredump/src/core_dump_common.c | 2 +- components/freertos/Kconfig | 18 ++++++++--------- .../freertos_tasks_c_additions.h | 2 +- .../freertos_debug.h} | 4 ++++ .../freertos/port/test_tasks_snapshot.c | 2 +- docs/doxygen/Doxyfile | 1 - docs/en/api-guides/performance/ram-usage.rst | 1 - .../system/freertos_additions.rst | 20 ------------------- .../api-guides/performance/ram-usage.rst | 1 - tools/ci/check_ldgen_mapping_exceptions.txt | 1 + 12 files changed, 19 insertions(+), 37 deletions(-) rename components/freertos/esp_additions/include/{freertos/task_snapshot.h => esp_private/freertos_debug.h} (96%) diff --git a/components/esp_gdbstub/private_include/esp_gdbstub_common.h b/components/esp_gdbstub/private_include/esp_gdbstub_common.h index 906a42f3ac..5f3791c354 100644 --- 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 */ diff --git a/components/esp_system/task_wdt/task_wdt.c b/components/esp_system/task_wdt/task_wdt.c index 9bd7770ca2..eba1677783 100644 --- 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" diff --git a/components/espcoredump/src/core_dump_common.c b/components/espcoredump/src/core_dump_common.c index c8d905917d..29b8cda215 100644 --- 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" diff --git a/components/freertos/Kconfig b/components/freertos/Kconfig index ebe716b483..0a1a18e895 100644 --- 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 diff --git a/components/freertos/esp_additions/freertos_tasks_c_additions.h b/components/freertos/esp_additions/freertos_tasks_c_additions.h index e0266a53ef..35383d52e8 100644 --- 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" diff --git a/components/freertos/esp_additions/include/freertos/task_snapshot.h b/components/freertos/esp_additions/include/esp_private/freertos_debug.h similarity index 96% rename from components/freertos/esp_additions/include/freertos/task_snapshot.h rename to components/freertos/esp_additions/include/esp_private/freertos_debug.h index 8cfbe11ffc..5b05289665 100644 --- a/components/freertos/esp_additions/include/freertos/task_snapshot.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" { diff --git a/components/freertos/test_apps/freertos/port/test_tasks_snapshot.c b/components/freertos/test_apps/freertos/port/test_tasks_snapshot.c index 4a911ac63b..ab83fce67e 100644 --- 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 #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" diff --git a/docs/doxygen/Doxyfile b/docs/doxygen/Doxyfile index 8d464a9e4c..e1f160d564 100644 --- 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 \ diff --git a/docs/en/api-guides/performance/ram-usage.rst b/docs/en/api-guides/performance/ram-usage.rst index 33b89d4275..7710bf1d72 100644 --- 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. diff --git a/docs/en/api-reference/system/freertos_additions.rst b/docs/en/api-reference/system/freertos_additions.rst index 1ca7b87913..d47497095d 100644 --- 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 ^^^^^^^^^^^^^^ diff --git a/docs/zh_CN/api-guides/performance/ram-usage.rst b/docs/zh_CN/api-guides/performance/ram-usage.rst index 23c9c14b19..701723fa24 100644 --- 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 性能。 diff --git a/tools/ci/check_ldgen_mapping_exceptions.txt b/tools/ci/check_ldgen_mapping_exceptions.txt index 950ce1c87e..c192068064 100644 --- 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