freertos-7.5.2/Source/include/task.h File Reference

#include "list.h"

Data Structures
struct	xMEMORY_REGION
struct	xTASK_PARAMTERS
struct	xTASK_STATUS
struct	xTIME_OUT

Macros
#define	taskDISABLE_INTERRUPTS()   portDISABLE_INTERRUPTS()
#define	taskENABLE_INTERRUPTS()   portENABLE_INTERRUPTS()
#define	taskENTER_CRITICAL()   portENTER_CRITICAL()
#define	taskEXIT_CRITICAL()   portEXIT_CRITICAL()
#define	taskSCHEDULER_NOT_STARTED   ( ( portBASE_TYPE ) 0 )
#define	taskSCHEDULER_RUNNING   ( ( portBASE_TYPE ) 1 )
#define	taskSCHEDULER_SUSPENDED   ( ( portBASE_TYPE ) 2 )
#define	taskYIELD()   portYIELD()
#define	tskIDLE_PRIORITY   ( ( unsigned portBASE_TYPE ) 0U )
#define	tskKERNEL_VERSION_NUMBER   "V7.5.2"
#define	xTaskCreate(pvTaskCode, pcName, usStackDepth, pvParameters, uxPriority, pxCreatedTask)   xTaskGenericCreate( ( pvTaskCode ), ( pcName ), ( usStackDepth ), ( pvParameters ), ( uxPriority ), ( pxCreatedTask ), ( NULL ), ( NULL ) )
#define	xTaskCreateRestricted(x, pxCreatedTask)   xTaskGenericCreate( ((x)->pvTaskCode), ((x)->pcName), ((x)->usStackDepth), ((x)->pvParameters), ((x)->uxPriority), (pxCreatedTask), ((x)->puxStackBuffer), ((x)->xRegions) )

Typedefs
typedef struct xMEMORY_REGION	xMemoryRegion
typedef void *	xTaskHandle
typedef struct xTASK_PARAMTERS	xTaskParameters
typedef struct xTASK_STATUS	xTaskStatusType
typedef struct xTIME_OUT	xTimeOutType

Enumerations
enum	eSleepModeStatus {   eAbortSleep = 0,   eStandardSleep,   eNoTasksWaitingTimeout,   eAbortSleep = 0,   eStandardSleep,   eNoTasksWaitingTimeout,   eAbortSleep = 0,   eStandardSleep,   eNoTasksWaitingTimeout,   eAbortSleep = 0,   eStandardSleep,   eNoTasksWaitingTimeout,   eAbortSleep = 0,   eStandardSleep,   eNoTasksWaitingTimeout }
enum	eTaskState {   eRunning = 0,   eReady,   eBlocked,   eSuspended,   eDeleted,   eRunning = 0,   eReady,   eBlocked,   eSuspended,   eDeleted,   eRunning = 0,   eReady,   eBlocked,   eSuspended,   eDeleted,   eRunning = 0,   eReady,   eBlocked,   eSuspended,   eDeleted,   eRunning = 0,   eReady,   eBlocked,   eSuspended,   eDeleted,   eInvalid,   eRunning = 0,   eReady,   eBlocked,   eSuspended,   eDeleted }

Functions
eSleepModeStatus	eTaskConfirmSleepModeStatus (void)
eTaskState	eTaskGetState (xTaskHandle xTask) PRIVILEGED_FUNCTION
	task. More...
signed char *	pcTaskGetTaskName (xTaskHandle xTaskToQuery)
unsigned portBASE_TYPE	uxTaskGetNumberOfTasks (void) PRIVILEGED_FUNCTION
unsigned portBASE_TYPE	uxTaskGetStackHighWaterMark (xTaskHandle xTask) PRIVILEGED_FUNCTION
	task.h More...
unsigned portBASE_TYPE	uxTaskGetSystemState (xTaskStatusType *pxTaskStatusArray, unsigned portBASE_TYPE uxArraySize, unsigned long *pulTotalRunTime)
	configUSE_TRACE_FACILITY must bet defined as 1 in FreeRTOSConfig.h for uxTaskGetSystemState() to be available. More...
