Table 54. Macros used in the collection of run-time statistics
Macro Description
portGET_RUN_TIME_COUNTER_VALUE(), or portALT_GET_RUN_TIME_COUNTER_VALUE(Time)
One of these two macros must be provided to return the current runtime statistics clock value. This is the total time the application has been running, in run-time statistics clock units, since the application first booted.
If the first macro is used it must be defined to evaluate to the current clock value. If the second macro is used it must be defined to set its
‘Time’ parameter to the current clock value.
The uxTaskGetSystemState() API Function
uxTaskGetSystemState() provides a snapshot of status information for each task under the control of the FreeRTOS scheduler. The information is provided as an array of TaskStatus_t
structures, with one index in the array for each task. TaskStatus_t is described by Listing 167 and Table 56.
UBaseType_t uxTaskGetSystemState( TaskStatus_t * const pxTaskStatusArray,
const UBaseType_t uxArraySize,
uint32_t * const pulTotalRunTime );
Listing 166. The uxTaskGetSystemState() API function prototype
339
161204 Pre-release for FreeRTOS V8.x.x. See http://www.FreeRTOS.org/FreeRTOS-V9.html
for information about FreeRTOS
V9.x.x. Use http://www.FreeRTOS.org/contact to provide feedback, corrections, and check for updates.
Table 55, uxTaskGetSystemState() parameters and return value
Parameter Name Description
pxTaskStatusArray A pointer to an array of TaskStatus_t structures.
The array must contain at least one TaskStatus_t structure for each task. The number of tasks can be determined using the uxTaskGetNumberOfTasks() API function. uxArraySize
The TaskStatus_t structure is shown in Listing 167, and the
TaskStatus_t structure members are described in Table 56.
The size of the array pointed to by the pxTaskStatusArray parameter.
The size is specified as the number of indexes in the array (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 runtime statistics clock provided by the application) since the target booted.
Returned value pulTotalRunTime is optional, and can be set to NULL if the total run time is not required.
The number of TaskStatus_t structures that were populated by uxTaskGetSystemState() is returned.
The returned value 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.
340
typedef struct xTASK_STATUS
{
TaskHandle_t xHandle;
const char *pcTaskName;
UBaseType_t xTaskNumber;
eTaskState eCurrentState;
UBaseType_t uxCurrentPriority;
UBaseType_t uxBasePriority;
uint32_t ulRunTimeCounter;
uint16_t usStackHighWaterMark;
} TaskStatus_t;
Listing 167. The TaskStatus_t structure
Parameter Name/
Returned Value
xHandle
Table 56. TaskStatus_t structure members
Description
pcTaskName xTaskNumber eCurrentState
The handle of the task to which the information in the structure relates.
The human readable text name of the task.
Each task has a unique xTaskNumber value.
If an application creates and deletes tasks at run time then it is possible that a task will have the same handle as a task that was previously deleted. xTaskNumber is provided to allow application code, and kernel aware debuggers, to distinguish between a task that is still valid, and a deleted task that had the same handle as the valid task.
An enumerated type that holds the state of the task. eCurrentState can be one of the following values: eRunning, eReady, eBlocked, eSuspended, eDeleted.
A task will only be reported as being in the eDeleted state for the short period between the time the task was deleted by a call to vTaskDelete(), and the time the Idle task frees the memory that was allocated to the deleted task’s internal data structures and stack. After that time, the task will no longer exist in any way, and it is invalid to attempt to use its handle.
341
