From 0c21d5971657d0ea5cca1d8252a07a602b55ee74 Mon Sep 17 00:00:00 2001 From: Darian Leung Date: Thu, 6 Apr 2023 20:56:50 +0800 Subject: [PATCH 1/3] freertos: Move freertos_tasks_c_additions.h freertos_tasks_c_additions.h is technically included as source file. This commit removes the "private_include" directory of "freertos_tasks_c_additions.h" and treats it as a source file of "esp_additions". --- components/freertos/CMakeLists.txt | 2 +- .../freertos_tasks_c_additions.h | 11 +++++------ 2 files changed, 6 insertions(+), 7 deletions(-) rename components/freertos/esp_additions/{private_include => }/freertos_tasks_c_additions.h (98%) diff --git a/components/freertos/CMakeLists.txt b/components/freertos/CMakeLists.txt index f8e3141670..ec244fc76b 100644 --- a/components/freertos/CMakeLists.txt +++ b/components/freertos/CMakeLists.txt @@ -59,7 +59,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) diff --git a/components/freertos/esp_additions/private_include/freertos_tasks_c_additions.h b/components/freertos/esp_additions/freertos_tasks_c_additions.h similarity index 98% rename from components/freertos/esp_additions/private_include/freertos_tasks_c_additions.h rename to components/freertos/esp_additions/freertos_tasks_c_additions.h index bc43cabdcd..526581d3bd 100644 --- a/components/freertos/esp_additions/private_include/freertos_tasks_c_additions.h +++ b/components/freertos/esp_additions/freertos_tasks_c_additions.h @@ -10,12 +10,11 @@ #include "idf_additions_inc.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 -------------------------------------------------------- From 3d2e674326f829d3f41f3127c2b1ae1307ec601e Mon Sep 17 00:00:00 2001 From: Darian Leung Date: Thu, 6 Apr 2023 21:26:17 +0800 Subject: [PATCH 2/3] freertos: Move private API additions to "freertos_idf_additions_priv.h" Previously, some IDF FreeRTOS API additions that were meant to be private were exposed through the same "idf_additions.h" header. This commit moves those functions to a separate header included via "esp_private/freertos_idf_additions_priv.h" so that they are not mistaken as public API by users. This commit also fixes some missing include and C++ guards in idf_additions.h --- components/freertos/CMakeLists.txt | 2 + .../freertos_tasks_c_additions.h | 3 +- .../esp_private/freertos_idf_additions_priv.h | 99 +++++++++++++++++++ .../include/freertos/idf_additions.h | 85 +++++++--------- .../include/freertos/idf_additions_inc.h | 33 ------- components/spi_flash/cache_utils.c | 2 +- 6 files changed, 137 insertions(+), 87 deletions(-) create mode 100644 components/freertos/esp_additions/include/esp_private/freertos_idf_additions_priv.h delete mode 100644 components/freertos/esp_additions/include/freertos/idf_additions_inc.h diff --git a/components/freertos/CMakeLists.txt b/components/freertos/CMakeLists.txt index ec244fc76b..903c69f851 100644 --- a/components/freertos/CMakeLists.txt +++ b/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 diff --git a/components/freertos/esp_additions/freertos_tasks_c_additions.h b/components/freertos/esp_additions/freertos_tasks_c_additions.h index 526581d3bd..5abbcc5207 100644 --- a/components/freertos/esp_additions/freertos_tasks_c_additions.h +++ b/components/freertos/esp_additions/freertos_tasks_c_additions.h @@ -7,7 +7,8 @@ #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 is treated as a source diff --git a/components/freertos/esp_additions/include/esp_private/freertos_idf_additions_priv.h b/components/freertos/esp_additions/include/esp_private/freertos_idf_additions_priv.h new file mode 100644 index 0000000000..c6e6ba81c0 --- /dev/null +++ b/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 diff --git a/components/freertos/esp_additions/include/freertos/idf_additions.h b/components/freertos/esp_additions/include/freertos/idf_additions.h index 6523575c8d..42c46d855a 100644 --- a/components/freertos/esp_additions/include/freertos/idf_additions.h +++ b/components/freertos/esp_additions/include/freertos/idf_additions.h @@ -1,20 +1,34 @@ /* - * 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 exposes 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" + +#ifdef __cplusplus + extern "C" { +#endif + +/* --------------------------------------------------- SMP Related ----------------------------------------------------- + * - 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__ -/* ------------------------------------------------ Helper Functions --------------------------------------------------- - * - * ------------------------------------------------------------------------------------------------------------------ */ - /** * @brief Create a new task that is pinned to a particular core * @@ -104,6 +118,16 @@ TaskHandle_t xTaskGetIdleTaskHandleForCPU( BaseType_t xCoreID ); */ BaseType_t xTaskGetAffinity( TaskHandle_t xTask ); +#endif // CONFIG_FREERTOS_SMP || __DOXYGEN__ + +/* --------------------------------------------- TLSP Deletion Callbacks ----------------------------------------------- + * - API additions for the TLSP deletion callback feature + * + * Todo: Move IDF FreeRTOS TLSP deletion callback additions to this header as well (see IDF-7201) + * ------------------------------------------------------------------------------------------------------------------ */ + +#if CONFIG_FREERTOS_SMP || __DOXYGEN__ + #if ( CONFIG_FREERTOS_TLSP_DELETION_CALLBACKS ) /** @@ -143,49 +167,6 @@ BaseType_t xTaskGetAffinity( TaskHandle_t xTask ); #endif // CONFIG_FREERTOS_SMP || __DOXYGEN__ -#if ( INCLUDE_vTaskPrioritySet == 1 ) - -/** - * 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. - */ -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 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 - */ -void prvTaskPriorityRestore( prvTaskSavedPriority_t * pxSavedPriority ); - -#endif // ( INCLUDE_vTaskPrioritySet == 1) +#ifdef __cplusplus + } +#endif diff --git a/components/freertos/esp_additions/include/freertos/idf_additions_inc.h b/components/freertos/esp_additions/include/freertos/idf_additions_inc.h deleted file mode 100644 index 25b0b6d9a4..0000000000 --- a/components/freertos/esp_additions/include/freertos/idf_additions_inc.h +++ /dev/null @@ -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_ diff --git a/components/spi_flash/cache_utils.c b/components/spi_flash/cache_utils.c index 6fc7e0fcc4..8079bd4630 100644 --- a/components/spi_flash/cache_utils.c +++ b/components/spi_flash/cache_utils.c @@ -11,7 +11,6 @@ #include #include -#include #include #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" From b042ed0495be2a3762843de5c7cb9a1637956597 Mon Sep 17 00:00:00 2001 From: Darian Leung Date: Thu, 6 Apr 2023 23:09:18 +0800 Subject: [PATCH 3/3] freertos: Uncrustify idf_additions.h --- .../include/freertos/idf_additions.h | 185 ++++++++++-------- 1 file changed, 100 insertions(+), 85 deletions(-) diff --git a/components/freertos/esp_additions/include/freertos/idf_additions.h b/components/freertos/esp_additions/include/freertos/idf_additions.h index 42c46d855a..22aac424b7 100644 --- a/components/freertos/esp_additions/include/freertos/idf_additions.h +++ b/components/freertos/esp_additions/include/freertos/idf_additions.h @@ -7,11 +7,13 @@ #pragma once /* -This file contains exposes 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) -*/ + * 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" @@ -21,39 +23,43 @@ additions are not part of Vanilla (i.e., upstream) FreeRTOS and include things s extern "C" { #endif -/* --------------------------------------------------- SMP Related ----------------------------------------------------- - * - SMP related API additions to FreeRTOS +/* ----------------------------------------------------------------------------- + * SMP related API additions to FreeRTOS * - * Todo: Move IDF FreeRTOS SMP related additions to this header as well (see IDF-7201) - * ------------------------------------------------------------------------------------------------------------------ */ + * 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 ); /** @@ -64,106 +70,115 @@ 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 ); + BaseType_t xTaskGetAffinity( TaskHandle_t xTask ); #endif // CONFIG_FREERTOS_SMP || __DOXYGEN__ -/* --------------------------------------------- TLSP Deletion Callbacks ----------------------------------------------- - * - API additions for the TLSP deletion callback feature +/* ----------------------------------------------------------------------------- + * TLSP Deletion Callback related API additions * - * Todo: Move IDF FreeRTOS TLSP deletion callback additions to this header as well (see IDF-7201) - * ------------------------------------------------------------------------------------------------------------------ */ + * 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 ) + #if ( CONFIG_FREERTOS_TLSP_DELETION_CALLBACKS ) - /** - * Prototype of local storage pointer deletion callback. - */ - typedef void (*TlsDeleteCallbackFunction_t)( int, void * ); +/** + * 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 +/** + * 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 #endif // CONFIG_FREERTOS_SMP || __DOXYGEN__