
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.
/* 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.
When xQueueSendFromISR() executes, it performs these steps atomically within a critical section:
errQUEUE_FULL immediately (no blocking in ISR)xTasksWaitingToReceive list — If a task is blocked on this queue*pxHigherPriorityTaskWoken = pdTRUEpdPASS — Data was enqueued successfullyThe critical insight: step 5 only sets the flag. It does not perform a context switch. The ISR continues executing. The scheduler only runs when:
portYIELD_FROM_ISR() was calledThis 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.
FreeRTOS queue send from ISR follows this contract:
BaseType_t xHigherPriorityTaskWoken = pdFALSE;pdTRUE if sending to the queue unblocked a task and that task has higher priority than the currently running taskportYIELD_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.
/* 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);
/* 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.
/* WRONG: NULL means "I don't care if a task was woken" */xQueueSendFromISR(queue, &item, NULL);// No way to know if yield neededportYIELD_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.
/* NVIC configuration — WRONG priority */NVIC_SetPriority(USART2_IRQn, 0); // Priority 0 = highest on Cortex-MNVIC_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);
/* 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.
/* 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);
/* 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++;}
/* 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);}}}
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.
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 coresvTaskCoreAffinitySet() for pinning tasks that service specific interruptsA 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.
When a task doesn’t wake after ISR queue send:
| Step | Check | Tool/Method |
|---|---|---|
| 1 | xHigherPriorityTaskWoken initialized to pdFALSE? | Code review |
| 2 | portYIELD_FROM_ISR() called with the variable? | Code review |
| 3 | ISR priority <= configMAX_SYSCALL_INTERRUPT_PRIORITY? | NVIC config + FreeRTOSConfig.h |
| 4 | configASSERT() enabled to catch priority violations? | configASSERT defined |
| 5 | Queue handle valid and created before ISR runs? | Debugger watch |
| 6 | Task actually blocked on this queue? | eTaskGetState() + queue handle |
| 7 | Task priority higher than interrupted task? | uxTaskPriorityGet() |
| 8 | configUSE_PREEMPTION enabled? | FreeRTOSConfig.h |
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)If the context switch is missing or delayed by ticks, the yield was not requested or the interrupt priority is wrong.
For systems without Tracealyzer, Segger SystemView provides similar visibility:
/* In FreeRTOSConfig.h */#define configUSE_TRACE_FACILITY 1#define INCLUDE_xTaskGetCurrentTaskHandle 1
SystemView records:
xQueueSendFromISR API calls with parametersKey SystemView markers:
OS_ISR_ENTER / OS_ISR_EXIT — ISR boundariesOS_QUEUE_SEND_ISR — Queue send from ISROS_TASK_SWITCH — Context switch with reasonOn 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.
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 notificationprocess_data();
Advantages:
errQUEUE_FULL — notifications are always delivered (counting semaphore semantics)xHigherPriorityTaskWoken / portYIELD_FROM_ISR patternWhen to use queues instead:
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.
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.
| Pitfall | Symptom | Fix |
|---|---|---|
Uninitialized xHigherPriorityTaskWoken | Sporadic wake-up | Initialize to pdFALSE |
Missing portYIELD_FROM_ISR | Task wakes on next tick only | Add yield call |
NULL passed to API | Forced yield every ISR | Use variable, conditional yield |
| ISR priority too high | configASSERT fire / silent fail | Set priority <= max syscall |
| Non-FromISR API in ISR | Crash / corruption | Use only FromISR APIs |
| Queue created after ISR enabled | Null handle dereference | Create queue early, enable IRQ last |
| Queue full ignored | Silent data loss | Check return, implement overflow policy |
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()
| Category | Typical Cause | Detection Method |
|---|---|---|
| Initialization | Variable not set to pdFALSE | Code review, static analysis |
| Yield omission | portYIELD_FROM_ISR missing | Code review, Tracealyzer |
| Priority | ISR > max syscall priority | configASSERT, NVIC check |
| Ordering | IRQ enabled before queue init | Code review, hard fault |
| Capacity | Queue too small for burst | Runtime monitoring, overflow counter |
| SMP | Affinity prevents IPI delivery | Tracealyzer 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.
Quick Links
Legal Stuff