unsigned portBASE_TYPE	uxTaskGetTaskNumber (xTaskHandle xTask)
unsigned portBASE_TYPE	uxTaskPriorityGet (xTaskHandle xTask) PRIVILEGED_FUNCTION
void	vTaskAllocateMPURegions (xTaskHandle xTask, const xMemoryRegion *const pxRegions) PRIVILEGED_FUNCTION
void	vTaskDelay (portTickType xTicksToDelay) PRIVILEGED_FUNCTION
void	vTaskDelayUntil (portTickType *const pxPreviousWakeTime, portTickType xTimeIncrement) PRIVILEGED_FUNCTION
void	vTaskDelete (xTaskHandle xTaskToDelete) PRIVILEGED_FUNCTION
void	vTaskEndScheduler (void) PRIVILEGED_FUNCTION
void	vTaskGetRunTimeStats (signed char *pcWriteBuffer) PRIVILEGED_FUNCTION
void	vTaskList (signed char *pcWriteBuffer) PRIVILEGED_FUNCTION
void	vTaskMissedYield (void) PRIVILEGED_FUNCTION
void	vTaskPlaceOnEventList (xList *const pxEventList, portTickType xTicksToWait) PRIVILEGED_FUNCTION
void	vTaskPlaceOnEventListRestricted (xList *const pxEventList, portTickType xTicksToWait) PRIVILEGED_FUNCTION
void	vTaskPriorityDisinherit (xTaskHandle const pxMutexHolder) PRIVILEGED_FUNCTION
void	vTaskPriorityInherit (xTaskHandle const pxMutexHolder) PRIVILEGED_FUNCTION
void	vTaskPrioritySet (xTaskHandle xTask, unsigned portBASE_TYPE uxNewPriority) PRIVILEGED_FUNCTION
void	vTaskResume (xTaskHandle xTaskToResume) PRIVILEGED_FUNCTION
void	vTaskSetTaskNumber (xTaskHandle xTask, unsigned portBASE_TYPE uxHandle)
void	vTaskSetTimeOutState (xTimeOutType *const pxTimeOut) PRIVILEGED_FUNCTION
void	vTaskStartScheduler (void) PRIVILEGED_FUNCTION
void	vTaskStepTick (portTickType xTicksToJump)
void	vTaskSuspend (xTaskHandle xTaskToSuspend) PRIVILEGED_FUNCTION
void	vTaskSuspendAll (void) PRIVILEGED_FUNCTION
void	vTaskSwitchContext (void) PRIVILEGED_FUNCTION
portBASE_TYPE	xTaskCallApplicationTaskHook (xTaskHandle xTask, void *pvParameter) PRIVILEGED_FUNCTION
	task.h More...
portBASE_TYPE	xTaskCheckForTimeOut (xTimeOutType *const pxTimeOut, portTickType *const pxTicksToWait) PRIVILEGED_FUNCTION
signed portBASE_TYPE	xTaskGenericCreate (pdTASK_CODE pxTaskCode, const signed char *const pcName, unsigned short usStackDepth, void *pvParameters, unsigned portBASE_TYPE uxPriority, xTaskHandle *pxCreatedTask, portSTACK_TYPE *puxStackBuffer, const xMemoryRegion *const xRegions) PRIVILEGED_FUNCTION
xTaskHandle	xTaskGetCurrentTaskHandle (void) PRIVILEGED_FUNCTION
xTaskHandle	xTaskGetIdleTaskHandle (void)
	xTaskGetIdleTaskHandle() is only available if INCLUDE_xTaskGetIdleTaskHandle is set to 1 in FreeRTOSConfig.h. More...
portBASE_TYPE	xTaskGetSchedulerState (void) PRIVILEGED_FUNCTION
portTickType	xTaskGetTickCount (void) PRIVILEGED_FUNCTION
portTickType	xTaskGetTickCountFromISR (void) PRIVILEGED_FUNCTION
portBASE_TYPE	xTaskIncrementTick (void) PRIVILEGED_FUNCTION
signed portBASE_TYPE	xTaskIsTaskSuspended (xTaskHandle xTask) PRIVILEGED_FUNCTION
	task. More...
