freertos: Move IDF API additions to seperate files

This commit moves the IDF API additions from task.h/task.c to seperate header/source files. - Declarations moved to "idf_additions.h" - Definitions moved to "freertos_task_c_additions.h" The API descriptions have also been updated.
2025-09-25 09:42:35 +00:00 · 2022-04-25 17:10:59 +08:00
parent 9bd31a3239
commit efdedaf726
4 changed files with 213 additions and 142 deletions
--- a/components/freertos/esp_additions/include/freertos/idf_additions.h
+++ b/components/freertos/esp_additions/include/freertos/idf_additions.h
@@ -0,0 +1,106 @@
+/*
+ * SPDX-FileCopyrightText: 2022 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include "sdkconfig.h"
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+
+#if CONFIG_FREERTOS_SMP || __DOXYGEN__
+
+/* ------------------------------------------------ Helper Functions ---------------------------------------------------
+ *
+ * ------------------------------------------------------------------------------------------------------------------ */
+
+/**
+ * @brief Create a new task that is pinned to a particular core
+ *
+ * Helper function to create a task that is pinned to a particular core, or has no affinity. In other wrods, the created
+ * task will have an affinity mask of:
+ * - (1 << xCoreID) if it is pinned to a particular core
+ * - Set to tskNO_AFFINITY if it has no affinity
+ *
+ * @param pxTaskCode Pointer to the task entry function.
+ * @param pcName A descriptive name for the task.
+ * @param usStackDepth The size of the task stack.
+ * @param pvParameters Pointer that will be used as the parameter for the task being created.
+ * @param uxPriority The priority at which the task should run.
+ * @param pxCreatedTask Used to pass back a handle by which the created task can be referenced.
+ * @param xCoreID The core to which the task is pinned to, or tskNO_AFFINITY if the task has no core affinity
+ * @return pdPASS if the task was successfully created and added to a ready list, otherwise an error code defined in the
+ *         file projdefs.h
+ */
+BaseType_t xTaskCreatePinnedToCore( TaskFunction_t pxTaskCode,
+                                    const char * const pcName,
+                                    const uint32_t usStackDepth,
+                                    void * const pvParameters,
+                                    UBaseType_t uxPriority,
+                                    TaskHandle_t * const pxCreatedTask,
+                                    const BaseType_t xCoreID);
+
+
+/**
+ * @brief Create a new static task that is pinned to a particular core
+ *
+ * This funciton is the static equivalent of xTaskCreatePinnedToCore().
+ *
+ * @param pxTaskCode Pointer to the task entry function.
+ * @param pcName A descriptive name for the task.
+ * @param ulStackDepth The size of the task stack.
+ * @param pvParameters Pointer that will be used as the parameter for the task being created.
+ * @param uxPriority The priority at which the task should run.
+ * @param puxStackBuffer Must point to a StackType_t array that has at least ulStackDepth indexes
+ * @param pxTaskBuffer Must point to a variable of type StaticTask_t, which will then be used to hold the task's data structures,
+ * @param xCoreID The core to which the task is pinned to, or tskNO_AFFINITY if the task has no core affinity
+ * @return The task handle if the task was created, NULL otherwise.
+ */
+#if ( configSUPPORT_STATIC_ALLOCATION == 1 )
+TaskHandle_t xTaskCreateStaticPinnedToCore( TaskFunction_t pxTaskCode,
+                                            const char * const pcName,
+                                            const uint32_t ulStackDepth,
+                                            void * const pvParameters,
+                                            UBaseType_t uxPriority,
+                                            StackType_t * const puxStackBuffer,
+                                            StaticTask_t * const pxTaskBuffer,
+                                            const BaseType_t xCoreID );
+#endif /* configSUPPORT_STATIC_ALLOCATION */
+
+/**
+ * @brief Get the handle of the task running on a certain core
+ *
+ * Because of the nature of SMP processing, there is no guarantee that this value will still be valid on return and
+ * should only be used for debugging purposes.
+ *
+ * [refactor-todo] Mark this function as deprecated, call xTaskGetCurrentTaskHandleCPU() instead
+ *
+ * @param xCoreID The core to query
+ * @return Handle of the current task running on the queried core
+ */
+TaskHandle_t xTaskGetCurrentTaskHandleForCPU( BaseType_t xCoreID );
+
+/**
+ * @brief Get the handle of idle task for the given CPU.
+ *
+ * [refactor-todo] Mark this function as deprecated, call xTaskGetIdleTaskHandle() instead
+ *
+ * @param xCoreID The core to query
+ * @return Handle of the idle task for the queried core
+ */
+TaskHandle_t xTaskGetIdleTaskHandleForCPU( BaseType_t xCoreID );
+
+/**
+ * @brief Get the current core affintiy of a particular task
+ *
+ * Helper function to get the core affinity of a particular task. If the task is pinned to a particular core, the core
+ * ID is returned. If the task is not pinned to a particular core, tskNO_AFFINITY is returned.
+ *
+ * [refactor-todo] Mark this function as deprecated, call vTaskCoreAffinityGet() instead
+ *
+ * @param xTask The task to query
+ * @return The tasks coreID or tskNO_AFFINITY
+ */
+BaseType_t xTaskGetAffinity( TaskHandle_t xTask );
+
+#endif // CONFIG_FREERTOS_SMP || __DOXYGEN__