Common RTOS bugs and debugging strategies in FreeRTOS

Introduction

RTOS bugs can cause your program to freeze or behave wrongly. Debugging helps find and fix these problems so your system runs smoothly.

When your RTOS tasks stop responding or freeze.

If you see unexpected behavior like wrong data or missed events.

When your system crashes or restarts without clear reason.

If tasks are not running in the order or timing you expect.

When debugging communication or resource sharing issues between tasks.

Syntax

FreeRTOS

No specific syntax, but common debugging tools and methods include:
- Using FreeRTOS trace macros
- Enabling configUSE_TRACE_FACILITY
- Using task notifications and hooks
- Checking return values of API calls
- Using breakpoints and watch variables in debugger

FreeRTOS provides trace and debug macros to help track task states.

Always check return values of RTOS functions to catch errors early.

Examples

Always check if task creation returns pdPASS to ensure the task was created.

FreeRTOS

// Example: Check if task creation succeeded
if (xTaskCreate(TaskFunction, "Task1", 1000, NULL, 1, NULL) != pdPASS) {
    // Handle error
}

configASSERT helps catch invalid pointers or failed resource creation during debugging.

FreeRTOS

// Example: Use configASSERT to catch errors
configASSERT(queueHandle != NULL);

This allows using trace macros to monitor task states and events.

FreeRTOS

// Example: Enable trace facility in FreeRTOSConfig.h
#define configUSE_TRACE_FACILITY 1

Sample Program

This simple program creates one task and starts the scheduler. It checks if task creation succeeded and prints a message if it failed. This helps catch a common bug where tasks fail to create.

FreeRTOS

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

void vTask1(void *pvParameters) {
    for (;;) {
        printf("Task 1 running\n");
        vTaskDelay(pdMS_TO_TICKS(1000));
    }
}

int main(void) {
    BaseType_t result = xTaskCreate(vTask1, "Task1", 1000, NULL, 1, NULL);
    if (result != pdPASS) {
        printf("Task creation failed!\n");
        while(1); // Stop here
    }
    vTaskStartScheduler();
    // Should never reach here
    printf("Scheduler ended unexpectedly\n");
    return 0;
}

Important Notes

Common RTOS bugs include stack overflow, priority inversion, and deadlocks.

Use stack overflow hooks and check task stack sizes to avoid crashes.

Use priority inheritance or mutexes to prevent priority inversion.

Summary

Always check return values of RTOS API calls to catch errors early.

Use FreeRTOS debug features like configASSERT and trace macros.

Watch for common bugs like deadlocks, stack overflow, and priority inversion.

Practice

1. Which of the following is a common cause of deadlocks in FreeRTOS applications?

easy

A. Not enabling the FreeRTOS scheduler

B. Using too much heap memory for dynamic allocation

C. Incorrect task priority assignment causing starvation

D. Two tasks waiting indefinitely for each other's resource

Solution

1. Step 1: Understand deadlock concept in RTOS

   Deadlock happens when two or more tasks wait forever for resources held by each other.

2. Step 2: Identify the scenario causing deadlock

   Two tasks waiting indefinitely for each other's resource is the classic deadlock cause.

3. Final Answer:

   Two tasks waiting indefinitely for each other's resource -> Option D

4. Quick Check:

   Deadlock = Mutual waiting [OK]

Hint: Deadlock means tasks wait forever for each other's resource [OK]

Common Mistakes:

• Confusing deadlock with priority inversion
• Thinking heap size causes deadlock
• Assuming scheduler not started causes deadlock

2. Which FreeRTOS API call correctly creates a task?

easy

A. xTaskCreate(TaskFunction, "Task1", 1000, NULL, 2, NULL);

B. vTaskCreate(TaskFunction, "Task1", 1000, NULL, 2, NULL);

C. xTaskCreate(TaskFunction, 1000, "Task1", NULL, 2, NULL);

D. xTaskCreate(TaskFunction, "Task1", NULL, 1000, 2, NULL);

Solution

