1. Introduction to Other FreeRTOS Task-Related API Functions
1. Introduction to FreeRTOS Task-Related API Functions (Commonly Used)
Answer:
2. Task Status Query API Functions
1. Function to Get Task Priority
Answer:
UBaseType_t uxTaskPriorityGet( const TaskHandle_t xTask )
This function is used to get the priority of a specified task. To use this function, the macro INCLUDE_uxTaskPriorityGet must be set to 1.
Function Parameters:
Function Return Value:
2. Function to Set Task Priority
Answer:
void vTaskPrioritySet( TaskHandle_t xTask , UBaseType_t uxNewPriority )
This function is used to change the priority of a task. To use this function, the macro INCLUDE_vTaskPrioritySet must be set to 1.
Function Parameters:
3. Function to Get the Number of Tasks in the System
Answer:
UBaseType_t uxTaskGetNumberOfTasks( void )
This function is used to get the number of tasks in the system.
Function Return Value:
4. Function to Get the Status Information of All Tasks in the System
Answer:
UBaseType_t uxTaskGetSystemState( TaskStatus_t * const pxTaskStatusArray,
const UBaseType_t uxArraySize,
configRUN_TIME_COUNTER_TYPE * const pulTotalRunTime )
This function is used to get the status information of all tasks in the system. To use this function, the macro configUSE_TRACE_FACILITY must be set to 1.
Function Parameters:
Function Return Value:
Structure of the parameter member pxTaskStatusArray:
typedef struct xTASK_STATUS
{
TaskHandle_t xHandle; /* Task handle */
const char * pcTaskName; /* Task name */
UBaseType_t xTaskNumber; /* Task number */
eTaskState CurrentState; /* Task state */
UBaseType_t uxCurrentPriority; /* Current task priority */
UBaseType_t uxBasePriority; /* Original task priority */
configRUN_TIME_COUNTER_TYPE ulRunTimeCounter; /* Task run time */
StackType_t * pxStackBase; /* Base address of task stack */
configSTACK_DEPTH_TYPE usStackHighWaterMark; /* Minimum remaining stack size history */
} TaskStatus_t;
5. Function to Get the Status Information of a Single Task in the System
Answer:
void vTaskGetInfo( TaskHandle_t xTask,
TaskStatus_t * pxTaskStatus,
BaseType_t xGetFreeStackSpace,
eTaskState eState )
This function is used to get the status information of a specified single task. To use this function, the macro configUSE_TRACE_FACILITY must be set to 1.
Function Parameters:
Structure of the parameter member eState:
typedef enum
{
eRunning = 0, /* Running state */
eReady, /* Ready state */
eBlocked, /* Blocked state */
eSuspended, /* Suspended state */
eDeleted, /* Task deleted */
eInvalid /* Invalid */
} eTaskState;
6. Function to Get the Current Task Handle
Answer:
TaskHandle_t xTaskGetCurrentTaskHandle( void )
This function is used to get the handle of the current task. To use this function, the macro INCLUDE_xTaskGetCurrentTaskHandle must be set to 1.
Function Return Value:
7. Function to Get Task Handle by Task Name
Answer:
TaskHandle_t xTaskGetHandle(const char * pcNameToQuery);
This function is used to get the task handle by task name. To use this function, the macro INCLUDE_xTaskGetHandle must be set to 1.
Function Parameters:
Function Return Value:
8. Function to Get the Task Stack High Water Mark of a Specified Task
UBaseType_t uxTaskGetStackHighWaterMark( TaskHandle_t xTask )
This function is used to get the historical minimum remaining stack of a specified task. To use this function, the macro INCLUDE_uxTaskGetStackHighWaterMark must be set to 1.
Function Parameters:
Function Return Value:
9. Function to Query the Running State of a Specified Task
Answer:
eTaskState eTaskGetState(TaskHandle_t xTask)
This function is used to query the running state of a task. To use this function, the macro INCLUDE_eTaskGetState must be set to 1.
Function Parameters:
Function Return Value:
Structure of the parameter member xTask:
typedef enum
{
eRunning = 0, /* Running state */
eReady, /* Ready state */
eBlocked, /* Blocked state */
eSuspended, /* Suspended state */
eDeleted, /* Task deleted */
eInvalid /* Invalid */
} eTaskState;
10. Function to Get System Task Information in a “Table” Format
Answer:
void vTaskList(char * pcWriteBuffer)
This function is used to get the information of tasks in the system in a “table” format.
To use this function, the macros configUSE_TRACE_FACILITY and configUSE_STATS_FORMATTING_FUNCTIONS must be set to 1.
Function Parameters:
Table Content:
- Name: The name assigned to the task when it is created.
- State: The state information of the task, B is Blocked, R is Ready, S is Suspended, D is Deleted.
- Priority: Task priority.
- Stack: The “high water mark” of the task stack, which is the historical minimum remaining size of the stack.
- Num: Task number, which is unique. When multiple tasks use the same task name, this number can be used to distinguish them.
3. Task Time Statistics API Functions
1. Task Time Statistics Function
Answer:
void vTaskGetRunTimeStats( char * pcWriteBuffer )
This function is used to collect task run time information. To use this function, the macros configGENERATE_RUN_TIME_STAT and configUSE_STATS_FORMATTING_FUNCTIONS must be set to 1.
Function Parameters:
Time Statistics Table:
- Task: Task name.
- Abs Time: Total actual run time of the task (absolute time).
- %Time: Percentage of total processing time.
2. Process for Using Time Statistics API Functions
Answer:
1. Set the macro configGENERATE_RUN_TIME_STATS to 1.
2. Set the macro configUSE_STATS_FORMATTING_FUNCTIONS to 1.
3. After setting the macro configGENERATE_RUN_TIME_STAT to 1, two additional macro definitions need to be implemented:
1) portCONFIGURE_TIMER_FOR_RUNTIME_STATE(): Used to initialize the timer for configuring task run time statistics;
Note: The timing precision of this timer must be 10 to 100 times higher than the system clock tick precision!
2) portGET_RUN_TIME_COUNTER_VALUE(): Used to get the count value of the hardware timer for this function.