Merge branch 'refactor/freertos_additional_api_headers' into 'master'

FreeRTOS: Refactor IDF API addition headers

See merge request espressif/esp-idf!23104

components/freertos/CMakeLists.txt

@@ -37,6 +37,8 @@ set(include_dirs
     "esp_additions/include/freertos"         # For files with #include "FreeRTOSConfig.h"
     "esp_additions/include"                  # For files with #include "freertos/FreeRTOSConfig.h"
                                              #      or #include "freertos/task_snapshot.h"
+                                             #      or #include "freertos/idf_additions.h"
+                                             #      or #include "esp_private/freertos_idf_additions_priv.h"
     "esp_additions/arch/${arch}/include")    # For #include "freertos/FreeRTOSConfig_arch.h"
 
 set(private_include_dirs
@@ -59,7 +61,7 @@ else()
         "${kernel_dir}/portable/${arch}/portasm.S")
 
     list(APPEND private_include_dirs
-        "esp_additions/private_include")    # For include "freertos_tasks_c_additions.h"
+        "esp_additions")    # For #include "freertos_tasks_c_additions.h"
 
     if(CONFIG_FREERTOS_SMP)
         set(ldfragments linker_smp.lf linker_common.lf)

components/freertos/esp_additions/private_include/freertos_tasks_c_additions.h → components/freertos/esp_additions/freertos_tasks_c_additions.h

@@ -7,15 +7,15 @@
 #pragma once
 
 #include "sdkconfig.h"
-#include "idf_additions_inc.h"
+#include "idf_additions.h"
+#include "esp_private/freertos_idf_additions_priv.h"
 
 /**
- * This file will be included in `tasks.c` file, thus, it must NOT be included
- * by any (other) file.
- * The functions below only consist in getters for the static variables in
- * `tasks.c` file.
- * The only source files that should call these functions are the ones in
- * `/additions` directory.
+ * This file will be included in `tasks.c` file, thus, it is treated as a source
+ * file instead of a header file, and must NOT be included by any (other) file.
+ * This file is used to add additional functions to `tasks.c`. See the
+ * `esp_additions/include` directory of the headers that expose these `tasks.c`
+ * additional API.
  */
 
 /* ----------------------------------------------------- Newlib --------------------------------------------------------

components/freertos/esp_additions/include/esp_private/freertos_idf_additions_priv.h

@@ -0,0 +1,99 @@
+/*
+ * SPDX-FileCopyrightText: 2023 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+/*
+ * This file is like "idf_additions.h" but for private API (i.e., only meant to
+ * be called by other internally by other
+ * ESP-IDF components.
+ */
+
+#include "sdkconfig.h"
+#include "freertos/FreeRTOS.h"
+
+#ifdef __cplusplus
+    extern "C" {
+#endif
+
+/* -----------------------------------------------------------------------------
+ * Priority Raise/Restore
+ * - Special functions to forcefully raise and restore a task's priority
+ * - Used by cache_utils.c when disabling/enabling the cache
+ * -------------------------------------------------------------------------- */
+
+#if ( INCLUDE_vTaskPrioritySet == 1 )
+
+    typedef struct
+    {
+        UBaseType_t uxPriority;
+        #if ( configUSE_MUTEXES == 1 )
+            UBaseType_t uxBasePriority;
+        #endif
+    } prvTaskSavedPriority_t;
+
+/**
+ * INCLUDE_vTaskPrioritySet must be defined as 1 for this function to be
+ * available. See the configuration section for more information.
+ *
+ * Saves the current priority and current base priority of a task, then
+ * raises the task's current and base priority to uxNewPriority if
+ * uxNewPriority is of a higher priority.
+ *
+ * Once a task's priority has been raised with this function, the priority
+ * can be restored by calling prvTaskPriorityRestore()
+ *
+ * - Note that this function differs from vTaskPrioritySet() as the task's
+ *   current priority will be modified even if the task has already
+ *   inherited a priority.
+ * - This function is intended for special circumstance where a task must be
+ *   forced immediately to a higher priority.
+ *
+ * For configUSE_MUTEXES == 0: A context switch will occur before the
+ * function returns if the priority being set is higher than the currently
+ * executing task.
+ *
+ * @note This functions is private and should only be called internally
+ * within various IDF components. Users should never call this function from
+ * their application.
+ *
+ * @note vTaskPrioritySet() should not be called while a task's priority is
+ * already raised via this function
+ *
+ * @param pxSavedPriority returns base and current priorities
+ *
+ * @param uxNewPriority The priority to which the task's priority will be
+ * set.
+ */
+    void prvTaskPriorityRaise( prvTaskSavedPriority_t * pxSavedPriority,
+                               UBaseType_t uxNewPriority );
+
+/**
+ * INCLUDE_vTaskPrioritySet must be defined as 1 for this function to be
+ * available.
+ * See the configuration section for more information.
+ *
+ * Restore a task's priority that was previously raised by
+ * prvTaskPriorityRaise().
+ *
+ * For configUSE_MUTEXES == 0: A context switch will occur before the function
+ * returns if the priority
+ * being set is higher than the currently executing task.
+ *
+ * @note This functions is private and should only be called internally within
+ * various IDF components. Users should never call this function from their
+ * application.
+ *
+ * @param pxSavedPriority previously saved base and current priorities that need
+ * to be restored
+ */
+    void prvTaskPriorityRestore( prvTaskSavedPriority_t * pxSavedPriority );
+
+#endif // ( INCLUDE_vTaskPrioritySet == 1)
+
+#ifdef __cplusplus
+    }
+#endif

