ESP32-IDF
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
Data Structures | Macros | Typedefs | Enumerations | Functions
task.h File Reference
#include <limits.h>
#include "list.h"
#include "portmacro.h"

Go to the source code of this file.

Data Structures

struct  xTIME_OUT
 
struct  xMEMORY_REGION
 
struct  xTASK_PARAMETERS
 
struct  xTASK_STATUS
 

Macros

#define tskKERNEL_VERSION_NUMBER   "V8.2.0"
 
#define tskKERNEL_VERSION_MAJOR   8
 
#define tskKERNEL_VERSION_MINOR   2
 
#define tskKERNEL_VERSION_BUILD   0
 
#define tskNO_AFFINITY   INT_MAX
 
#define tskIDLE_PRIORITY   ( ( UBaseType_t ) 0U )
 
#define taskYIELD()   portYIELD()
 
#define taskENTER_CRITICAL(mux)   portENTER_CRITICAL(mux)
 
#define taskENTER_CRITICAL_ISR(mux)   portENTER_CRITICAL_ISR(mux)
 
#define taskEXIT_CRITICAL(mux)   portEXIT_CRITICAL(mux)
 
#define taskEXIT_CRITICAL_ISR(mux)   portEXIT_CRITICAL_ISR(mux)
 
#define taskDISABLE_INTERRUPTS()   portDISABLE_INTERRUPTS()
 
#define taskENABLE_INTERRUPTS()   portENABLE_INTERRUPTS()
 
#define taskSCHEDULER_SUSPENDED   ( ( BaseType_t ) 0 )
 
#define taskSCHEDULER_NOT_STARTED   ( ( BaseType_t ) 1 )
 
#define taskSCHEDULER_RUNNING   ( ( BaseType_t ) 2 )
 
#define xTaskCreate(pvTaskCode, pcName, usStackDepth, pvParameters, uxPriority, pxCreatedTask)   xTaskGenericCreate( ( pvTaskCode ), ( pcName ), ( usStackDepth ), ( pvParameters ), ( uxPriority ), ( pxCreatedTask ), ( NULL ), ( NULL ), tskNO_AFFINITY )
 
#define xTaskCreatePinnedToCore(pvTaskCode, pcName, usStackDepth, pvParameters, uxPriority, pxCreatedTask, xCoreID)   xTaskGenericCreate( ( pvTaskCode ), ( pcName ), ( usStackDepth ), ( pvParameters ), ( uxPriority ), ( pxCreatedTask ), ( NULL ), ( NULL ), xCoreID )
 
#define xTaskCreateRestricted(x, pxCreatedTask)   xTaskGenericCreate( ((x)->pvTaskCode), ((x)->pcName), ((x)->usStackDepth), ((x)->pvParameters), ((x)->uxPriority), (pxCreatedTask), ((x)->puxStackBuffer), ((x)->xRegions) )
 
#define xTaskNotifyGive(xTaskToNotify)   xTaskNotify( ( xTaskToNotify ), 0, eIncrement );
 

Typedefs

typedef voidTaskHandle_t
 
typedef BaseType_t(* TaskHookFunction_t )(void *)
 
typedef struct xTIME_OUT TimeOut_t
 
typedef struct xMEMORY_REGION MemoryRegion_t
 
typedef struct xTASK_PARAMETERS TaskParameters_t
 
typedef struct xTASK_STATUS TaskStatus_t
 

Enumerations

enum  eTaskState {
  eRunning = 0, eReady, eBlocked, eSuspended,
  eDeleted
}
 
enum  eNotifyAction {
  eNoAction = 0, eSetBits, eIncrement, eSetValueWithOverwrite,
  eSetValueWithoutOverwrite
}
 
enum  eSleepModeStatus { eAbortSleep = 0, eStandardSleep, eNoTasksWaitingTimeout }
 

Functions

void vTaskAllocateMPURegions (TaskHandle_t xTask, const MemoryRegion_t *const pxRegions) PRIVILEGED_FUNCTION
 
void vTaskDelete (TaskHandle_t xTaskToDelete) PRIVILEGED_FUNCTION
 
void vTaskDelay (const TickType_t xTicksToDelay) PRIVILEGED_FUNCTION
 
