vTaskGetRunTimeStats() for CPU usage in FreeRTOS - Step-by-Step Execution

Concept Flow - vTaskGetRunTimeStats() for CPU usage

Start Scheduler

↓

Tasks run and consume CPU

↓

Call vTaskGetRunTimeStats()

↓

Collect run time counters for each task

↓

Calculate CPU usage % per task

↓

Return formatted string with stats

↓

Display or log CPU usage

This flow shows how FreeRTOS collects CPU usage data by tracking task run times and then formats it into a readable string.

Execution Sample

FreeRTOS

char buffer[512];
vTaskGetRunTimeStats(buffer);
printf("%s", buffer);

This code collects CPU usage stats of all tasks and prints them as a formatted string.

Execution Table

Step	Action	Internal Operation	Result
1	Start Scheduler	Tasks begin running, run time counters start incrementing	Tasks run, counters increment
2	Call vTaskGetRunTimeStats(buffer)	Function reads run time counters for each task	Counters collected
3	Calculate CPU usage %	For each task: (task run time / total run time) * 100	CPU usage % computed
4	Format stats string	Create human-readable table with task names and CPU %	Formatted string stored in buffer
5	Print buffer	Output the CPU usage stats to console or log	CPU usage stats displayed
6	End	Function returns after filling buffer	Execution complete

💡 Function ends after filling the buffer with CPU usage stats for all tasks

Variable Tracker

Variable	Start	After Step 2	After Step 3	After Step 4	Final
buffer	"" (empty)	"Counters collected string"	"CPU % calculated string"	"Formatted stats string"	"Ready to print string"
taskRunTimeCounter	0	Incremented by task run time	Used for CPU % calculation	Used for formatting	Used for display
totalRunTime	0	Sum of all task run times	Used for CPU % calculation	Used for formatting	Used for display

Key Moments - 3 Insights

Why does the CPU usage percentage not add up exactly to 100%?

Because of rounding during percentage calculation and possible time spent in the idle task or interrupts, the sum may be slightly less or more than 100%. See execution_table step 3.

What happens if the buffer passed to vTaskGetRunTimeStats() is too small?

The function may truncate the output string, so some task stats might be missing. Always provide a sufficiently large buffer as shown in execution_table step 4.

Does vTaskGetRunTimeStats() affect task scheduling or performance?

No, it only reads counters and formats a string. It does not block or change task priorities. This is shown in execution_table steps 2 and 4.

Visual Quiz - 3 Questions

Look at the execution_table at step 3, what is calculated for each task?

A The CPU usage percentage based on run time counters

B The task priority level

C The stack size used by the task

D The number of times the task was switched

💡 Hint

Refer to execution_table row with Step 3 describing CPU usage % calculation

According to variable_tracker, what does the 'buffer' variable contain after step 4?

A Empty string

B Formatted stats string ready to print

C Raw run time counters

D Task handles

💡 Hint

Check variable_tracker row for 'buffer' after Step 4

If the buffer size is too small, what is the likely effect on the output?

A Function will crash

B All task stats will be shown correctly

C Output string may be truncated, missing some tasks

D CPU usage percentages will be incorrect

💡 Hint

See key_moments explanation about buffer size and truncation

Concept Snapshot

vTaskGetRunTimeStats(buffer) collects CPU run time counters for all tasks.
It calculates CPU usage % = (task run time / total run time) * 100.
Results are formatted into a string stored in buffer.
Call after scheduler start to get current CPU usage.
Ensure buffer is large enough to hold all stats.
Useful for monitoring task CPU consumption in FreeRTOS.

Full Transcript

This visual execution trace shows how FreeRTOS's vTaskGetRunTimeStats() function works to measure CPU usage per task. First, the scheduler starts and tasks run, incrementing their run time counters. When vTaskGetRunTimeStats() is called, it reads these counters, sums total run time, and calculates each task's CPU usage percentage. Then it formats this data into a readable string stored in the provided buffer. Finally, the string can be printed or logged to show CPU usage stats. Variables like buffer, taskRunTimeCounter, and totalRunTime change step-by-step as the function executes. Common beginner questions include why percentages may not add to 100%, the importance of buffer size, and that this function does not affect scheduling. The quizzes test understanding of CPU usage calculation, buffer content, and effects of buffer size. This helps learners see exactly how CPU usage stats are gathered and displayed in FreeRTOS.