components/freertos/esp_additions/include/freertos/idf_additions.h

@@ -1,45 +1,65 @@
 /*
- * SPDX-FileCopyrightText: 2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2023 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
 
+#pragma once
+
+/*
+ * This file contains the function prototypes of ESP-IDF specific API additions
+ * to the FreeRTOS kernel. These API additions are not part of Vanilla (i.e.,
+ * upstream) FreeRTOS and include things such as....
+ *    - Various helper functions
+ *    - API for ESP-IDF feature additions to FreeRTOS (such as TSLP deletion
+ * call backs)
+ */
+
 #include "sdkconfig.h"
 #include "freertos/FreeRTOS.h"
 #include "freertos/task.h"
-#include "idf_additions_inc.h"
 
-#if CONFIG_FREERTOS_SMP || __DOXYGEN__
+#ifdef __cplusplus
+    extern "C" {
+#endif
 
-/* ------------------------------------------------ Helper Functions ---------------------------------------------------
+/* -----------------------------------------------------------------------------
+ * SMP related API additions to FreeRTOS
  *
- * ------------------------------------------------------------------------------------------------------------------ */
+ * Todo: Move IDF FreeRTOS SMP related additions to this header as well (see
+ * IDF-7201)
+ * -------------------------------------------------------------------------- */
+
+#if CONFIG_FREERTOS_SMP || __DOXYGEN__
 
 /**
  * @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:
+ * 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 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
+ * @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);
+    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 );
 
 
 /**
@@ -50,142 +70,118 @@ BaseType_t xTaskCreatePinnedToCore( TaskFunction_t pxTaskCode,
  * @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 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
+ * @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 */
+    #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.
+ * 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
+ * [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 );
+    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
+ * [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 );
+    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.
+ * 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
+ * [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 );
-
-#if ( CONFIG_FREERTOS_TLSP_DELETION_CALLBACKS )
-
-    /**
-     * Prototype of local storage pointer deletion callback.
-     */
-    typedef void (*TlsDeleteCallbackFunction_t)( int, void * );
-
-    /**
-     * Set local storage pointer and deletion callback.
-     *
-     * Each task contains an array of pointers that is dimensioned by the
-     * configNUM_THREAD_LOCAL_STORAGE_POINTERS setting in FreeRTOSConfig.h.
-     * The kernel does not use the pointers itself, so the application writer
-     * can use the pointers for any purpose they wish.
-     *
-     * Local storage pointers set for a task can reference dynamically
-     * allocated resources. This function is similar to
-     * vTaskSetThreadLocalStoragePointer, but provides a way to release
-     * these resources when the task gets deleted. For each pointer,
-     * a callback function can be set. This function will be called
-     * when task is deleted, with the local storage pointer index
-     * and value as arguments.
-     *
-     * @param xTaskToSet  Task to set thread local storage pointer for
-     * @param xIndex The index of the pointer to set, from 0 to
-     *               configNUM_THREAD_LOCAL_STORAGE_POINTERS - 1.
-     * @param pvValue  Pointer value to set.
-     * @param pvDelCallback  Function to call to dispose of the local
-     *                       storage pointer when the task is deleted.
-     */
-    void vTaskSetThreadLocalStoragePointerAndDelCallback(
-            TaskHandle_t xTaskToSet,
-            BaseType_t xIndex,
-            void *pvValue,
-            TlsDeleteCallbackFunction_t pvDelCallback);
-#endif // CONFIG_FREERTOS_TLSP_DELETION_CALLBACKS
+    BaseType_t xTaskGetAffinity( TaskHandle_t xTask );
 
 #endif // CONFIG_FREERTOS_SMP || __DOXYGEN__
 
-#if ( INCLUDE_vTaskPrioritySet == 1 )
+/* -----------------------------------------------------------------------------
+ * TLSP Deletion Callback related API additions
+ *
+ * Todo: Move IDF FreeRTOS TLSP Deletion Callback related additions to this
+ * header as well (see IDF-7201)
+ * -------------------------------------------------------------------------- */
+
+#if CONFIG_FREERTOS_SMP || __DOXYGEN__
+
+    #if ( CONFIG_FREERTOS_TLSP_DELETION_CALLBACKS )
 
 /**
- * INCLUDE_vTaskPrioritySet must be defined as 1 for this function to be available.
- * See the configuration section for more information.
- *
- * Saves the current priority and current base priority of a task, then raises the tasks
- * current and base priority to uxNewPriority if uxNewPriority is of a higher priority.
- * Once a task's priority has been raised with this function, the priority can be restored
- * by calling prvTaskPriorityRestore()
- * - Note that this function differs from vTaskPrioritySet() as the task's current priority
- *   will be modified even if the task has already inherited a priority.
- * - This function is intended for special circumstance where a task must be forced immediately
- *   to a higher priority.
- *
- * For configUSE_MUTEXES == 0: A context switch will occur before the function returns if the priority
- * being set is higher than the currently executing task.
- *
- * @note This functions is private is only be called internally within various IDF components.
- *       Users should never call this function from their application.
- *
- * @note vTaskPrioritySet() should not be called while a task's priority is already raised via this function
- *
- * @param pxSavedPriority returns base and current priorities
- *
- * @param uxNewPriority The priority to which the task will be set.
+ * Prototype of local storage pointer deletion callback.
  */
-void prvTaskPriorityRaise( prvTaskSavedPriority_t * pxSavedPriority, UBaseType_t uxNewPriority );
+        typedef void (* TlsDeleteCallbackFunction_t)( int,
+                                                      void * );
 
 /**
- * INCLUDE_vTaskPrioritySet must be defined as 1 for this function to be available.
- * See the configuration section for more information.
- *
- * Restore a task's priority that was previously raised by prvTaskPriorityRaise().
- *
- * For configUSE_MUTEXES == 0: A context switch will occur before the function returns if the priority
- * being set is higher than the currently executing task.
- *
- * @note This functions is private is only be called internally within various IDF components.
- *       Users should never call this function from their application.
- *
- * @param pxSavedPriority previously saved base and current priorities that need to be restored
+ * Set local storage pointer and deletion callback.
+ *
+ * Each task contains an array of pointers that is dimensioned by the
+ * configNUM_THREAD_LOCAL_STORAGE_POINTERS setting in FreeRTOSConfig.h. The
+ * kernel does not use the pointers itself, so the application writer can use
+ * the pointers for any purpose they wish.
+ *
+ * Local storage pointers set for a task can reference dynamically allocated
+ * resources. This function is similar to vTaskSetThreadLocalStoragePointer, but
+ * provides a way to release these resources when the task gets deleted. For
+ * each pointer, a callback function can be set. This function will be called
+ * when task is deleted, with the local storage pointer index and value as
+ * arguments.
+ *
+ * @param xTaskToSet  Task to set thread local storage pointer for
+ * @param xIndex The index of the pointer to set, from 0 to
+ * configNUM_THREAD_LOCAL_STORAGE_POINTERS - 1.
+ * @param pvValue Pointer value to set.
+ * @param pvDelCallback  Function to call to dispose of the local storage
+ * pointer when the task is deleted.
  */
-void prvTaskPriorityRestore( prvTaskSavedPriority_t * pxSavedPriority );
+        void vTaskSetThreadLocalStoragePointerAndDelCallback( TaskHandle_t xTaskToSet,
+                                                              BaseType_t xIndex,
+                                                              void * pvValue,
+                                                              TlsDeleteCallbackFunction_t pvDelCallback );
+    #endif // CONFIG_FREERTOS_TLSP_DELETION_CALLBACKS
+
+#endif // CONFIG_FREERTOS_SMP || __DOXYGEN__
 
-#endif // ( INCLUDE_vTaskPrioritySet == 1)
+#ifdef __cplusplus
+    }
+#endif