void vTaskDelayUntil (TickType_t *const pxPreviousWakeTime, const TickType_t xTimeIncrement) PRIVILEGED_FUNCTION
 
UBaseType_t uxTaskPriorityGet (TaskHandle_t xTask) PRIVILEGED_FUNCTION
 
UBaseType_t uxTaskPriorityGetFromISR (TaskHandle_t xTask) PRIVILEGED_FUNCTION
 
eTaskState eTaskGetState (TaskHandle_t xTask) PRIVILEGED_FUNCTION
 
void vTaskPrioritySet (TaskHandle_t xTask, UBaseType_t uxNewPriority) PRIVILEGED_FUNCTION
 
void vTaskSuspend (TaskHandle_t xTaskToSuspend) PRIVILEGED_FUNCTION
 
void vTaskResume (TaskHandle_t xTaskToResume) PRIVILEGED_FUNCTION
 
BaseType_t xTaskResumeFromISR (TaskHandle_t xTaskToResume) PRIVILEGED_FUNCTION
 
void vTaskStartScheduler (void) PRIVILEGED_FUNCTION
 
void vTaskEndScheduler (void) PRIVILEGED_FUNCTION
 
void vTaskSuspendAll (void) PRIVILEGED_FUNCTION
 
BaseType_t xTaskResumeAll (void) PRIVILEGED_FUNCTION
 
TickType_t xTaskGetTickCount (void) PRIVILEGED_FUNCTION
 
TickType_t xTaskGetTickCountFromISR (void) PRIVILEGED_FUNCTION
 
UBaseType_t uxTaskGetNumberOfTasks (void) PRIVILEGED_FUNCTION
 
char * pcTaskGetTaskName (TaskHandle_t xTaskToQuery) PRIVILEGED_FUNCTION
 
UBaseType_t uxTaskGetStackHighWaterMark (TaskHandle_t xTask) PRIVILEGED_FUNCTION
 
BaseType_t xTaskCallApplicationTaskHook (TaskHandle_t xTask, void *pvParameter) PRIVILEGED_FUNCTION
 
TaskHandle_t xTaskGetIdleTaskHandle (void)
 
UBaseType_t uxTaskGetSystemState (TaskStatus_t *const pxTaskStatusArray, const UBaseType_t uxArraySize, uint32_t *const pulTotalRunTime)
 
void vTaskList (char *pcWriteBuffer) PRIVILEGED_FUNCTION
 
void vTaskGetRunTimeStats (char *pcWriteBuffer) PRIVILEGED_FUNCTION
 
BaseType_t xTaskNotify (TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction)
 
BaseType_t xTaskNotifyFromISR (TaskHandle_t xTaskToNotify, uint32_t ulValue, eNotifyAction eAction, BaseType_t *pxHigherPriorityTaskWoken)
 
BaseType_t xTaskNotifyWait (uint32_t ulBitsToClearOnEntry, uint32_t ulBitsToClearOnExit, uint32_t *pulNotificationValue, TickType_t xTicksToWait)
 
void vTaskNotifyGiveFromISR (TaskHandle_t xTaskToNotify, BaseType_t *pxHigherPriorityTaskWoken)
 
uint32_t ulTaskNotifyTake (BaseType_t xClearCountOnExit, TickType_t xTicksToWait)
 
BaseType_t xTaskIncrementTick (void) PRIVILEGED_FUNCTION
 
void vTaskPlaceOnEventList (List_t *const pxEventList, const TickType_t xTicksToWait) PRIVILEGED_FUNCTION
 
void vTaskPlaceOnUnorderedEventList (List_t *pxEventList, const TickType_t xItemValue, const TickType_t xTicksToWait) PRIVILEGED_FUNCTION
 
void vTaskPlaceOnEventListRestricted (List_t *const pxEventList, const TickType_t xTicksToWait) PRIVILEGED_FUNCTION
 
BaseType_t xTaskRemoveFromEventList (const List_t *const pxEventList) PRIVILEGED_FUNCTION
 
BaseType_t xTaskRemoveFromUnorderedEventList (ListItem_t *pxEventListItem, const TickType_t xItemValue) PRIVILEGED_FUNCTION
 
