HomeAbout UsContact Us

Fix FreeRTOS ISR Queue Not Waking: xHigherPriorityTaskWoken

By Jithin Tom
Published in Embedded OS
November 20, 2026
5 min read
Fix FreeRTOS ISR Queue Not Waking: xHigherPriorityTaskWoken

Table Of Contents

01
The Problem: ISR Sends, Task Sleeps Forever
02
How xHigherPriorityTaskWoken Works
03
Common Failure Patterns
04
Complete Working ISR Pattern
05
Advanced: Multiple Queue Sends in One ISR
06
FreeRTOS SMP Considerations
07
Debugging Checklist
08
Alternative: Direct Task Notifications (Often Better)
09
Summary
10
Related Reading
11
References
12
Frequently Asked Questions

An engineer adds xQueueSendFromISR() to a UART receive interrupt. The queue receives data. The waiting task calls xQueueReceive() with portMAX_DELAY. But the task never wakes. The system appears to hang. This is one of the most common FreeRTOS ISR integration failures — and it almost always traces back to xHigherPriorityTaskWoken and portYIELD_FROM_ISR misuse.

The Problem: ISR Sends, Task Sleeps Forever

/* UART RX ISR — receives a byte and posts to queue */
void USART2_IRQHandler(void) {
BaseType_t xHigherPriorityTaskWoken; // BUG: uninitialized!
if (LL_USART_IsActiveFlag_RXNE(USART2)) {
uint8_t byte = LL_USART_ReceiveData8(USART2);
xQueueSendFromISR(uart_rx_queue, &byte, &xHigherPriorityTaskWoken);
// BUG: No portYIELD_FROM_ISR() call!
}
}

The task blocks on xQueueReceive(uart_rx_queue, &byte, portMAX_DELAY). Data arrives. The ISR runs. xQueueSendFromISR returns pdPASS. But the task remains blocked. Why?

Root cause: The ISR unblocked the task but never requested a context switch. The kernel knows a higher-priority task is ready — but the current interrupt context continues, and the scheduler only runs on the next tick interrupt (or explicit yield). In a busy system, that delay can be milliseconds — or forever if ticks are suppressed.

Inside the Queue: What Actually Happens

When xQueueSendFromISR() executes, it performs these steps atomically within a critical section:

  1. Check queue capacity — If full, return errQUEUE_FULL immediately (no blocking in ISR)
  2. Copy data into queue storage — Byte-by-byte copy of the item
  3. Check xTasksWaitingToReceive list — If a task is blocked on this queue
  4. Unblock the task — Move it from Blocked to Ready state
  5. Compare priorities — If unblocked task priority > current running task priority, set *pxHigherPriorityTaskWoken = pdTRUE
  6. Return pdPASS — Data was enqueued successfully

The critical insight: step 5 only sets the flag. It does not perform a context switch. The ISR continues executing. The scheduler only runs when:

  • The ISR returns and portYIELD_FROM_ISR() was called
  • The next tick interrupt occurs
  • A task explicitly yields

This design is intentional: FreeRTOS separates “unblocking a task” from “switching to that task” because the ISR context cannot safely invoke the scheduler directly on many architectures.

How xHigherPriorityTaskWoken Works

FreeRTOS queue send from ISR follows this contract:

  1. Caller initializes BaseType_t xHigherPriorityTaskWoken = pdFALSE;
  2. API sets it to pdTRUE if sending to the queue unblocked a task and that task has higher priority than the currently running task
  3. Caller must pass it to portYIELD_FROM_ISR() to request an immediate context switch
