Merge branch 'refactor/freertos_additional_api_headers' into 'master'

FreeRTOS: Refactor IDF API addition headers

See merge request espressif/esp-idf!23104
pull/11189/head
Darian 2023-04-07 18:09:57 +08:00
commit 649fbc01f1
6 zmienionych plików z 223 dodań i 159 usunięć

Wyświetl plik

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

Wyświetl plik

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

Wyświetl plik

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

Wyświetl plik

@ -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"
#ifdef __cplusplus
extern "C" {
#endif
/* -----------------------------------------------------------------------------
* 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
*
* 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.
* Set local storage pointer and deletion callback.
*
* Restore a task's priority that was previously raised by prvTaskPriorityRaise().
* 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.
*
* 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.
* 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.
*
* @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
* @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 // ( INCLUDE_vTaskPrioritySet == 1)
#endif // CONFIG_FREERTOS_SMP || __DOXYGEN__
#ifdef __cplusplus
}
#endif

Wyświetl plik

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

Wyświetl plik

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