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.

components/freertos/FreeRTOS-Kernel-SMP/include/freertos/task.h

@@ -3279,25 +3279,6 @@ void vTaskYieldWithinAPI( void );
 
 #ifdef ESP_PLATFORM
 
-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);
-
-#if ( configSUPPORT_STATIC_ALLOCATION == 1 )
-TaskHandle_t xTaskCreateStaticPinnedToCore( TaskFunction_t pxTaskCode,
-                                            const char * const pcName,     /*lint !e971 Unqualified char types are allowed for          strings and single characters only. */
-                                            const uint32_t ulStackDepth,
-                                            void * const pvParameters,
-                                            UBaseType_t uxPriority,
-                                            StackType_t * const puxStackBuffer,
-                                            StaticTask_t * const pxTaskBuffer,
-                                            const BaseType_t xCoreID ) PRIVILEGED_FUNCTION;
-#endif /* configSUPPORT_STATIC_ALLOCATION */
-
 #if ( configTHREAD_LOCAL_STORAGE_DELETE_CALLBACKS )
 
     /**
@@ -3331,32 +3312,7 @@ TaskHandle_t xTaskCreateStaticPinnedToCore( TaskFunction_t pxTaskCode,
     void vTaskSetThreadLocalStoragePointerAndDelCallback( TaskHandle_t xTaskToSet, BaseType_t xIndex, void *pvValue, TlsDeleteCallbackFunction_t pvDelCallback);
 #endif
 
-/*
- * Return the handle of the task running on a certain CPU. 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.
- */
-TaskHandle_t xTaskGetCurrentTaskHandleForCPU( BaseType_t cpuid );
-
-/**
- * Get the handle of idle task for the given CPU.
- *
- * xTaskGetIdleTaskHandleForCPU() is only available if
- * INCLUDE_xTaskGetIdleTaskHandle is set to 1 in FreeRTOSConfig.h.
- *
- * @param cpuid The CPU to get the handle for
- *
- * @return Idle task handle of a given cpu. It is not valid to call
- * xTaskGetIdleTaskHandleForCPU() before the scheduler has been started.
- */
-TaskHandle_t xTaskGetIdleTaskHandleForCPU( BaseType_t cpuid );
-
-/*
- * Get the current core affinity of a task
- */
-BaseType_t xTaskGetAffinity( TaskHandle_t xTask ) PRIVILEGED_FUNCTION;
-
+#include "idf_additions.h"
 
 #endif //ESP_PLATFORM
 

components/freertos/FreeRTOS-Kernel-SMP/tasks.c