+------------------------------------------------------------------+
| ISR EXECUTION FLOW |
+------------------------------------------------------------------+
| |
| xQueueSendFromISR(queue, &data, &xHigherPriorityTaskWoken) |
| | |
| v |
| +--------------------------+ |
| | Task was blocked on queue?| |
| +--------------------------+ |
| | | |
| YES NO |
| | | |
| v v |
| +------------------+ xHigherPriorityTaskWoken |
| | Unblock task | remains pdFALSE |
| | Set xHigherPriority| |
| | TaskWoken = pdTRUE| |
| +------------------+ |
| | |
| v |
| portYIELD_FROM_ISR(xHigherPriorityTaskWoken) |
| | |
| +------+------+ |
| | pdTRUE? | |
| +------+------+ |
| / \ |
| YES NO |
| | | |
| v v |
| Context switch Return to |
| to high-prio interrupted |
| task immediately task |
| |
+------------------------------------------------------------------+

If xHigherPriorityTaskWoken is uninitialized (stack garbage), the portYIELD_FROM_ISR call reads an unpredictable value — sometimes yielding, sometimes not. If the variable is initialized but portYIELD_FROM_ISR is omitted entirely, the yield never happens.

Common Failure Patterns

1. Uninitialized Variable

/* WRONG: xHigherPriorityTaskWoken not initialized */
BaseType_t xHigherPriorityTaskWoken;
xQueueSendFromISR(queue, &item, &xHigherPriorityTaskWoken);
portYIELD_FROM_ISR(xHigherPriorityTaskWoken); // Reads garbage

Fix: Always initialize to pdFALSE.

/* CORRECT */
BaseType_t xHigherPriorityTaskWoken = pdFALSE;
xQueueSendFromISR(queue, &item, &xHigherPriorityTaskWoken);
portYIELD_FROM_ISR(xHigherPriorityTaskWoken);

2. Missing portYIELD_FROM_ISR Entirely

/* WRONG: No yield request */
BaseType_t xHigherPriorityTaskWoken = pdFALSE;
xQueueSendFromISR(queue, &item, &xHigherPriorityTaskWoken);
// Forgot portYIELD_FROM_ISR()

The task unblocks but only runs on the next tick. If configUSE_TICKLESS_IDLE is enabled and the system enters sleep, the task may not run until the next wake source — effectively a hang.

3. Passing NULL to xQueueSendFromISR

/* WRONG: NULL means "I don't care if a task was woken" */
xQueueSendFromISR(queue, &item, NULL);
// No way to know if yield needed
portYIELD_FROM_ISR(pdTRUE); // Forces yield every time — inefficient

From FreeRTOS V7.3.0, pxHigherPriorityTaskWoken can be NULL. But then you lose the ability to conditionally yield. You must call portYIELD_FROM_ISR(pdTRUE) unconditionally, which causes unnecessary context switches when no task was actually woken.

4. Interrupt Priority Above configMAX_SYSCALL_INTERRUPT_PRIORITY

/* NVIC configuration — WRONG priority */
NVIC_SetPriority(USART2_IRQn, 0); // Priority 0 = highest on Cortex-M
NVIC_EnableIRQ(USART2_IRQn);

If the ISR priority is numerically lower (higher urgency) than configMAX_SYSCALL_INTERRUPT_PRIORITY (typically configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY shifted), the configASSERT() inside xQueueSendFromISR triggers. The queue send fails silently in release builds.

Fix: Ensure ISR priority is at or below (numerically higher than) the max syscall priority:

/* CORRECT: Priority 5 (assuming configMAX_SYSCALL_INTERRUPT_PRIORITY = 5) */
NVIC_SetPriority(USART2_IRQn, 5);
NVIC_EnableIRQ(USART2_IRQn);

5. Using Non-FromISR API in ISR

/* WRONG: Blocking API in ISR */
xQueueSend(queue, &item, portMAX_DELAY); // CANNOT block in ISR!

Only FromISR suffixed APIs are ISR-safe. The non-ISR versions may block, use scheduler locks, or access non-reentrant data structures.

6. Queue Created After ISR Enabled

/* WRONG: IRQ enabled before queue exists */
NVIC_EnableIRQ(USART2_IRQn); // ISR can fire now!
uart_rx_queue = xQueueCreate(32, sizeof(uint8_t)); // Too late

