Task Utilities

Group that contains task utility macros & functions. More...

Collaboration diagram for Task Utilities:

Macros
#define	tskIDLE_PRIORITY   ( ( UBaseType_t ) 0U )
	Defines the priority used by the idle task. This must not be modified.

Functions
eTaskState	eTaskGetState (TaskHandle_t xTask) PRIVILEGED_FUNCTION
	Obtain the state of any task. States are encoded by the eTaskState enumerated type. More...
void	vTaskGetInfo (TaskHandle_t xTask, TaskStatus_t *pxTaskStatus, BaseType_t xGetFreeStackSpace, eTaskState eState) PRIVILEGED_FUNCTION
	Populates a TaskStatus_t structure with information about a task. More...
void	vTaskPrioritySet (TaskHandle_t xTask, UBaseType_t uxNewPriority) PRIVILEGED_FUNCTION
	Set the priority of any task. More...
TickType_t	xTaskGetTickCount (void) PRIVILEGED_FUNCTION
TickType_t	xTaskGetTickCountFromISR (void) PRIVILEGED_FUNCTION
	This is a version of xTaskGetTickCount() that is safe to be called from an ISR - provided that TickType_t is the natural word size of the microcontroller being used or interrupt nesting is either not supported or not being used. More...
UBaseType_t	uxTaskGetNumberOfTasks (void) PRIVILEGED_FUNCTION
char *	pcTaskGetName (TaskHandle_t xTaskToQuery) PRIVILEGED_FUNCTION
TaskHandle_t	xTaskGetHandle (const char *pcNameToQuery) PRIVILEGED_FUNCTION
UBaseType_t	uxTaskGetStackHighWaterMark (TaskHandle_t xTask) PRIVILEGED_FUNCTION
	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. More...
BaseType_t	xTaskCallApplicationTaskHook (TaskHandle_t xTask, void *pvParameter) PRIVILEGED_FUNCTION
	Calls the hook function associated with xTask. Passing xTask as NULL has the effect of calling the Running tasks (the calling task) hook function. More...
TaskHandle_t	xTaskGetIdleTaskHandle (void) PRIVILEGED_FUNCTION
UBaseType_t	uxTaskGetSystemState (TaskStatus_t *const pxTaskStatusArray, const UBaseType_t uxArraySize, uint32_t *const pulTotalRunTime) PRIVILEGED_FUNCTION
	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. More...
void	vTaskList (char *pcWriteBuffer) PRIVILEGED_FUNCTION
	Lists all the current tasks, along with their current state and stack usage high water mark. More...
void	vTaskGetRunTimeStats (char *pcWriteBuffer) PRIVILEGED_FUNCTION
	Call uxTaskGetSystemState(), then format part of the uxTaskGetSystemState() output into a human readable table that displays the amount of time each task has spent in the Running state in both absolute and percentage terms. More...

Detailed Description

Group that contains task utility macros & functions.

Function Documentation

eTaskGetState()

eTaskState eTaskGetState

(

TaskHandle_t

xTask

)

#include <task.h>

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

Precondition

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

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.

pcTaskGetName()

char* pcTaskGetName

(

TaskHandle_t

xTaskToQuery

)

#include <task.h>

Returns

The text (human readable) name of the task referenced by the handle xTaskToQuery. A task can query its own name by either passing in its own handle, or by setting xTaskToQuery to NULL.

uxTaskGetNumberOfTasks()

UBaseType_t uxTaskGetNumberOfTasks

(

void

)

#include <task.h>

Returns

The number of tasks that the real time kernel is currently managing. This includes all ready, blocked and suspended tasks. A task that has been deleted but not yet freed by the idle task will also be included in the count.

uxTaskGetStackHighWaterMark()

UBaseType_t uxTaskGetStackHighWaterMark

(

TaskHandle_t

xTask

)

#include <task.h>

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.

Precondition

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

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 words, so actual spaces on the stack rather than bytes) since the task referenced by xTask was created.

uxTaskGetSystemState()