@@ -6468,65 +6468,6 @@ static void prvAddCurrentTaskToDelayedList( TickType_t xTicksToWait,
 
 #ifdef ESP_PLATFORM
 
-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)
-{
-    BaseType_t ret;
-    #if ( ( configUSE_CORE_AFFINITY == 1 ) && ( configNUM_CORES > 1 ) )
-        {
-            // Convert xCoreID into an affinity mask
-            UBaseType_t uxCoreAffinityMask;
-            if (xCoreID == tskNO_AFFINITY) {
-                uxCoreAffinityMask = tskNO_AFFINITY;
-            } else {
-                uxCoreAffinityMask = (1 << xCoreID);
-            }
-            ret = xTaskCreateAffinitySet(pxTaskCode, pcName, usStackDepth, pvParameters, uxPriority, uxCoreAffinityMask, pxCreatedTask);
-        }
-    #else /* ( ( configUSE_CORE_AFFINITY == 1 ) && ( configNUM_CORES > 1 ) ) */
-        {
-            ret = xTaskCreate(pxTaskCode, pcName, usStackDepth, pvParameters, uxPriority, pxCreatedTask);
-        }
-    #endif /* ( ( configUSE_CORE_AFFINITY == 1 ) && ( configNUM_CORES > 1 ) ) */
-    return ret;
-}
-
-#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)
-{
-    TaskHandle_t ret;
-    #if ( ( configUSE_CORE_AFFINITY == 1 ) && ( configNUM_CORES > 1 ) )
-        {
-            // Convert xCoreID into an affinity mask
-            UBaseType_t uxCoreAffinityMask;
-            if (xCoreID == tskNO_AFFINITY) {
-                uxCoreAffinityMask = tskNO_AFFINITY;
-            } else {
-                uxCoreAffinityMask = (1 << xCoreID);
-            }
-            ret = xTaskCreateStaticAffinitySet(pxTaskCode, pcName, ulStackDepth, pvParameters, uxPriority, puxStackBuffer, pxTaskBuffer, uxCoreAffinityMask);
-        }
-    #else /* ( ( configUSE_CORE_AFFINITY == 1 ) && ( configNUM_CORES > 1 ) ) */
-        {
-            ret = xTaskCreateStatic(pxTaskCode, pcName, ulStackDepth, pvParameters, uxPriority, puxStackBuffer, pxTaskBuffer);
-        }
-    #endif /* ( ( configUSE_CORE_AFFINITY == 1 ) && ( configNUM_CORES > 1 ) ) */
-    return ret;
-}
-#endif /* configSUPPORT_STATIC_ALLOCATION */
-
 #if ( configTHREAD_LOCAL_STORAGE_DELETE_CALLBACKS )
     void vTaskSetThreadLocalStoragePointerAndDelCallback( TaskHandle_t xTaskToSet, BaseType_t xIndex, void *pvValue , TlsDeleteCallbackFunction_t xDelCallback)
     {
@@ -6539,44 +6480,6 @@ TaskHandle_t xTaskCreateStaticPinnedToCore( TaskFunction_t pxTaskCode,
     }
 #endif
 
-TaskHandle_t xTaskGetCurrentTaskHandleForCPU( BaseType_t cpuid )
-{
-    TaskHandle_t xTaskHandleTemp;
-    assert(cpuid >= 0 && cpuid < configNUM_CORES);
-    taskENTER_CRITICAL();
-    xTaskHandleTemp = (TaskHandle_t) pxCurrentTCBs[cpuid];
-    taskEXIT_CRITICAL();
-    return xTaskHandleTemp;
-}
-
-TaskHandle_t xTaskGetIdleTaskHandleForCPU( BaseType_t cpuid )
-{
-    assert(cpuid >= 0 && cpuid < configNUM_CORES);
-    return (TaskHandle_t) xIdleTaskHandle[cpuid];
-}
-
-BaseType_t xTaskGetAffinity( TaskHandle_t xTask )
-{
-    taskENTER_CRITICAL();
-    UBaseType_t uxCoreAffinityMask;
-#if ( configUSE_CORE_AFFINITY == 1 && configNUM_CORES > 1 )
-    TCB_t *pxTCB = prvGetTCBFromHandle( xTask );
-    uxCoreAffinityMask = pxTCB->uxCoreAffinityMask;
-#else
-    uxCoreAffinityMask = tskNO_AFFINITY;
-#endif
-    taskEXIT_CRITICAL();
-    BaseType_t ret;
-    if (uxCoreAffinityMask == tskNO_AFFINITY) {
-        ret = tskNO_AFFINITY;
-    } else {
-        int index_plus_one = __builtin_ffs(uxCoreAffinityMask);
-        assert(index_plus_one >= 1);
-        ret = index_plus_one - 1;
-    }
-    return ret;
-}
-
 #if ( configUSE_NEWLIB_REENTRANT == 1 )
 //Return global reent struct if FreeRTOS isn't running,
 struct _reent* __getreent(void) {

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__

components/freertos/esp_additions/private_include/freertos_tasks_c_additions.h

@@ -237,3 +237,109 @@ const DRAM_ATTR uint8_t FreeRTOS_openocd_params[ESP_FREERTOS_DEBUG_TABLE_END]  =
 };
 
 #endif // configENABLE_FREERTOS_DEBUG_OCDAWARE == 1
+
+/* -------------------------------------------- FreeRTOS IDF API Additions ---------------------------------------------
+ * FreeRTOS related API that were added by IDF
+ * ------------------------------------------------------------------------------------------------------------------ */
+
+#if CONFIG_FREERTOS_SMP
+
+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)
+{
+    BaseType_t ret;
+    #if ( ( configUSE_CORE_AFFINITY == 1 ) && ( configNUM_CORES > 1 ) )
+        {
+            // Convert xCoreID into an affinity mask
+            UBaseType_t uxCoreAffinityMask;
+            if (xCoreID == tskNO_AFFINITY) {
+                uxCoreAffinityMask = tskNO_AFFINITY;
+            } else {
+                uxCoreAffinityMask = (1 << xCoreID);
+            }
+            ret = xTaskCreateAffinitySet(pxTaskCode, pcName, usStackDepth, pvParameters, uxPriority, uxCoreAffinityMask, pxCreatedTask);
+        }
+    #else /* ( ( configUSE_CORE_AFFINITY == 1 ) && ( configNUM_CORES > 1 ) ) */
+        {
+            ret = xTaskCreate(pxTaskCode, pcName, usStackDepth, pvParameters, uxPriority, pxCreatedTask);
+        }
+    #endif /* ( ( configUSE_CORE_AFFINITY == 1 ) && ( configNUM_CORES > 1 ) ) */
+    return ret;
+}
+
+#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)
+{
+    TaskHandle_t ret;
+    #if ( ( configUSE_CORE_AFFINITY == 1 ) && ( configNUM_CORES > 1 ) )
+        {
+            // Convert xCoreID into an affinity mask
+            UBaseType_t uxCoreAffinityMask;
+            if (xCoreID == tskNO_AFFINITY) {
+                uxCoreAffinityMask = tskNO_AFFINITY;
+            } else {
+                uxCoreAffinityMask = (1 << xCoreID);
+            }
+            ret = xTaskCreateStaticAffinitySet(pxTaskCode, pcName, ulStackDepth, pvParameters, uxPriority, puxStackBuffer, pxTaskBuffer, uxCoreAffinityMask);
+        }
+    #else /* ( ( configUSE_CORE_AFFINITY == 1 ) && ( configNUM_CORES > 1 ) ) */
+        {
+            ret = xTaskCreateStatic(pxTaskCode, pcName, ulStackDepth, pvParameters, uxPriority, puxStackBuffer, pxTaskBuffer);
+        }
+    #endif /* ( ( configUSE_CORE_AFFINITY == 1 ) && ( configNUM_CORES > 1 ) ) */
+    return ret;
+}
+#endif /* configSUPPORT_STATIC_ALLOCATION */
+
+TaskHandle_t xTaskGetCurrentTaskHandleForCPU( BaseType_t xCoreID )
+{
+    TaskHandle_t xTaskHandleTemp;
+    assert(xCoreID >= 0 && xCoreID < configNUM_CORES);
+    taskENTER_CRITICAL();
+    xTaskHandleTemp = (TaskHandle_t) pxCurrentTCBs[xCoreID];
+    taskEXIT_CRITICAL();
+    return xTaskHandleTemp;
+}
+
+TaskHandle_t xTaskGetIdleTaskHandleForCPU( BaseType_t xCoreID )
+{
+    assert(xCoreID >= 0 && xCoreID < configNUM_CORES);
+    return (TaskHandle_t) xIdleTaskHandle[xCoreID];
+}
+
+BaseType_t xTaskGetAffinity( TaskHandle_t xTask )
+{
+    taskENTER_CRITICAL();
+    UBaseType_t uxCoreAffinityMask;
+#if ( configUSE_CORE_AFFINITY == 1 && configNUM_CORES > 1 )
+    TCB_t *pxTCB = prvGetTCBFromHandle( xTask );
+    uxCoreAffinityMask = pxTCB->uxCoreAffinityMask;
+#else
+    uxCoreAffinityMask = tskNO_AFFINITY;
+#endif
+    taskEXIT_CRITICAL();
+    BaseType_t ret;
+    // If the task is not pinned to a particular core, treat it as tskNO_AFFINITY
+    if (uxCoreAffinityMask & (uxCoreAffinityMask - 1)) {    // If more than one bit set
+        ret = tskNO_AFFINITY;
+    } else {
+        int index_plus_one = __builtin_ffs(uxCoreAffinityMask);
+        assert(index_plus_one >= 1);
+        ret = index_plus_one - 1;
+    }
+    return ret;
+}
+
+#endif // CONFIG_FREERTOS_SMP