If the ISR fires before xQueueCreate() runs, it dereferences a NULL/invalid handle. The result is a hard fault or silent corruption.

Fix: Create all kernel objects before enabling interrupts:

/* CORRECT: Queue first, IRQ last */
uart_rx_queue = xQueueCreate(32, sizeof(uint8_t));
configASSERT(uart_rx_queue != NULL);
NVIC_SetPriority(USART2_IRQn, 5);
NVIC_EnableIRQ(USART2_IRQn);

7. Queue Full Handling Missing

/* WRONG: Ignoring errQUEUE_FULL */
xQueueSendFromISR(queue, &item, &xHigherPriorityTaskWoken);
// If queue full, data lost silently

In high-throughput scenarios (DMA burst, high baud rate), the queue can fill faster than the task drains it. Ignoring errQUEUE_FULL loses data with no indication.

Fix: Always check return value and implement overflow policy:

/* CORRECT: Handle overflow explicitly */
if (xQueueSendFromISR(queue, &item, &xHigherPriorityTaskWoken) != pdPASS) {
/* Policy options: */
/* 1. Overwrite oldest (use xQueueSendFromISR with queueOVERWRITE) */
/* 2. Drop newest (current behavior) + increment error counter */
/* 3. Trigger system error / watchdog */
uart_rx_overflow_count++;
}

Complete Working ISR Pattern

/* FreeRTOSConfig.h prerequisites */
#define configUSE_PREEMPTION 1
#define configUSE_QUEUE_SETS 0 /* Not needed for basic queue */
#define INCLUDE_xQueueSendFromISR 1
#define INCLUDE_xQueueReceiveFromISR 1
/* Application code */
QueueHandle_t uart_rx_queue;
void USART2_IRQHandler(void) {
BaseType_t xHigherPriorityTaskWoken = pdFALSE;
uint8_t byte;
/* Check RXNE flag */
if (LL_USART_IsActiveFlag_RXNE(USART2)) {
byte = LL_USART_ReceiveData8(USART2);
/* Send to queue — ISR-safe, non-blocking */
if (xQueueSendFromISR(uart_rx_queue, &byte, &xHigherPriorityTaskWoken) != pdPASS) {
/* Queue full — handle overflow (e.g., increment error counter) */
uart_rx_overflow_count++;
}
}
/* Request context switch if higher-priority task was woken */
portYIELD_FROM_ISR(xHigherPriorityTaskWoken);
}
/* Task that processes received bytes */
void uart_rx_task(void *pvParameters) {
uint8_t byte;
for (;;) {
/* Blocks until data available */
if (xQueueReceive(uart_rx_queue, &byte, portMAX_DELAY) == pdPASS) {
process_byte(byte);
}
}
}

Advanced: Multiple Queue Sends in One ISR

When an ISR sends multiple items (e.g., DMA fills a buffer, ISR posts each byte), batch the yield:

void DMA1_Stream5_IRQHandler(void) {
BaseType_t xHigherPriorityTaskWoken = pdFALSE;
uint8_t *buffer = dma_rx_buffer;
size_t count = dma_get_received_count();
for (size_t i = 0; i < count; i++) {
xQueueSendFromISR(uart_rx_queue, &buffer[i], &xHigherPriorityTaskWoken);
}
/* Single yield at the end — efficient */
portYIELD_FROM_ISR(xHigherPriorityTaskWoken);
}

The variable accumulates: if any send unblocked a higher-priority task, it becomes pdTRUE. One yield suffices.

FreeRTOS SMP Considerations

On SMP (multi-core), portYIELD_FROM_ISR behavior is port-specific. The variable still works the same way, but the yield may need to target a specific core or broadcast an IPI.

