Stack high water mark monitoring in FreeRTOS - Step-by-Step Execution

Concept Flow - Stack high water mark monitoring

Task starts running

↓

Stack usage increases

↓

Check current stack usage

↓

Compare with previous high water mark

↓

Update HWM

↓

Task continues or ends

This flow shows how FreeRTOS tracks the deepest stack usage of a task by checking current usage and updating the high water mark if needed.

Execution Sample

FreeRTOS

UBaseType_t uxTaskGetStackHighWaterMark(TaskHandle_t xTask);

// Called periodically or on demand
highWaterMark = uxTaskGetStackHighWaterMark(taskHandle);

This code calls the FreeRTOS API to get the minimum free stack space (high water mark) for a task.

Execution Table

Step	Task State	Stack Usage (bytes)	High Water Mark (bytes)	Action
1	Task started	0	1024	Initialize stack, HWM set to total stack size
2	Running	200	824	Current usage 200, HWM updated to 824
3	Running	400	624	Current usage 400, HWM updated to 624
4	Running	600	424	Current usage 600, HWM updated to 424
5	Running	800	224	Current usage 800, HWM updated to 224
6	Running	900	124	Current usage 900, HWM updated to 124
7	Running	950	74	Current usage 950, HWM updated to 74
8	Running	980	44	Current usage 980, HWM updated to 44
9	Running	1000	24	Current usage 1000, HWM updated to 24
10	Running	1020	4	Current usage 1020, HWM updated to 4
11	Running	1024	0	Stack fully used, HWM updated to 0
12	Check HWM	N/A	0	API returns 0 bytes free (stack fully used)
13	Task ends	N/A	0	Final high water mark recorded

💡 Task ends or monitoring stops; high water mark shows minimum free stack space during task life

Variable Tracker

Variable	Start	After Step 2	After Step 5	After Step 10	Final
Stack Usage (bytes)	0	200	800	1020	N/A
High Water Mark (bytes free)	1024	824	224	4	0

Key Moments - 3 Insights

Why does the high water mark value decrease as stack usage increases?

The high water mark tracks the minimum free stack space left, so as usage grows, free space shrinks, lowering the high water mark (see execution_table steps 2 to 10).

What does the high water mark value represent exactly?

It represents the smallest amount of free stack space remaining during the task's execution, indicating the deepest stack usage (see step 12 where 0 bytes free means stack fully used).

Why is the high water mark useful for monitoring?

It helps detect if the stack size is sufficient or if the task risks overflow by showing the closest point to full stack usage (refer to final high water mark in execution_table).

Visual Quiz - 3 Questions

Look at the execution table at step 10, what is the stack usage?

A 1020 bytes

B 1000 bytes

C 1024 bytes

D 980 bytes

💡 Hint

Check the 'Stack Usage (bytes)' column at step 10 in the execution_table.

At which step does the API report the high water mark as 24 bytes free?

A Step 12

B Step 9

C Step 6

D Step 13

💡 Hint

Look for the step where 'API returns 24 bytes free' in the Action column.

If the stack usage never exceeded 500 bytes, how would the high water mark change?

A It would stay at 1024 bytes

B It would be 500 bytes

C It would be around 524 bytes

D It would be 0 bytes

💡 Hint

High water mark = total stack size - max usage; check variable_tracker for relation.

Concept Snapshot

FreeRTOS stack high water mark shows minimum free stack space during task run.
Use uxTaskGetStackHighWaterMark(taskHandle) to get it.
Lower value means deeper stack usage.
Monitor to avoid stack overflow.
Update happens as task runs and stack usage changes.

Full Transcript

Stack high water mark monitoring in FreeRTOS tracks the minimum free stack space left during a task's execution. As the task runs and uses more stack, the free space decreases, lowering the high water mark. The API uxTaskGetStackHighWaterMark returns this value, helping developers see how close the task came to overflowing its stack. Monitoring this helps ensure stack sizes are sufficient and prevents crashes. The execution table shows stack usage increasing step by step, while the high water mark decreases accordingly. When the task ends, the final high water mark indicates the smallest free stack space recorded.

Practice

1.

What does the stack high water mark indicate in FreeRTOS?

easy

A. The total stack size allocated to a task

B. The minimum amount of free stack space a task has had

C. The maximum CPU usage of a task

D. The number of tasks currently running

Solution

1. Step 1: Understand stack high water mark meaning

   The stack high water mark shows the smallest amount of unused stack space a task has had since it started.

