KernelTask utilities

Updated Mar 2025

vTaskGetInfo()

[Task Utilities]

task.h

1void vTaskGetInfo( TaskHandle_t xTask,
2                   TaskStatus_t *pxTaskStatus,
3                   BaseType_t xGetFreeStackSpace,
4                   eTaskState eState );

Copy

configUSE_TRACE_FACILITY

Copy

vTaskGetInfo()

Copy

Whereas uxTaskGetSystemState() populates a TaskStatus_t structure for each task in the system,

vTaskGetInfo()

Copy

TaskStatus_t

Copy

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:

• xTask

  The handle of the task being queried. Setting xTask to NULL will return information on the calling task.

• pxTaskStatus

  The

  TaskStatus_t

  Copy
  structure pointed to by

  pxTaskStatus

  Copy
  will be filled with information about the task referenced by the handle passed in the

  xTask

  Copy
  parameter.

• xGetFreeStackSpace

  The

  TaskStatus_t

  Copy
  structure contains a member to report the stack high water mark of the task being queried. The stack high water mark is the minimum amount of stack space that has ever existed, so the closer the number is to zero the closer the task has come to overflowing its stack. Calculating the stack high water mark takes a relatively long time, and can make the system temporarily unresponsive - so the

  xGetFreeStackSpace

  Copy
  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

  Copy
  structure if

  xGetFreeStackSpace

  Copy
  is not set to

  pdFALSE

  Copy
  .

• eState

  The

  TaskStatus_t

  Copy
  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

  Copy
  parameter is provided to allow the state information to be omitted from the

  TaskStatus_t

  Copy
  structure. To obtain state information then set eState to

  eInvalid

  Copy
  - otherwise the value passed in

  eState

  Copy
  will be reported as the task state in the

  TaskStatus_t

  Copy
  structure.

Example usage:

1void vAFunction( void )
2{
3    TaskHandle_t xHandle;
4    TaskStatus_t xTaskDetails;
5
6    /* Obtain the handle of a task from its name. */
7    xHandle = xTaskGetHandle( "Task_Name" );
8
9    /* Check the handle is not NULL. */
10    configASSERT( xHandle );
11
12    /* Use the handle to obtain further information about the task. */
13    vTaskGetInfo( /* The handle of the task being queried. */
14                  xHandle,
15                  /* The TaskStatus_t structure to complete with information
16                     on xTask. */
17                  &xTaskDetails,
18                  /* Include the stack high water mark value in the
19                     TaskStatus_t structure. */
20                  pdTRUE,
21                  /* Include the task state in the TaskStatus_t structure. */
22                  eInvalid );
23}

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
28       time stats clock. Only valid when configGENERATE_RUN_TIME_STATS is
29       defined as 1 in FreeRTOSConfig.h. */
30    unsigned long ulRunTimeCounter;
31
32    /* Points to the lowest address of the task's stack area. */
33    StackType_t *pxStackBase;
34
35    #if ( configRECORD_STACK_HIGH_ADDRESS == 1 )
36        /* Points to the top address of the task's stack area. */
37        StackType_t * pxTopOfStack;
38
39        /* Points to the bottom address of the task's stack area. */
40        StackType_t * pxEndOfStack;
41    #endif
42
43    /* The minimum amount of stack space that has remained for the task since
44       the task was created. The closer this value is to zero the closer the task
45       has come to overflowing its stack. */
46    configSTACK_DEPTH_TYPE usStackHighWaterMark;
47} TaskStatus_t;

Copy