signed portBASE_TYPE	xTaskRemoveFromEventList (const xList *const pxEventList) PRIVILEGED_FUNCTION
signed portBASE_TYPE	xTaskResumeAll (void) PRIVILEGED_FUNCTION
portBASE_TYPE	xTaskResumeFromISR (xTaskHandle xTaskToResume) PRIVILEGED_FUNCTION

#define taskDISABLE_INTERRUPTS

(

)

portDISABLE_INTERRUPTS()

#define taskENABLE_INTERRUPTS

(

)

portENABLE_INTERRUPTS()

#define taskENTER_CRITICAL

(

)

portENTER_CRITICAL()

Referenced by FreeRTOS_CLIRegisterCommand(), prvAddNewTaskToReadyList(), prvCheckTasksWaitingTermination(), prvInitialiseTaskLists(), prvIsQueueEmpty(), prvIsQueueFull(), prvUnlockQueue(), uxQueueMessagesWaiting(), uxQueueSpacesAvailable(), vTaskSetTimeOutState(), xEventGroupClearBits(), xEventGroupSync(), xEventGroupWaitBits(), xQueueGenericReceive(), xQueueGenericReset(), xQueueGenericSend(), xQueuePeek(), xQueueReceive(), xQueueSemaphoreTake(), xStreamBufferReceive(), xStreamBufferSend(), xTaskCheckForTimeOut(), xTaskGetTickCount(), and xTaskResumeAll().

#define taskEXIT_CRITICAL

(

)

portEXIT_CRITICAL()

Referenced by FreeRTOS_CLIRegisterCommand(), prvAddNewTaskToReadyList(), prvCheckTasksWaitingTermination(), prvInitialiseTaskLists(), prvIsQueueEmpty(), prvIsQueueFull(), prvUnlockQueue(), uxQueueMessagesWaiting(), uxQueueSpacesAvailable(), vTaskSetTimeOutState(), xEventGroupClearBits(), xEventGroupSync(), xEventGroupWaitBits(), xQueueGenericReceive(), xQueueGenericReset(), xQueueGenericSend(), xQueuePeek(), xQueueReceive(), xQueueSemaphoreTake(), xStreamBufferReceive(), xStreamBufferSend(), xTaskCheckForTimeOut(), xTaskGetTickCount(), and xTaskResumeAll().

#define taskSCHEDULER_NOT_STARTED   ( ( portBASE_TYPE ) 0 )

#define taskSCHEDULER_RUNNING   ( ( portBASE_TYPE ) 1 )

#define taskSCHEDULER_SUSPENDED   ( ( portBASE_TYPE ) 2 )

Referenced by xEventGroupSync(), xEventGroupWaitBits(), xQueueGenericReceive(), xQueueGenericSend(), xQueuePeek(), xQueueReceive(), and xQueueSemaphoreTake().

#define taskYIELD

(

)

portYIELD()

Referenced by portTASK_FUNCTION().

#define tskIDLE_PRIORITY   ( ( unsigned portBASE_TYPE ) 0U )

Referenced by vTaskStartScheduler().

#define tskKERNEL_VERSION_NUMBER   "V7.5.2"

#define xTaskCreate	(		pvTaskCode,
			pcName,
			usStackDepth,
			pvParameters,
			uxPriority,
			pxCreatedTask
	)		xTaskGenericCreate( ( pvTaskCode ), ( pcName ), ( usStackDepth ), ( pvParameters ), ( uxPriority ), ( pxCreatedTask ), ( NULL ), ( NULL ) )

Referenced by vTaskStartScheduler().

#define xTaskCreateRestricted	(		x,
			pxCreatedTask
	)		xTaskGenericCreate( ((x)->pvTaskCode), ((x)->pcName), ((x)->usStackDepth), ((x)->pvParameters), ((x)->uxPriority), (pxCreatedTask), ((x)->puxStackBuffer), ((x)->xRegions) )

