Task Utilities

xTaskGetTickCount

task. h

 portTickType xTaskGetTickCount( void ); 

Returns:

The count of ticks since vTaskStartScheduler was called.

xTaskGetTickCountFromISR

task. h

 portTickType xTaskGetTickCountFromISR( void ); 

Returns:

The count of ticks since vTaskStartScheduler was called.

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

uxTaskGetNumberOfTasks

task. h

 unsigned short uxTaskGetNumberOfTasks( void ); 

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.

vTaskList

task. h

 void vTaskList( char *pcWriteBuffer ); 

configUSE_TRACE_FACILITY must be defined as 1 for this function to be available. See the configuration section 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.

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

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

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.

vTaskGetRunTimeStats

task. h

 void vTaskGetRunTimeStats( char *pcWriteBuffer ); 

configGENERATE_RUN_TIME_STATS must 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.

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.

vTaskStartTrace

task. h

 void vTaskStartTrace( char * pcBuffer, unsigned portBASE_TYPE uxBufferSize ); 

Starts a real time kernel activity trace. The trace logs the identity of which task is running when.

The trace file is stored in binary format. A separate DOS utility called convtrce.exe is used to convert this into a tab delimited text file which can be viewed and plotted in a spread sheet.

Parameters:

pcBuffer	The buffer into which the trace will be written.
ulBufferSize	The size of pcBuffer in bytes. The trace will continue until either the buffer in full, or ulTaskEndTrace () is called.

usTaskEndTrace

task. h

 unsigned long ulTaskEndTrace( void ); 

Stops a kernel activity trace. See vTaskStartTrace ().

Returns:

The number of bytes that have been written into the trace buffer.

uxTaskGetStackHighWaterMark

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.

xTaskCallApplicationTaskHook

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.