Solving FreeRTOS Queue Overflow and Task Starvation

What causes this

FreeRTOS queue overflow and task starvation often occur when tasks that are responsible for dequeuing messages are not scheduled frequently enough, or when producers send messages faster than consumers can process them. A common culprit is a misconfigured task priority or an inadequate stack size, leading to inefficient task scheduling.

In the ESP32 architecture, these issues can be exacerbated by incorrect FreeRTOS configurations such as configMAX_PRIORITIES, configQUEUE_REGISTRY_SIZE, and configUSE_PREEMPTION. For instance, a high CPU load can cause the uxHighWaterMark to drop, leading to task starvation. Additionally, an overloaded queue will trigger a buffer overflow error, often indicated by crashing with error codes like 0x101 (out of memory) or 0x107 (stack overflow).

Register names such as PS, PC, and A0 in the exception decoder output will help identify the task causing the issue. It's also crucial to review the configuration in FreeRTOSConfig.h to ensure that queue and task priorities are correctly set.

Minimal reproduction

Here's a minimal example that consistently triggers a queue overflow:

```c

#include

#include

#include

QueueHandle_t xQueue;

void producerTask(void *pvParameters) {

int msg = 0;

while (true) {

xQueueSend(xQueue, &msg, portMAX_DELAY);

msg++;

}

}

void consumerTask(void *pvParameters) {

int received;

while (true) {

if (xQueueReceive(xQueue, &received, portMAX_DELAY) == pdTRUE) {

// Process received item

}

}

}

void setup() {

xQueue = xQueueCreate(5, sizeof(int));

xTaskCreatePinnedToCore(producerTask, "Producer", 1024, NULL, 1, NULL, 0);

xTaskCreatePinnedToCore(consumerTask, "Consumer", 1024, NULL, 1, NULL, 0);

}

void loop() {}

```

Expected serial output when the queue overflows:

```

Guru Meditation Error: Core 1 panic'ed (LoadProhibited). Exception was unhandled.

Register dump:

PC : 0x400d1234 PS : 0x00060030 A0 : 0x800d0f68 A1 : 0x3ffb1f00

...

```

The fix

To resolve the queue overflow and task starvation issue, consider the following adjustments:

Before:

```c

xTaskCreatePinnedToCore(producerTask, "Producer", 1024, NULL, 1, NULL, 0);

xTaskCreatePinnedToCore(consumerTask, "Consumer", 1024, NULL, 1, NULL, 0);

```

After:

```c

xTaskCreatePinnedToCore(producerTask, "Producer", 1024, NULL, 1, NULL, 0);

xTaskCreatePinnedToCore(consumerTask, "Consumer", 1024, NULL, 2, NULL, 0);

```

By increasing the priority of the consumerTask, you allow it to preempt the producerTask, reducing the chance of queue overflow and ensuring that the consumer can keep up with the producer.

Additionally, check FreeRTOSConfig.h to ensure parameters like configMINIMAL_STACK_SIZE and configUSE_TIME_SLICING are correctly set to balance CPU usage.

How SerialDoctor catches this

SerialDoctor analyzes the serial output for specific patterns and codes that indicate queue overflow and task starvation. By parsing the register dump and exception codes, it pinpoints the exact issue and suggests configuration changes within seconds. Visit [serialdoctor.com](http://serialdoctor.com) to streamline your debugging process.

Quick checklist

• [ ] Ensure task priorities are set to reflect task importance.
• [ ] Validate queue sizes are sufficient for peak loads.
• [ ] Examine stack sizes and increase if tasks are consuming more memory.
• [ ] Monitor CPU load to prevent task starvation.
• [ ] Use FreeRTOS trace tools to analyze task execution patterns.

Seeing this crash on your board right now?

Connect it to SerialDoctor and get a root cause + code fix in under 3 seconds.