typedef struct xMEMORY_REGION xMemoryRegion

typedef void* xTaskHandle

typedef struct xTASK_PARAMTERS xTaskParameters

typedef struct xTASK_STATUS xTaskStatusType

typedef struct xTIME_OUT xTimeOutType

enum eSleepModeStatus

Enumerator
eAbortSleep
eStandardSleep
eNoTasksWaitingTimeout
eAbortSleep
eStandardSleep
eNoTasksWaitingTimeout
eAbortSleep
eStandardSleep
eNoTasksWaitingTimeout
eAbortSleep
eStandardSleep
eNoTasksWaitingTimeout
eAbortSleep
eStandardSleep
eNoTasksWaitingTimeout

enum eTaskState

Enumerator
eRunning
eReady
eBlocked
eSuspended
eDeleted
eRunning
eReady
eBlocked
eSuspended
eDeleted
eRunning
eReady
eBlocked
eSuspended
eDeleted
eRunning
eReady
eBlocked
eSuspended
eDeleted
eRunning
eReady
eBlocked
eSuspended
eDeleted
eInvalid
eRunning
eReady
eBlocked
eSuspended
eDeleted

eSleepModeStatus eTaskConfirmSleepModeStatus

(

void

)

eTaskState eTaskGetState

(

xTaskHandle

xTask

)

task.

h

eTaskState eTaskGetState( xTaskHandle 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

xTask

Handle 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.

signed char* pcTaskGetTaskName

(

xTaskHandle

xTaskToQuery

)

unsigned portBASE_TYPE uxTaskGetNumberOfTasks

(

void

)

unsigned portBASE_TYPE uxTaskGetStackHighWaterMark

(

xTaskHandle

xTask

)

task.h

unsigned portBASE_TYPE uxTaskGetStackHighWaterMark( xTaskHandle 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

xTask

Handle 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 bytes) since the task referenced by xTask was created.

unsigned portBASE_TYPE uxTaskGetSystemState	(	xTaskStatusType *	pxTaskStatusArray,
		unsigned portBASE_TYPE	uxArraySize,
		unsigned long *	pulTotalRunTime
	)

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

uxTaskGetSystemState() populates an xTaskStatusType structure for each task in the system. xTaskStatusType 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 xTaskStatusType 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

pxTaskStatusArray	A pointer to an array of xTaskStatusType structures. The array must contain at least one xTaskStatusType 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.
uxArraySize	The 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 xTaskStatusType structures contained in the array, not by the number of bytes in the array.
pulTotalRunTime	If 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 xTaskStatusType 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( signed char *pcWriteBuffer )
    {
    xTaskStatusType *pxTaskStatusArray;
    volatile unsigned portBASE_TYPE uxArraySize, x;
    unsigned long 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 = uxCurrentNumberOfTasks();

Allocate a xTaskStatusType structure for each task.  An array could be
allocated statically at compile time.
        pxTaskStatusArray = pvPortMalloc( uxCurrentNumberOfTasks * sizeof( xTaskStatusType ) );

        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( ( char * ) pcWriteBuffer, ( char * ) "%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( ( char * ) pcWriteBuffer, ( char * ) "%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 );
        }
    }
    

unsigned portBASE_TYPE uxTaskGetTaskNumber

(

xTaskHandle

xTask

)

unsigned portBASE_TYPE uxTaskPriorityGet

(

xTaskHandle

xTask

)

void vTaskAllocateMPURegions	(	xTaskHandle	xTask,
		const xMemoryRegion *const	pxRegions
	)

void vTaskDelay

(

portTickType

xTicksToDelay

)

void vTaskDelayUntil	(	portTickType *const	pxPreviousWakeTime,
		portTickType	xTimeIncrement
	)

void vTaskDelete

(

xTaskHandle

xTaskToDelete

)

void vTaskEndScheduler

(

void

)

void vTaskGetRunTimeStats

(

signed char *

pcWriteBuffer

)

void vTaskList