void vTaskSwitchContext (void) PRIVILEGED_FUNCTION
 
TickType_t uxTaskResetEventItemValue (void) PRIVILEGED_FUNCTION
 
TaskHandle_t xTaskGetCurrentTaskHandle (void) PRIVILEGED_FUNCTION
 
void vTaskSetTimeOutState (TimeOut_t *const pxTimeOut) PRIVILEGED_FUNCTION
 
BaseType_t xTaskCheckForTimeOut (TimeOut_t *const pxTimeOut, TickType_t *const pxTicksToWait) PRIVILEGED_FUNCTION
 
void vTaskMissedYield (void) PRIVILEGED_FUNCTION
 
BaseType_t xTaskGetSchedulerState (void) PRIVILEGED_FUNCTION
 
void vTaskPriorityInherit (TaskHandle_t const pxMutexHolder) PRIVILEGED_FUNCTION
 
BaseType_t xTaskPriorityDisinherit (TaskHandle_t const pxMutexHolder) PRIVILEGED_FUNCTION
 
BaseType_t xTaskGenericCreate (TaskFunction_t pxTaskCode, const char *const pcName, const uint16_t usStackDepth, void *const pvParameters, UBaseType_t uxPriority, TaskHandle_t *const pxCreatedTask, StackType_t *const puxStackBuffer, const MemoryRegion_t *const xRegions, const BaseType_t xCoreID) PRIVILEGED_FUNCTION
 
UBaseType_t uxTaskGetTaskNumber (TaskHandle_t xTask) PRIVILEGED_FUNCTION
 
void vTaskSetTaskNumber (TaskHandle_t xTask, const UBaseType_t uxHandle) PRIVILEGED_FUNCTION
 
void vTaskStepTick (const TickType_t xTicksToJump) PRIVILEGED_FUNCTION
 
eSleepModeStatus eTaskConfirmSleepModeStatus (void) PRIVILEGED_FUNCTION
 
voidpvTaskIncrementMutexHeldCount (void)
 

Macro Definition Documentation

#define taskDISABLE_INTERRUPTS ( )    portDISABLE_INTERRUPTS()
#define taskENABLE_INTERRUPTS ( )    portENABLE_INTERRUPTS()
#define taskENTER_CRITICAL (   mux)    portENTER_CRITICAL(mux)
#define taskENTER_CRITICAL_ISR (   mux)    portENTER_CRITICAL_ISR(mux)
#define taskEXIT_CRITICAL (   mux)    portEXIT_CRITICAL(mux)
#define taskEXIT_CRITICAL_ISR (   mux)    portEXIT_CRITICAL_ISR(mux)
#define taskSCHEDULER_NOT_STARTED   ( ( BaseType_t ) 1 )
#define taskSCHEDULER_RUNNING   ( ( BaseType_t ) 2 )
#define taskSCHEDULER_SUSPENDED   ( ( BaseType_t ) 0 )
#define taskYIELD ( )    portYIELD()
#define tskIDLE_PRIORITY   ( ( UBaseType_t ) 0U )

Defines the priority used by the idle task. This must not be modified.

#define tskKERNEL_VERSION_BUILD   0
#define tskKERNEL_VERSION_MAJOR   8
#define tskKERNEL_VERSION_MINOR   2
#define tskKERNEL_VERSION_NUMBER   "V8.2.0"
#define tskNO_AFFINITY   INT_MAX
#define xTaskCreate (   pvTaskCode,
  pcName,
  usStackDepth,
  pvParameters,
  uxPriority,
  pxCreatedTask 
)    xTaskGenericCreate( ( pvTaskCode ), ( pcName ), ( usStackDepth ), ( pvParameters ), ( uxPriority ), ( pxCreatedTask ), ( NULL ), ( NULL ), tskNO_AFFINITY )
#define xTaskCreatePinnedToCore (   pvTaskCode,
  pcName,
  usStackDepth,
  pvParameters,
  uxPriority,
  pxCreatedTask,
  xCoreID 
)    xTaskGenericCreate( ( pvTaskCode ), ( pcName ), ( usStackDepth ), ( pvParameters ), ( uxPriority ), ( pxCreatedTask ), ( NULL ), ( NULL ), xCoreID )
#define xTaskCreateRestricted (   x,
  pxCreatedTask 
)    xTaskGenericCreate( ((x)->pvTaskCode), ((x)->pcName), ((x)->usStackDepth), ((x)->pvParameters), ((x)->uxPriority), (pxCreatedTask), ((x)->puxStackBuffer), ((x)->xRegions) )
#define xTaskNotifyGive (   xTaskToNotify)    xTaskNotify( ( xTaskToNotify ), 0, eIncrement );

