KernelTask utilities

Updated Jun 2025

uxTaskGetSystemState()

[Task Utilities]

task.h

1UBaseType_t uxTaskGetSystemState(
2                       TaskStatus_t * const pxTaskStatusArray,
3                       const UBaseType_t uxArraySize,
4                       unsigned long * const pulTotalRunTime );

Copy

configUSE_TRACE_FACILITY

Copy

uxTaskGetSystemState()

Copy

uxTaskGetSystemState()

Copy

TaskStatus_t

Copy

See vTaskGetInfo() for a version that populates a

TaskStatus_t

Copy

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

  Copy
  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

  Copy
  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

  Copy
  is set to 1 in FreeRTOSConfig.h then

  *pulTotalRunTime

  Copy
  is set by

  uxTaskGetSystemState()

  Copy
  to the total run time (as defined by the run time stats clock) since the target booted.

  pulTotalRunTime

  Copy
  can be set to NULL to omit the total run time value.

Returns:

• The number of TaskStatus_t structures that were populated by

  uxTaskGetSystemState()

  Copy
  . This should equal the number returned by the

  uxTaskGetNumberOfTasks()

  Copy
  API function, but will be zero if the value passed in the

  uxArraySize

  Copy
  parameter was too small.

Example usage:

1/* This example demonstrates how a human readable table of run time stats
2   information is generated from raw data provided by uxTaskGetSystemState().
3   The human readable table is written to pcWriteBuffer. (see the vTaskList()
4   API function which actually does just this). */
5void vTaskGetRunTimeStats( char *pcWriteBuffer )
6{
7    TaskStatus_t *pxTaskStatusArray;
8    volatile UBaseType_t uxArraySize, x;
9    unsigned long ulTotalRunTime, ulStatsAsPercentage;
10
11   /* Make sure the write buffer does not contain a string. */
12   *pcWriteBuffer = 0x00;
13
14   /* Take a snapshot of the number of tasks in case it changes while this
15      function is executing. */
16   uxArraySize = uxTaskGetNumberOfTasks();
17
18   /* Allocate a TaskStatus_t structure for each task. An array could be
19      allocated statically at compile time. */
20   pxTaskStatusArray = pvPortMalloc( uxArraySize * sizeof( TaskStatus_t ) );
21
22   if( pxTaskStatusArray != NULL )
23   {
24      /* Generate raw status information about each task. */
25      uxArraySize = uxTaskGetSystemState( pxTaskStatusArray,
26                                 uxArraySize,
27                                 &ulTotalRunTime );
28
29      /* For percentage calculations. */
30      ulTotalRunTime /= 100UL;
31
32      /* Avoid divide by zero errors. */
33      if( ulTotalRunTime > 0 )
34      {
35         /* For each populated position in the pxTaskStatusArray array,
36            format the raw data as human readable ASCII data. */
37         for( x = 0; x < uxArraySize; x++ )
38         {
39            /* What percentage of the total run time has the task used?
40               This will always be rounded down to the nearest integer.
41               ulTotalRunTimeDiv100 has already been divided by 100. */
42            ulStatsAsPercentage =
43                  pxTaskStatusArray[ x ].ulRunTimeCounter / ulTotalRunTime;
44
45            if( ulStatsAsPercentage > 0UL )
46            {
47               sprintf( pcWriteBuffer, "%stt%lutt%lu%%rn",
48                                 pxTaskStatusArray[ x ].pcTaskName,
49                                 pxTaskStatusArray[ x ].ulRunTimeCounter,
50                                 ulStatsAsPercentage );
51            }
52            else
53            {
54               /* If the percentage is zero here then the task has
55                  consumed less than 1% of the total run time. */
56               sprintf( pcWriteBuffer, "%stt%lutt<1%%rn",
57                                 pxTaskStatusArray[ x ].pcTaskName,
58                                 pxTaskStatusArray[ x ].ulRunTimeCounter );
59            }
60
61            pcWriteBuffer += strlen( ( char * ) pcWriteBuffer );
62         }
63      }
64
65      /* The array is no longer needed, free the memory it consumes. */
66      vPortFree( pxTaskStatusArray );
67   }
68}

Copy

The TaskStatus_t definition

1typedef struct xTASK_STATUS
2{
3   /* The handle of the task to which the rest of the information in the
4      structure relates. */
5   TaskHandle_t xHandle;
6
7   /* A pointer to the task's name. This value will be invalid if the task was
8      deleted since the structure was populated! */
9   const char *pcTaskName;
10
11   /* A number unique to the task. */
12   UBaseType_t xTaskNumber;
13
14   /* The state in which the task existed when the structure was populated. */
15   eTaskState eCurrentState;
16
17   /* The priority at which the task was running (may be inherited) when the
18      structure was populated. */
19   UBaseType_t uxCurrentPriority;
20
21   /* The priority to which the task will return if the task's current priority
22      has been inherited to avoid unbounded priority inversion when obtaining a
23      mutex. Only valid if configUSE_MUTEXES is defined as 1 in
24      FreeRTOSConfig.h. */
25   UBaseType_t uxBasePriority;
26
27   /* The total run time allocated to the task so far, as defined by the run time stats clock. 
28      Only valid when configGENERATE_RUN_TIME_STATS is defined as 1 in FreeRTOSConfig.h. */
29   unsigned long ulRunTimeCounter;
30
31   /* Points to the lowest address of the task's stack area. */
32   StackType_t *pxStackBase;
33
34   #if ( configRECORD_STACK_HIGH_ADDRESS == 1 )
35       /* Points to the top address of the task's stack area. */
36       StackType_t * pxTopOfStack;
37
38       /* Points to the bottom address of the task's stack area. */
39       StackType_t * pxEndOfStack;
40   #endif
41
42   /* The minimum amount of stack space that has remained for the task since
43      the task was created. The closer this value is to zero the closer the task
44      has come to overflowing its stack. */
45   configSTACK_DEPTH_TYPE usStackHighWaterMark;
46} TaskStatus_t;

Copy