(

signed char *

pcWriteBuffer

)

void vTaskMissedYield

(

void

)

void vTaskPlaceOnEventList	(	xList *const	pxEventList,
		portTickType	xTicksToWait
	)

References configASSERT, portRESET_READY_PRIORITY, portTickType, prvAddCurrentTaskToDelayedList(), pxCurrentTCB, uxListRemove(), tskTaskControlBlock::uxPriority, uxTopReadyPriority, vListInsert(), vListInsertEnd(), tskTaskControlBlock::xEventListItem, tskTaskControlBlock::xGenericListItem, and xTickCount.

Referenced by xQueueGenericReceive(), xQueueGenericSend(), xQueuePeek(), xQueueReceive(), and xQueueSemaphoreTake().

void vTaskPlaceOnEventListRestricted	(	xList *const	pxEventList,
		portTickType	xTicksToWait
	)

void vTaskPriorityDisinherit

(

xTaskHandle const

pxMutexHolder

)

Referenced by prvCopyDataToQueue().

void vTaskPriorityInherit

(

xTaskHandle const

pxMutexHolder

)

Referenced by xQueueGenericReceive().

void vTaskPrioritySet	(	xTaskHandle	xTask,
		unsigned portBASE_TYPE	uxNewPriority
	)

void vTaskResume

(

xTaskHandle

xTaskToResume

)

void vTaskSetTaskNumber	(	xTaskHandle	xTask,
		unsigned portBASE_TYPE	uxHandle
	)

void vTaskSetTimeOutState

(

xTimeOutType *const

pxTimeOut

)

void vTaskStartScheduler

(

void

)

void vTaskStepTick

(

portTickType

xTicksToJump

)

void vTaskSuspend

(

xTaskHandle

xTaskToSuspend

)

void vTaskSuspendAll

(

void

)

void vTaskSwitchContext

(

void

)

portBASE_TYPE xTaskCallApplicationTaskHook	(	xTaskHandle	xTask,
		void *	pvParameter
	)

task.h

portBASE_TYPE xTaskCallApplicationTaskHook( xTaskHandle xTask, pdTASK_HOOK_CODE pxHookFunction );

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.

portBASE_TYPE xTaskCheckForTimeOut	(	xTimeOutType *const	pxTimeOut,
		portTickType *const	pxTicksToWait
	)

signed portBASE_TYPE xTaskGenericCreate	(	pdTASK_CODE	pxTaskCode,
		const signed char *const	pcName,
		unsigned short	usStackDepth,
		void *	pvParameters,
		unsigned portBASE_TYPE	uxPriority,
		xTaskHandle *	pxCreatedTask,
		portSTACK_TYPE *	puxStackBuffer,
		const xMemoryRegion *const	xRegions
	)

xTaskHandle xTaskGetCurrentTaskHandle

(

void

)

Referenced by xQueueGenericReceive(), xStreamBufferReceive(), and xStreamBufferSend().

xTaskHandle 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.

portBASE_TYPE xTaskGetSchedulerState

(

void

)

Referenced by xEventGroupSync(), xEventGroupWaitBits(), xQueueGenericReceive(), xQueueGenericSend(), xQueuePeek(), xQueueReceive(), and xQueueSemaphoreTake().

portTickType xTaskGetTickCount

(

void

)

portTickType xTaskGetTickCountFromISR

(

void

)

portBASE_TYPE xTaskIncrementTick

(

void

)

signed portBASE_TYPE xTaskIsTaskSuspended

(

xTaskHandle

xTask

)

task.

h

signed portBASE_TYPE xTaskIsTaskSuspended( const xTaskHandle xTask );

Utility task that simply returns pdTRUE if the task referenced by xTask is currently in the Suspended state, or pdFALSE if the task referenced by xTask is in any other state.

signed portBASE_TYPE xTaskRemoveFromEventList

(

const xList *const

pxEventList

)

signed portBASE_TYPE xTaskResumeAll

(

void

)

portBASE_TYPE xTaskResumeFromISR

(

xTaskHandle

xTaskToResume

)