components/freertos/esp_additions/include/freertos/idf_additions_inc.h

@@ -1,33 +0,0 @@
-/*
- * SPDX-FileCopyrightText: 2022 Espressif Systems (Shanghai) CO LTD
- *
- * SPDX-License-Identifier: Apache-2.0
- */
-
-
-#ifndef FREERTOS_ADDITITIONS_INC_H_
-#define FREERTOS_ADDITITIONS_INC_H_
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-#include "sdkconfig.h"
-#include "freertos/FreeRTOS.h"
-
-#if ( INCLUDE_vTaskPrioritySet == 1 )
-
-typedef struct {
-    UBaseType_t uxPriority;
-#if ( configUSE_MUTEXES == 1 )
-    UBaseType_t uxBasePriority;
-#endif
-} prvTaskSavedPriority_t;
-
-#endif // ( INCLUDE_vTaskPrioritySet == 1)
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif //FREERTOS_ADDITITIONS_INC_H_

components/spi_flash/cache_utils.c

@@ -11,7 +11,6 @@
 
 #include <freertos/FreeRTOS.h>
 #include <freertos/task.h>
-#include <freertos/idf_additions.h>
 #include <freertos/semphr.h>
 #if CONFIG_IDF_TARGET_ESP32
 #include "soc/dport_reg.h"
@@ -57,6 +56,7 @@
 #include "spi_flash_mmap.h"
 #include "spi_flash_override.h"
 #include "esp_private/spi_flash_os.h"
+#include "esp_private/freertos_idf_additions_priv.h"
 #include "esp_log.h"
 #include "esp_cpu.h"