2. Step 2: Compare with other options

   Other options describe CPU usage, total stack size, or task count, which are unrelated to stack high water mark.

3. Final Answer:

   The minimum amount of free stack space a task has had -> Option B

4. Quick Check:

   Stack high water mark = minimum free stack space [OK]

Hint: Remember: 'high water mark' means lowest free stack left [OK]

Common Mistakes:

• Confusing stack size with stack usage
• Thinking it measures CPU or task count
• Assuming it shows maximum stack used

2.

Which is the correct way to get the stack high water mark of the current task in FreeRTOS?

?

easy

A. uxTaskGetStackHighWaterMark(NULL);

B. uxTaskGetStackHighWaterMark(currentTask);

C. getStackHighWaterMark(NULL);

D. uxGetStackHighWaterMark();

Solution

1. Step 1: Recall function signature

   The FreeRTOS function to get stack high water mark is uxTaskGetStackHighWaterMark, which takes a task handle or NULL for current task.

2. Step 2: Identify correct usage

   Passing NULL gets the current task's high water mark. Other options use wrong function names or parameters.

3. Final Answer:

   uxTaskGetStackHighWaterMark(NULL); -> Option A

4. Quick Check:

   Use NULL for current task in uxTaskGetStackHighWaterMark [OK]

Hint: Use NULL to refer to current task handle [OK]

Common Mistakes:

• Using wrong function names
• Passing invalid parameters instead of NULL
• Assuming no parameter needed

3.

Given the following code snippet, what will be the output if the task's minimum free stack space was 50 words?

UBaseType_t highWaterMark = uxTaskGetStackHighWaterMark(NULL);
printf("High water mark: %u\n", highWaterMark);

medium

A. High water mark: 50

B. High water mark: 0

C. High water mark: Stack overflow

D. Compilation error

Solution

1. Step 1: Understand uxTaskGetStackHighWaterMark output

   This function returns the minimum free stack space (in words) the task had, which is 50 in this case.

2. Step 2: Analyze printf output

   The printf prints the unsigned integer value returned, so output will be "High water mark: 50".

3. Final Answer:

   High water mark: 50 -> Option A

4. Quick Check:

   Function returns minimum free stack, printed as number [OK]

Hint: Function returns minimum free stack words, print as unsigned int [OK]

Common Mistakes:

• Assuming it returns zero on no overflow
• Thinking it returns error string
• Confusing with stack size or usage

4.

Identify the error in this code snippet intended to get the stack high water mark of a task named myTaskHandle:

UBaseType_t mark = uxTaskGetStackHighWaterMark(myTaskHandle);

Assume myTaskHandle is a valid task handle.

medium

A. Return type should be int, not UBaseType_t

B. Function name is incorrect, should be uxGetStackHighWaterMark

C. Parameter should be NULL to get any task's high water mark

D. No error, code is correct

Solution

1. Step 1: Verify function and parameter usage

   uxTaskGetStackHighWaterMark takes a task handle to get that task's high water mark. Using myTaskHandle is valid.

2. Step 2: Check return type and function name

   Return type UBaseType_t is correct. Function name is correct as per FreeRTOS API.

3. Final Answer:

   No error, code is correct -> Option D

4. Quick Check:

   Correct function and parameter usage means no error [OK]

Hint: Use task handle parameter for specific task, NULL for current task [OK]

Common Mistakes:

• Thinking NULL is required for all tasks
• Using wrong function names
• Confusing return types

5.

You want to monitor stack usage of multiple tasks and log a warning if any task's stack high water mark falls below 20 words. Which approach is best?

hard

A. Only check the current task's stack high water mark using NULL parameter

B. Increase all task stack sizes to 20 words to avoid overflow

C. Periodically call uxTaskGetStackHighWaterMark for each task handle and check if value < 20

D. Use vTaskDelete to remove tasks with low stack

Solution

1. Step 1: Understand monitoring multiple tasks

   To monitor multiple tasks, you must check each task's stack high water mark individually using their task handles.

2. Step 2: Implement threshold check

   Calling uxTaskGetStackHighWaterMark for each task and comparing to 20 words allows detecting low stack and logging warnings.

3. Final Answer:

   Periodically call uxTaskGetStackHighWaterMark for each task handle and check if value < 20 -> Option C

4. Quick Check:

   Check each task's high water mark against threshold [OK]

Hint: Check each task's high water mark, compare to threshold [OK]

Common Mistakes:

• Checking only current task misses others
• Assuming increasing stack size fixes monitoring
• Deleting tasks instead of warning