UBaseType_t uxTaskGetSystemState	(	TaskStatus_t *const	pxTaskStatusArray,
		const UBaseType_t	uxArraySize,
		uint32_t *const	pulTotalRunTime
	)

#include <task.h>

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.

Precondition

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

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 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.
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 TaskStatus_t 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 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 );
    }
}

vTaskGetInfo()

void vTaskGetInfo	(	TaskHandle_t	xTask,
		TaskStatus_t *	pxTaskStatus,
		BaseType_t	xGetFreeStackSpace,
		eTaskState	eState
	)

#include <task.h>

Populates a TaskStatus_t structure with information about a task.

Precondition

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

Parameters

xTask	Handle of the task being queried. If xTask is NULL then information will be returned about the calling task.
pxTaskStatus	A pointer to the TaskStatus_t structure that will be filled with information about the task referenced by the handle passed using the xTask parameter.
xGetFreeStackSpace	The TaskStatus_t structure contains a member to report the stack high water mark of the task being queried. Calculating the stack high water mark takes a relatively long time, and can make the system temporarily unresponsive - so the xGetFreeStackSpace parameter is provided to allow the high water mark checking to be skipped. The high watermark value will only be written to the TaskStatus_t structure if xGetFreeStackSpace is not set to pdFALSE;
eState	The TaskStatus_t structure contains a member to report the state of the task being queried. Obtaining the task state is not as fast as a simple assignment - so the eState parameter is provided to allow the state information to be omitted from the TaskStatus_t structure. To obtain state information then set eState to eInvalid - otherwise the value passed in eState will be reported as the task state in the TaskStatus_t structure.

Example usage:

void vAFunction( void )
{
   TaskHandle_t xHandle;
   TaskStatus_t xTaskDetails;
 
   // Obtain the handle of a task from its name.
   xHandle = xTaskGetHandle( "Task_Name" );
 
   // Check the handle is not NULL.
   configASSERT( xHandle );
 
   // Use the handle to obtain further information about the task.
   vTaskGetInfo( xHandle,
                 &xTaskDetails,
                 pdTRUE, // Include the high water mark in xTaskDetails.
                 eInvalid ); // Include the task state in xTaskDetails.
}

vTaskGetRunTimeStats()

void vTaskGetRunTimeStats

(

char *

pcWriteBuffer

)

#include <task.h>

Call uxTaskGetSystemState(), then format part of the uxTaskGetSystemState() output into a human readable table that displays the amount of time each task has spent in the Running state in both absolute and percentage terms.

Precondition

configGENERATE_RUN_TIME_STATS and configUSE_STATS_FORMATTING_FUNCTIONS must both be defined as 1 for this function to be available. The application must also then provide definitions for portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() and portGET_RUN_TIME_COUNTER_VALUE() to configure a peripheral timer/counter and return the timers current count value respectively. The counter should be at least 10 times the frequency of the tick count.

Note

This function will disable interrupts for its duration. It is not intended for normal application runtime use but as a debug aid.

Setting configGENERATE_RUN_TIME_STATS to 1 will result in a total accumulated execution time being stored for each task. The resolution of the accumulated time value depends on the frequency of the timer configured by the portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() macro. Calling vTaskGetRunTimeStats() writes the total execution time of each task into a buffer, both as an absolute count value and as a percentage of the total system execution time.

Note

This function is provided for convenience only, and is used by many of the demo applications. Do not consider it to be part of the scheduler.

vTaskGetRunTimeStats() has a dependency on the sprintf() C library function that might bloat the code size, use a lot of stack, and provide different results on different platforms. An alternative, tiny, third party, and limited functionality implementation of sprintf() is provided in many of the FreeRTOS/Demo sub-directories in a file called printf-stdarg.c (note printf-stdarg.c does not provide a full snprintf() implementation!).

It is recommended that production systems call uxTaskGetSystemState() directly to get access to raw stats data, rather than indirectly through a call to vTaskGetRunTimeStats().

Parameters