Typedef Documentation

typedef void* TaskHandle_t
typedef BaseType_t(* TaskHookFunction_t)(void *)
typedef struct xTASK_STATUS TaskStatus_t
typedef struct xTIME_OUT TimeOut_t

Enumeration Type Documentation

Enumerator
eNoAction 
eSetBits 
eIncrement 
eSetValueWithOverwrite 
eSetValueWithoutOverwrite 
Enumerator
eAbortSleep 
eStandardSleep 
eNoTasksWaitingTimeout 
enum eTaskState
Enumerator
eRunning 
eReady 
eBlocked 
eSuspended 
eDeleted 

Function Documentation

eSleepModeStatus eTaskConfirmSleepModeStatus ( void  )
eTaskState eTaskGetState ( TaskHandle_t  xTask)

task. h

eTaskState eTaskGetState( TaskHandle_t xTask );

INCLUDE_eTaskGetState must be defined as 1 for this function to be available. See the configuration section for more information.

Obtain the state of any task. States are encoded by the eTaskState enumerated type.

Parameters
xTaskHandle of the task to be queried.
Returns
The state of xTask at the time the function was called. Note the state of the task might change between the function being called, and the functions return value being tested by the calling task.
char* pcTaskGetTaskName ( TaskHandle_t  xTaskToQuery)
void* pvTaskIncrementMutexHeldCount ( void  )
uint32_t ulTaskNotifyTake ( BaseType_t  xClearCountOnExit,
TickType_t  xTicksToWait 
)
UBaseType_t uxTaskGetNumberOfTasks ( void  )
UBaseType_t uxTaskGetStackHighWaterMark ( TaskHandle_t  xTask)

task.h

UBaseType_t uxTaskGetStackHighWaterMark( TaskHandle_t xTask );

INCLUDE_uxTaskGetStackHighWaterMark must be set to 1 in FreeRTOSConfig.h for this function to be available.

Returns the high water mark of the stack associated with xTask. That is, the minimum free stack space there has been (in words, so on a 32 bit machine a value of 1 means 4 bytes) since the task started. The smaller the returned number the closer the task has come to overflowing its stack.

Parameters
xTaskHandle of the task associated with the stack to be checked. Set xTask to NULL to check the stack of the calling task.
Returns
The smallest amount of free stack space there has been (in words, so actual spaces on the stack rather than bytes) since the task referenced by xTask was created.
UBaseType_t uxTaskGetSystemState ( TaskStatus_t *const  pxTaskStatusArray,
const UBaseType_t  uxArraySize,
uint32_t *const  pulTotalRunTime 
)

configUSE_TRACE_FACILITY must be defined as 1 in FreeRTOSConfig.h for uxTaskGetSystemState() to be available.

uxTaskGetSystemState() populates an TaskStatus_t structure for each task in the system. TaskStatus_t structures contain, among other things, members for the task handle, task name, task priority, task state, and total amount of run time consumed by the task. See the TaskStatus_t structure definition in this file for the full member list.

NOTE: This function is intended for debugging use only as its use results in the scheduler remaining suspended for an extended period.

