vTaskList() for task status dump in FreeRTOS

Introduction

The vTaskList() function helps you see what tasks are running in FreeRTOS. It shows their names, states, priorities, and stack usage. This is useful to understand how your program is working.

You want to check which tasks are active in your FreeRTOS system.

You need to find out if any task is stuck or blocked.

You want to monitor stack usage to avoid overflow.

You are debugging your FreeRTOS application to see task details.

You want to log task status for system health monitoring.

Syntax

FreeRTOS

void vTaskList(char *pcWriteBuffer);

pcWriteBuffer must point to a buffer large enough to hold the task list string.

The output is a formatted string showing task name, state, priority, stack, and task number.

Examples

This example creates a buffer, calls vTaskList() to fill it, then prints the task list.

FreeRTOS

char taskListBuffer[512];
vTaskList(taskListBuffer);
printf("Task List:\n%s", taskListBuffer);

If no tasks exist, the buffer will contain only the header or be empty.

FreeRTOS

// Edge case: Empty task list (no tasks created yet)
char emptyBuffer[512];
vTaskList(emptyBuffer);
printf("Empty Task List:\n%s", emptyBuffer);

Shows output when only one task is running.

FreeRTOS

// Edge case: Single task
char singleTaskBuffer[512];
vTaskList(singleTaskBuffer);
printf("Single Task List:\n%s", singleTaskBuffer);

Shows task list including a task with the highest priority.

FreeRTOS

// Edge case: Task at highest priority
char highPriorityBuffer[512];
vTaskList(highPriorityBuffer);
printf("High Priority Task List:\n%s", highPriorityBuffer);

Sample Program

This program creates two simple tasks with different priorities. It starts the FreeRTOS scheduler. After scheduler stops (which normally doesn't happen), it calls vTaskList() to get the task status and prints it.

FreeRTOS

#include "FreeRTOS.h"
#include "task.h"
#include <stdio.h>

// Simple task function
void vSimpleTask(void *pvParameters) {
    for (;;) {
        vTaskDelay(pdMS_TO_TICKS(1000));
    }
}

int main(void) {
    // Create two tasks
    xTaskCreate(vSimpleTask, "Task1", 1000, NULL, 1, NULL);
    xTaskCreate(vSimpleTask, "Task2", 1000, NULL, 2, NULL);

    // Buffer to hold task list
    char taskListBuffer[512];

    // Start scheduler
    vTaskStartScheduler();

    // This code runs only if scheduler exits (which normally it doesn't)
    vTaskList(taskListBuffer);
    printf("Task List:\n%s", taskListBuffer);

    return 0;
}

Important Notes

Time complexity: vTaskList() runs in O(n) where n is the number of tasks.

Space complexity: The buffer size must be large enough to hold all task info; typically 512 bytes or more.

Common mistake: Not providing a large enough buffer causes truncated or corrupted output.

When to use: Use vTaskList() for debugging and monitoring task states. For real-time monitoring, consider other methods as this function is not real-time safe.

Summary

vTaskList() shows all running tasks and their status in a readable format.

It requires a buffer to store the output string.

Useful for debugging and checking task health in FreeRTOS.