/* SMP-safe pattern — same variable usage */
BaseType_t xHigherPriorityTaskWoken = pdFALSE;
xQueueSendFromISR(queue, &item, &xHigherPriorityTaskWoken);
/* Port handles multi-core yield correctly */
portYIELD_FROM_ISR(xHigherPriorityTaskWoken);

Key SMP points:

  • configUSE_CORE_AFFINITY must be 1 if you pin tasks to cores
  • The woken task runs on a core where its affinity allows it
  • If the task is pinned to a different core than the ISR, an IPI triggers the yield on that core
  • See vTaskCoreAffinitySet() for pinning tasks that service specific interrupts

SMP-Specific Pitfall: Affinity Mismatch

A common SMP failure: the ISR runs on Core 0, unblocks a task pinned to Core 1, but the IPI doesn’t reach Core 1 in time (or Core 1 is in a critical section). The task remains Ready on Core 1’s run queue but doesn’t execute immediately.

/* Task pinned to Core 1 only */
vTaskCoreAffinitySet(uart_task_handle, (1 << 1));
/* ISR on Core 0 sends to queue */
xQueueSendFromISR(queue, &byte, &xHigherPriorityTaskWoken);
portYIELD_FROM_ISR(xHigherPriorityTaskWoken); // Must trigger IPI to Core 1

Verification: Enable configUSE_TRACE_FACILITY and check Tracealyzer for cross-core scheduling latency. If the wake-to-run latency exceeds one tick, investigate IPI handling or core affinity constraints.

Debugging Checklist

When a task doesn’t wake after ISR queue send:

StepCheckTool/Method
1xHigherPriorityTaskWoken initialized to pdFALSE?Code review
2portYIELD_FROM_ISR() called with the variable?Code review
3ISR priority <= configMAX_SYSCALL_INTERRUPT_PRIORITY?NVIC config + FreeRTOSConfig.h
4configASSERT() enabled to catch priority violations?configASSERT defined
5Queue handle valid and created before ISR runs?Debugger watch
6Task actually blocked on this queue?eTaskGetState() + queue handle
7Task priority higher than interrupted task?uxTaskPriorityGet()
8configUSE_PREEMPTION enabled?FreeRTOSConfig.h

Runtime Verification with Tracealyzer

Enable configUSE_TRACE_FACILITY and INCLUDE_xTaskGetIdleTaskHandle to capture ISR-to-task interactions:

/* In FreeRTOSConfig.h */
#define configUSE_TRACE_FACILITY 1
#define configUSE_TIMERS 1
#define INCLUDE_xTimerPendFunctionCall 1

In Percepio Tracealyzer, look for:

  • xQueueSendFromISR events (green arrows)
  • xHigherPriorityTaskWoken = pdTRUE (orange marker)
  • Subsequent context switch to the waiting task (yellow block)

If the context switch is missing or delayed by ticks, the yield was not requested or the interrupt priority is wrong.

Debugging with Segger SystemView

For systems without Tracealyzer, Segger SystemView provides similar visibility:

/* In FreeRTOSConfig.h */
#define configUSE_TRACE_FACILITY 1
#define INCLUDE_xTaskGetCurrentTaskHandle 1

SystemView records:

  • ISR entry/exit timestamps
  • xQueueSendFromISR API calls with parameters
  • Task state transitions (Blocked → Ready → Running)
  • Context switch events with core ID (SMP)

Key SystemView markers:

  • OS_ISR_ENTER / OS_ISR_EXIT — ISR boundaries
  • OS_QUEUE_SEND_ISR — Queue send from ISR
  • OS_TASK_SWITCH — Context switch with reason

Hardware-Assisted Debugging

On Cortex-M with DWT/ITM:

/* Minimal ISR tracing via DWT cycle counter */
#define ISR_TRACE_START() DWT->CYCCNT
#define ISR_TRACE_END() (DWT->CYCCNT - ISR_TRACE_START())
void USART2_IRQHandler(void) {
uint32_t start = ISR_TRACE_START();
// ... ISR code ...
uint32_t cycles = ISR_TRACE_END();
if (cycles > ISR_WARN_CYCLES) log_isr_latency(cycles);
}

