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.
This commit is contained in:
Darian Leung 2023-09-21 17:17:49 +08:00
parent fbc31c8f15
commit 9968a48c36
12 changed files with 19 additions and 37 deletions

View File

@ -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 */

View File

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

View File

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

View File

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

View File

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

View File

@ -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" {

View File

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

View File

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

View File

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

View File

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

View File

@ -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 性能。

View File

@ -2,3 +2,4 @@ libc
sha256_coredump
gcc
clang_rt_builtins
freertos_common