Parameters
pxTaskStatusArrayA pointer to an array of TaskStatus_t structures. The array must contain at least one TaskStatus_t structure for each task that is under the control of the RTOS. The number of tasks under the control of the RTOS can be determined using the uxTaskGetNumberOfTasks() API function.
uxArraySizeThe size of the array pointed to by the pxTaskStatusArray parameter. The size is specified as the number of indexes in the array, or the number of TaskStatus_t structures contained in the array, not by the number of bytes in the array.
pulTotalRunTimeIf configGENERATE_RUN_TIME_STATS is set to 1 in FreeRTOSConfig.h then *pulTotalRunTime is set by uxTaskGetSystemState() to the total run time (as defined by the run time stats clock, see http://www.freertos.org/rtos-run-time-stats.html) since the target booted. pulTotalRunTime can be set to NULL to omit the total run time information.
Returns
The number of TaskStatus_t structures that were populated by uxTaskGetSystemState(). This should equal the number returned by the uxTaskGetNumberOfTasks() API function, but will be zero if the value passed in the uxArraySize parameter was too small.

Example usage:

 // This example demonstrates how a human readable table of run time stats
// information is generated from raw data provided by uxTaskGetSystemState().
// The human readable table is written to pcWriteBuffer
void vTaskGetRunTimeStats( char *pcWriteBuffer )
{
TaskStatus_t *pxTaskStatusArray;
volatile UBaseType_t uxArraySize, x;
uint32_t ulTotalRunTime, ulStatsAsPercentage;
   // Make sure the write buffer does not contain a string.
   *pcWriteBuffer = 0x00;
   // Take a snapshot of the number of tasks in case it changes while this
   // function is executing.
   uxArraySize = uxTaskGetNumberOfTasks();
   // Allocate a TaskStatus_t structure for each task.  An array could be
   // allocated statically at compile time.
   pxTaskStatusArray = pvPortMalloc( uxArraySize * sizeof( TaskStatus_t ) );
   if( pxTaskStatusArray != NULL )
   {
      // Generate raw status information about each task.
      uxArraySize = uxTaskGetSystemState( pxTaskStatusArray, uxArraySize, &ulTotalRunTime );
      // For percentage calculations.
      ulTotalRunTime /= 100UL;
      // Avoid divide by zero errors.
      if( ulTotalRunTime > 0 )
      {
         // For each populated position in the pxTaskStatusArray array,
         // format the raw data as human readable ASCII data
         for( x = 0; x < uxArraySize; x++ )
         {
            // What percentage of the total run time has the task used?
            // This will always be rounded down to the nearest integer.
            // ulTotalRunTimeDiv100 has already been divided by 100.
            ulStatsAsPercentage = pxTaskStatusArray[ x ].ulRunTimeCounter / ulTotalRunTime;
            if( ulStatsAsPercentage > 0UL )
            {
               sprintf( pcWriteBuffer, "%s\t\t%lu\t\t%lu%%\r\n", pxTaskStatusArray[ x ].pcTaskName, pxTaskStatusArray[ x ].ulRunTimeCounter, ulStatsAsPercentage );
            }
            else
            {
               // If the percentage is zero here then the task has
               // consumed less than 1% of the total run time.
               sprintf( pcWriteBuffer, "%s\t\t%lu\t\t<1%%\r\n", pxTaskStatusArray[ x ].pcTaskName, pxTaskStatusArray[ x ].ulRunTimeCounter );
            }
            pcWriteBuffer += strlen( ( char * ) pcWriteBuffer );
         }
      }
      // The array is no longer needed, free the memory it consumes.
      vPortFree( pxTaskStatusArray );
   }
}
UBaseType_t uxTaskGetTaskNumber ( TaskHandle_t  xTask)
UBaseType_t uxTaskPriorityGet ( TaskHandle_t  xTask)
UBaseType_t uxTaskPriorityGetFromISR ( TaskHandle_t  xTask)

task. h

UBaseType_t uxTaskPriorityGetFromISR( TaskHandle_t xTask );

A version of uxTaskPriorityGet() that can be used from an ISR.

TickType_t uxTaskResetEventItemValue ( void  )
void vTaskAllocateMPURegions ( TaskHandle_t  xTask,
const MemoryRegion_t *const  pxRegions 
)
void vTaskDelay ( const TickType_t  xTicksToDelay)
void vTaskDelayUntil ( TickType_t *const  pxPreviousWakeTime,
const TickType_t  xTimeIncrement 
)
void vTaskDelete ( TaskHandle_t  xTaskToDelete)
void vTaskEndScheduler ( void  )
void vTaskGetRunTimeStats ( char *  pcWriteBuffer)
void vTaskList ( char *  pcWriteBuffer)
void vTaskMissedYield ( void  )
void vTaskNotifyGiveFromISR ( TaskHandle_t  xTaskToNotify,
BaseType_t pxHigherPriorityTaskWoken 
)
void vTaskPlaceOnEventList ( List_t *const  pxEventList,
const TickType_t  xTicksToWait 
)
void vTaskPlaceOnEventListRestricted ( List_t *const  pxEventList,
const TickType_t  xTicksToWait 
)
void vTaskPlaceOnUnorderedEventList ( List_t pxEventList,
const TickType_t  xItemValue,
const TickType_t  xTicksToWait 
)
void vTaskPriorityInherit ( TaskHandle_t const  pxMutexHolder)
void vTaskPrioritySet ( TaskHandle_t  xTask,
UBaseType_t  uxNewPriority 
)
void vTaskResume ( TaskHandle_t  xTaskToResume)
void vTaskSetTaskNumber ( TaskHandle_t  xTask,
const UBaseType_t  uxHandle 
)
void vTaskSetTimeOutState ( TimeOut_t *const  pxTimeOut)
void vTaskStartScheduler ( void  )
void vTaskStepTick ( const TickType_t  xTicksToJump)
void vTaskSuspend ( TaskHandle_t  xTaskToSuspend)
void vTaskSuspendAll ( void  )
void vTaskSwitchContext ( void  )
BaseType_t xTaskCallApplicationTaskHook ( TaskHandle_t  xTask,
void pvParameter 
)

task.h

BaseType_t xTaskCallApplicationTaskHook( TaskHandle_t xTask, void *pvParameter );

Calls the hook function associated with xTask. Passing xTask as NULL has the effect of calling the Running tasks (the calling task) hook function.

pvParameter is passed to the hook function for the task to interpret as it wants. The return value is the value returned by the task hook function registered by the user.

BaseType_t xTaskCheckForTimeOut ( TimeOut_t *const  pxTimeOut,
TickType_t *const  pxTicksToWait 
)
BaseType_t xTaskGenericCreate ( TaskFunction_t  pxTaskCode,
const char *const  pcName,
const uint16_t  usStackDepth,
void *const  pvParameters,
UBaseType_t  uxPriority,
TaskHandle_t *const  pxCreatedTask,
StackType_t *const  puxStackBuffer,
const MemoryRegion_t *const  xRegions,
const BaseType_t  xCoreID 
)
TaskHandle_t xTaskGetCurrentTaskHandle ( void  )
TaskHandle_t xTaskGetIdleTaskHandle ( void  )

xTaskGetIdleTaskHandle() is only available if INCLUDE_xTaskGetIdleTaskHandle is set to 1 in FreeRTOSConfig.h.

Simply returns the handle of the idle task. It is not valid to call xTaskGetIdleTaskHandle() before the scheduler has been started.

BaseType_t xTaskGetSchedulerState ( void  )
TickType_t xTaskGetTickCount ( void  )
TickType_t xTaskGetTickCountFromISR ( void  )
BaseType_t xTaskIncrementTick ( void  )
BaseType_t xTaskNotify ( TaskHandle_t  xTaskToNotify,
uint32_t  ulValue,
eNotifyAction  eAction 
)
BaseType_t xTaskNotifyFromISR ( TaskHandle_t  xTaskToNotify,
uint32_t  ulValue,
eNotifyAction  eAction,
BaseType_t pxHigherPriorityTaskWoken 
)
BaseType_t xTaskNotifyWait ( uint32_t  ulBitsToClearOnEntry,
uint32_t  ulBitsToClearOnExit,
uint32_t pulNotificationValue,
TickType_t  xTicksToWait 
)
BaseType_t xTaskPriorityDisinherit ( TaskHandle_t const  pxMutexHolder)
BaseType_t xTaskRemoveFromEventList ( const List_t *const  pxEventList)
BaseType_t xTaskRemoveFromUnorderedEventList ( ListItem_t pxEventListItem,
const TickType_t  xItemValue 
)
BaseType_t xTaskResumeAll ( void  )
BaseType_t xTaskResumeFromISR ( TaskHandle_t  xTaskToResume)