Measure ISR duration — if it exceeds ~10% of tick period, consider moving work to a task.

Alternative: Direct Task Notifications (Often Better)

For single-value ISR-to-task signaling, direct task notifications are faster and simpler:

/* ISR */
BaseType_t xHigherPriorityTaskWoken = pdFALSE;
vTaskNotifyGiveFromISR(uart_rx_task_handle, &xHigherPriorityTaskWoken);
portYIELD_FROM_ISR(xHigherPriorityTaskWoken);
/* Task */
ulTaskNotifyTake(pdTRUE, portMAX_DELAY); // Wait for notification
process_data();

Advantages:

  • No queue memory overhead
  • ~40% faster than queue send/receive
  • No errQUEUE_FULL — notifications are always delivered (counting semaphore semantics)
  • Same xHigherPriorityTaskWoken / portYIELD_FROM_ISR pattern

When to use queues instead:

  • Multiple data items per ISR (byte streams)
  • Multiple tasks waiting on same data (queue sets)
  • Need queue peek/front/back operations

Queue Sets: Multiple Queues, One Wait

When an ISR must wake a task on any of several queues, use Queue Sets:

/* Create queue set */
QueueSetHandle_t xQueueSet = xQueueCreateSet(3);
/* Add queues to set */
xQueueAddToSet(uart_rx_queue, xQueueSet);
xQueueAddToSet(spi_rx_queue, xQueueSet);
xQueueAddToSet(i2c_event_queue, xQueueSet);
/* ISR posts to specific queue */
xQueueSendFromISR(uart_rx_queue, &byte, &xHigherPriorityTaskWoken);
portYIELD_FROM_ISR(xHigherPriorityTaskWoken);
/* Task waits on *any* queue in set */
QueueHandle_t xActivatedQueue;
xActivatedQueue = xQueueSelectFromSet(xQueueSet, portMAX_DELAY);
if (xActivatedQueue == uart_rx_queue) {
xQueueReceive(uart_rx_queue, &byte, 0);
process_uart_byte(byte);
}

Queue Sets eliminate the “which queue woke me?” polling loop. The xHigherPriorityTaskWoken / portYIELD_FROM_ISR pattern works identically.

Summary

The xHigherPriorityTaskWoken / portYIELD_FROM_ISR pair is the contract between your ISR and the FreeRTOS scheduler. Initialize the variable, pass it to the queue send, pass it to the yield macro. Every time. No exceptions.

PitfallSymptomFix
Uninitialized xHigherPriorityTaskWokenSporadic wake-upInitialize to pdFALSE
Missing portYIELD_FROM_ISRTask wakes on next tick onlyAdd yield call
NULL passed to APIForced yield every ISRUse variable, conditional yield
ISR priority too highconfigASSERT fire / silent failSet priority <= max syscall
Non-FromISR API in ISRCrash / corruptionUse only FromISR APIs
Queue created after ISR enabledNull handle dereferenceCreate queue early, enable IRQ last
Queue full ignoredSilent data lossCheck return, implement overflow policy

Quick Reference Card

ISR CHECKLIST (paste near your interrupt vectors)
☐ BaseType_t xHigherPriorityTaskWoken = pdFALSE;
☐ xQueueSendFromISR(queue, &data, &xHigherPriorityTaskWoken);
☐ if (result != pdPASS) handle_overflow();
☐ portYIELD_FROM_ISR(xHigherPriorityTaskWoken);
☐ ISR priority <= configMAX_SYSCALL_INTERRUPT_PRIORITY
☐ Queue created before NVIC_EnableIRQ()

Root Cause Taxonomy

