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.

Practice

1. What is the primary purpose of the vTaskGetRunTimeStats() function in FreeRTOS?

easy

A. To suspend all running tasks temporarily

B. To create a new task with specific priority

C. To delete a task from the scheduler

D. To display the CPU usage time of each task

Solution

1. Step 1: Understand the function's role

   vTaskGetRunTimeStats() is designed to collect and display CPU usage statistics for each task in FreeRTOS.

2. Step 2: Compare options with function purpose

   Options A, B, and C relate to task management but not CPU usage reporting, which is the key role of vTaskGetRunTimeStats().

3. Final Answer:

   To display the CPU usage time of each task -> Option D

4. Quick Check:

   Function purpose = CPU usage display [OK]

Hint: Remember: vTaskGetRunTimeStats shows CPU time per task [OK]

Common Mistakes:

• Confusing it with task creation or deletion functions
• Thinking it suspends tasks instead of reporting stats
• Assuming it modifies task priorities

2. Which of the following is the correct way to call vTaskGetRunTimeStats() to store the stats in a buffer named buffer?

easy

A. vTaskGetRunTimeStats(buffer);

B. vTaskGetRunTimeStats(&buffer);

C. vTaskGetRunTimeStats(buffer[]);

D. vTaskGetRunTimeStats(*buffer);

Solution

1. Step 1: Check function parameter type

   vTaskGetRunTimeStats() expects a pointer to a char array (string buffer), so passing the buffer name directly is correct.

2. Step 2: Analyze each option's syntax

   vTaskGetRunTimeStats(buffer); passes the buffer correctly. vTaskGetRunTimeStats(&buffer); passes address of buffer pointer (wrong). vTaskGetRunTimeStats(buffer[]); uses invalid syntax. vTaskGetRunTimeStats(*buffer); dereferences buffer incorrectly.

3. Final Answer:

   vTaskGetRunTimeStats(buffer); -> Option A

4. Quick Check:

   Pass buffer name directly [OK]

Hint: Pass buffer name directly, no & or * needed [OK]

Common Mistakes:

• Using &buffer which is wrong for arrays
• Adding [] inside function call
• Dereferencing buffer pointer incorrectly

3. Given the following code snippet, what will be the output stored in statsBuffer?

char statsBuffer[100];
vTaskGetRunTimeStats(statsBuffer);
printf("%s", statsBuffer);

Assuming two tasks "TaskA" and "TaskB" run and TaskA used 70% CPU, TaskB used 30%.

medium

A. TaskA 7
TaskB 3

B. TaskA 70%
TaskB 30%

C. TaskA 7000
TaskB 3000

D. TaskA 700
TaskB 300

Solution

1. Step 1: Understand output format of vTaskGetRunTimeStats()

   The function outputs CPU usage as run time counter ticks, not percentages. If TaskA used 70% CPU, it might show 7000 ticks and TaskB 3000 ticks (assuming 10000 total ticks).

2. Step 2: Match options with expected output

   TaskA 7000 TaskB 3000 shows usage in ticks (7000 and 3000), matching expected output. Options B, C, and D show percentages or smaller numbers, which are not the direct output format.

3. Final Answer:

   TaskA 7000 TaskB 3000 -> Option C

4. Quick Check:

   Output shows ticks, not percentages [OK]

Hint: Output shows ticks, not percent values [OK]

Common Mistakes:

• Assuming output shows percentages directly
• Confusing ticks with smaller numbers
• Expecting formatted percentages in output

4. You called vTaskGetRunTimeStats(statsBuffer); but the output is empty. What is the most likely cause?

medium

A. The function requires a NULL pointer as argument

B. Run time stats collection is not enabled in FreeRTOSConfig.h

C. The buffer size is too large

D. The tasks have zero priority

Solution

1. Step 1: Identify prerequisites for run time stats

   Run time stats must be enabled in FreeRTOSConfig.h (configGENERATE_RUN_TIME_STATS set to 1) for vTaskGetRunTimeStats() to work.

2. Step 2: Analyze other options

   Buffer size being too large does not cause empty output. Passing NULL is invalid. Task priority does not affect stats collection directly.

3. Final Answer:

   Run time stats collection is not enabled in FreeRTOSConfig.h -> Option B

4. Quick Check:

   Enable run time stats in config [OK]

Hint: Check configGENERATE_RUN_TIME_STATS is enabled [OK]

Common Mistakes:

• Assuming buffer size too large causes empty output
• Passing NULL pointer mistakenly
• Thinking task priority disables stats

5. You want to monitor CPU usage of tasks over time using vTaskGetRunTimeStats(). Which approach correctly ensures accurate and meaningful stats?

hard

A. Enable run time stats, provide a large buffer, call periodically, and reset counters between calls

B. Call vTaskGetRunTimeStats() once at startup with a small buffer

C. Disable run time stats and manually count task switches

D. Call vTaskGetRunTimeStats() inside each task to get its own CPU usage

Solution

1. Step 1: Understand requirements for accurate CPU stats

   Run time stats must be enabled, buffer must be large enough to hold all task info, and stats should be collected periodically to track changes over time.

2. Step 2: Evaluate each option

   Enable run time stats, provide a large buffer, call periodically, and reset counters between calls describes the correct approach including resetting counters to avoid cumulative overflow. Call vTaskGetRunTimeStats() once at startup with a small buffer is insufficient (only once, small buffer). Disable run time stats and manually count task switches disables stats, losing automation. Call vTaskGetRunTimeStats() inside each task to get its own CPU usage is incorrect because stats are global, not per task.

3. Final Answer:

   Enable run time stats, provide a large buffer, call periodically, and reset counters between calls -> Option A

4. Quick Check:

   Enable + buffer + periodic calls + reset = accurate stats [OK]

Hint: Enable stats, use big buffer, call regularly, reset counters [OK]

Common Mistakes:

• Calling once only at startup
• Disabling run time stats
• Calling inside each task expecting per-task stats