1. Step 1: Recall FreeRTOS task creation syntax

   The correct syntax is xTaskCreate(TaskFunction, "Name", stackSize, parameters, priority, taskHandle).

2. Step 2: Match options with correct parameter order

   xTaskCreate(TaskFunction, "Task1", 1000, NULL, 2, NULL); matches the correct order and types.

3. Final Answer:

   xTaskCreate(TaskFunction, "Task1", 1000, NULL, 2, NULL); -> Option A

4. Quick Check:

   Correct API call = xTaskCreate(TaskFunction, "Task1", 1000, NULL, 2, NULL); [OK]

Hint: xTaskCreate returns status; remember parameter order [OK]

Common Mistakes:

• Mixing up parameter order
• Using void return type function instead of xTaskCreate
• Passing NULL for stack size

3. Given the code snippet:

void vTask1(void *pvParameters) {
  for(;;) {
    xSemaphoreTake(xMutex, portMAX_DELAY);
    // Critical section
    xSemaphoreGive(xMutex);
    vTaskDelay(10);
  }
}

What is the likely effect if xSemaphoreGive(xMutex); is accidentally omitted?

medium

A. The mutex will be automatically released after timeout

B. The task will run normally without issues

C. Other tasks waiting for the mutex will block indefinitely

D. The system will reset due to stack overflow

Solution

1. Step 1: Understand semaphore usage in FreeRTOS

   Mutex must be given back after taking it to allow other tasks to access the resource.

2. Step 2: Analyze effect of missing xSemaphoreGive

   If xSemaphoreGive is omitted, the mutex stays taken, blocking other tasks indefinitely.

3. Final Answer:

   Other tasks waiting for the mutex will block indefinitely -> Option C

4. Quick Check:

   Missing give = Blocked tasks [OK]

Hint: Always pair xSemaphoreTake with xSemaphoreGive [OK]

Common Mistakes:

• Assuming mutex auto-releases
• Confusing blocking with stack overflow
• Ignoring semaphore usage rules

4. You observe that a FreeRTOS task sometimes stops running unexpectedly. Which debugging strategy is best to identify if a stack overflow caused this?

medium

A. Enable configCHECK_FOR_STACK_OVERFLOW and use configASSERT

B. Increase task priority to highest level

C. Disable all interrupts temporarily

D. Use vTaskDelay to slow down the task

Solution

1. Step 1: Identify debugging features for stack overflow

   FreeRTOS provides configCHECK_FOR_STACK_OVERFLOW and configASSERT to detect stack overflow at runtime.

2. Step 2: Choose the best debugging method

   Enabling these features helps catch stack overflow errors causing task failure.

3. Final Answer:

   Enable configCHECK_FOR_STACK_OVERFLOW and use configASSERT -> Option A

4. Quick Check:

   Stack overflow debug = configCHECK_FOR_STACK_OVERFLOW [OK]

Hint: Use FreeRTOS built-in stack overflow checks [OK]

Common Mistakes:

• Thinking priority change fixes stack overflow
• Disabling interrupts hides bugs
• Using delay does not detect stack issues

5. In a FreeRTOS system, priority inversion occurs when a low priority task holds a resource needed by a high priority task. Which strategy helps to solve this problem?

hard

A. Increase the stack size of the low priority task

B. Use priority inheritance protocol on mutexes

C. Disable preemption in the scheduler

D. Use vTaskDelay in the high priority task

Solution

1. Step 1: Understand priority inversion problem

   Priority inversion happens when a low priority task blocks a high priority task by holding a resource.

2. Step 2: Identify solution using FreeRTOS features

   Priority inheritance protocol temporarily raises the low priority task's priority to prevent inversion.

3. Final Answer:

   Use priority inheritance protocol on mutexes -> Option B

4. Quick Check:

   Priority inversion fix = Priority inheritance [OK]

Hint: Enable priority inheritance on mutexes to fix inversion [OK]

Common Mistakes:

• Thinking stack size affects priority inversion
• Disabling preemption causes system issues
• Using delay does not solve inversion