CategoryTypical CauseDetection Method
InitializationVariable not set to pdFALSECode review, static analysis
Yield omissionportYIELD_FROM_ISR missingCode review, Tracealyzer
PriorityISR > max syscall priorityconfigASSERT, NVIC check
OrderingIRQ enabled before queue initCode review, hard fault
CapacityQueue too small for burstRuntime monitoring, overflow counter
SMPAffinity prevents IPI deliveryTracealyzer cross-core latency

The most pernicious bugs are silent: the code compiles, runs, and mostly works — until a specific timing alignment causes a missed wake-up. Systematic application of the checklist above eliminates the entire class of ISR-to-task synchronization failures.

References

  1. FreeRTOS Kernel Documentation — Queue Management: https://www.freertos.org/Documentation/02-Kernel/04-API-references/06-Queues/00-QueueManagement
  2. FreeRTOS xQueueSendFromISR API Reference: https://www.freertos.org/Documentation/02-Kernel/04-API-references/06-Queues/04-xQueueSendFromISR
  3. FreeRTOS portYIELD_FROM_ISR Macro: https://www.freertos.org/Documentation/02-Kernel/02-Kernel-features/13-Symmetric-multiprocessing-introduction
  4. FreeRTOS Interrupt Management (Cortex-M): https://www.freertos.org/RTOS-Cortex-M3-M4.html
  5. FreeRTOS SMP Kernel Source — queue.c: https://github.com/FreeRTOS/FreeRTOS-Kernel/blob/main/queue.c
  6. STMicroelectronics AN4031 — DMA Controller (queue/ISR patterns): https://www.st.com/content/ccc/resource/technical/document/application_note/27/46/7c/ea/2d/91/40/a9/DM00046011.pdf/files/DM00046011.pdf/jcr:content/translations/en.DM00046011.pdf

Frequently Asked Questions

Why does my FreeRTOS task not wake up after xQueueSendFromISR?

The most common cause is missing or incorrect `portYIELD_FROM_ISR(xHigherPriorityTaskWoken)` call after `xQueueSendFromISR()`. The ISR must request a context switch when a higher-priority task was unblocked.

What is the correct pattern for xHigherPriorityTaskWoken in FreeRTOS ISRs?

Initialize `BaseType_t xHigherPriorityTaskWoken = pdFALSE;` before the API call, pass its address to `xQueueSendFromISR()`, then pass the variable to `portYIELD_FROM_ISR(xHigherPriorityTaskWoken)`. Never pass NULL if you need the wake-up to work.

Can I use portYIELD_FROM_ISR(pdTRUE) instead of the variable?

You can, but it forces a yield every time, causing unnecessary context switches when no task was actually woken. Using the variable is more efficient — it only yields when a higher-priority task was unblocked.

Does FreeRTOS SMP change how xHigherPriorityTaskWoken works?

In SMP, `portYIELD_FROM_ISR()` may need to target a specific core. The variable still works the same way, but the yield macro implementation differs. Check your port's `portYIELD_FROM_ISR` definition for multi-core behavior.

What happens if the ISR priority is above configMAX_SYSCALL_INTERRUPT_PRIORITY?

The `configASSERT()` in `xQueueSendFromISR()` will trigger (if asserts are enabled), and the queue send will silently fail. ISRs calling FreeRTOS APIs must be at or below `configMAX_SYSCALL_INTERRUPT_PRIORITY`.

Tags

freertosisrqueuecontext-switchxhigherprioritytaskwokenportyield-from-isr

Share


Previous Article
Fixing C Integer Promotion Bugs on 8-bit and 16-bit MCUs
Jithin Tom

Jithin Tom

A Closer Look at C/C++, RTOS, and Embedded Systems

Related Posts

Fixing FreeRTOS Timer Task Stall When Command Queue Is Full
Fixing FreeRTOS Timer Task Stall When Command Queue Is Full
November 17, 2026
13 min
© 2026, All Rights Reserved.
Powered By Netlyft

Quick Links

Advertise with usAbout UsContact Us

Social Media