pcWriteBuffer

A buffer into which the execution times will be written, in ASCII form. This buffer is assumed to be large enough to contain the generated report. Approximately 40 bytes per task should be sufficient.

vTaskList()

void vTaskList

(

char *

pcWriteBuffer

)

#include <task.h>

Lists all the current tasks, along with their current state and stack usage high water mark.

Precondition

configUSE_TRACE_FACILITY and configUSE_STATS_FORMATTING_FUNCTIONS must both be defined as 1 for this function to be available. See the configuration section of the FreeRTOS.org website for more information.

Note

This function will disable interrupts for its duration. It is not intended for normal application runtime use but as a debug aid.

Tasks are reported as blocked ('B'), ready ('R'), deleted ('D') or suspended ('S').

Note

This function is provided for convenience only, and is used by many of the demo applications. Do not consider it to be part of the scheduler.

vTaskList() calls uxTaskGetSystemState(), then formats part of the uxTaskGetSystemState() output into a human readable table that displays task names, states and stack usage.

vTaskList() has a dependency on the sprintf() C library function that might bloat the code size, use a lot of stack, and provide different results on different platforms. An alternative, tiny, third party, and limited functionality implementation of sprintf() is provided in many of the FreeRTOS/Demo sub-directories in a file called printf-stdarg.c (note printf-stdarg.c does not provide a full snprintf() implementation!).

It is recommended that production systems call uxTaskGetSystemState() directly to get access to raw stats data, rather than indirectly through a call to vTaskList().

Parameters

pcWriteBuffer

A buffer into which the above mentioned details will be written, in ASCII form. This buffer is assumed to be large enough to contain the generated report. Approximately 40 bytes per task should be sufficient.

vTaskPrioritySet()

void vTaskPrioritySet	(	TaskHandle_t	xTask,
		UBaseType_t	uxNewPriority
	)

#include <task.h>

Set the priority of any task.

Precondition

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

A context switch will occur before the function returns if the priority being set is higher than the currently executing task.

Parameters

xTask	Handle to the task for which the priority is being set. Passing a NULL handle results in the priority of the calling task being set.
uxNewPriority	The priority to which the task will be set.

Example usage:

void vAFunction( void )
{
TaskHandle_t xHandle;
 
    // Create a task, storing the handle.
    xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
 
    // ...
 
    // Use the handle to raise the priority of the created task.
    vTaskPrioritySet( xHandle, tskIDLE_PRIORITY + 1 );
 
    // ...
 
    // Use a NULL handle to raise our priority to the same value.
    vTaskPrioritySet( NULL, tskIDLE_PRIORITY + 1 );
}

xTaskCallApplicationTaskHook()

BaseType_t xTaskCallApplicationTaskHook	(	TaskHandle_t	xTask,
		void *	pvParameter
	)

#include <task.h>

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.

xTaskGetHandle()

TaskHandle_t xTaskGetHandle

(

const char *

pcNameToQuery

)

#include <task.h>

Precondition

INCLUDE_xTaskGetHandle must be set to 1 in FreeRTOSConfig.h for pcTaskGetHandle() to be available.

Note

This function takes a relatively long time to complete and should be used sparingly.

Returns

The handle of the task that has the human readable name pcNameToQuery. NULL is returned if no matching name is found.

xTaskGetIdleTaskHandle()

TaskHandle_t xTaskGetIdleTaskHandle

(

void

)

#include <task.h>

Precondition

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

Returns

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

xTaskGetTickCount()

TickType_t xTaskGetTickCount

(

void

)

#include <task.h>

Returns

The count of ticks since vTaskStartScheduler() was called.

xTaskGetTickCountFromISR()

TickType_t xTaskGetTickCountFromISR

(

void

)

#include <task.h>

This is a version of xTaskGetTickCount() that is safe to be called from an ISR - provided that TickType_t is the natural word size of the microcontroller being used or interrupt nesting is either not supported or not being used.

Returns

The count of ticks since vTaskStartScheduler() was called.