ISR-safe API functions (FromISR suffix) in FreeRTOS - Step-by-Step Execution

Concept Flow - ISR-safe API functions (FromISR suffix)

Interrupt Occurs

↓

Call FromISR API

↓

Check ISR Context

↓

Perform Safe Operation

↓

Return from ISR

↓

Scheduler Decision

↓

No Switch

↓

Continue

When an interrupt happens, ISR-safe APIs with FromISR suffix are called to safely interact with FreeRTOS from interrupt context, possibly triggering a context switch.

Execution Sample

FreeRTOS

void ISR_Handler() {
  BaseType_t xHigherPriorityTaskWoken = pdFALSE;
  xQueueSendFromISR(queue, &data, &xHigherPriorityTaskWoken);
  portYIELD_FROM_ISR(xHigherPriorityTaskWoken);
}

This code sends data to a queue safely from an ISR and requests a context switch if needed.

Execution Table

Step	Action	Variable Values	Result	Notes
1	Interrupt occurs	xHigherPriorityTaskWoken = pdFALSE	Enter ISR context	ISR starts
2	Call xQueueSendFromISR	queue, &data, &xHigherPriorityTaskWoken	Data queued, xHigherPriorityTaskWoken updated	Safe queue send from ISR
3	Check xHigherPriorityTaskWoken	xHigherPriorityTaskWoken = pdTRUE or pdFALSE	If pdTRUE, request context switch	Determines if higher priority task was woken
4	Call portYIELD_FROM_ISR	xHigherPriorityTaskWoken	Context switch triggered if pdTRUE	Yield from ISR to scheduler
5	Return from ISR	-	ISR ends, possibly switches task	ISR completes execution

💡 ISR completes and returns; if a higher priority task was woken, context switch occurs immediately.

Variable Tracker

Variable	Start	After Step 2	After Step 3	Final
xHigherPriorityTaskWoken	pdFALSE	pdTRUE or pdFALSE	pdTRUE or pdFALSE	pdTRUE or pdFALSE

Key Moments - 3 Insights

Why do we use xHigherPriorityTaskWoken in FromISR functions?

It tells if a higher priority task was woken by the ISR operation, so the scheduler knows if it should switch tasks immediately (see execution_table step 3).

Can we call normal FreeRTOS API functions inside an ISR?

No, normal APIs are not safe in ISR context. FromISR versions are designed to be safe and avoid blocking or unsafe operations (see concept_flow).

What happens if portYIELD_FROM_ISR is not called when xHigherPriorityTaskWoken is true?

The higher priority task will not run immediately after ISR, delaying its execution until the next normal context switch (see execution_table step 4).

Visual Quiz - 3 Questions

Look at the execution_table, what is the value of xHigherPriorityTaskWoken after step 2?

A Always pdTRUE

B pdFALSE

C pdTRUE or pdFALSE

D Undefined

💡 Hint

Check the 'Variable Values' column in step 2 of execution_table.

At which step does the ISR request a context switch if needed?

A Step 4

B Step 1

C Step 3

D Step 5

💡 Hint

Look at the 'Result' column for step 4 in execution_table.

If we forget to call portYIELD_FROM_ISR, what changes in the execution flow?

A ISR will not complete

B No context switch happens immediately after ISR

C xHigherPriorityTaskWoken will be reset

D Queue operation fails

💡 Hint

Refer to key_moments explanation about portYIELD_FROM_ISR importance.

Concept Snapshot

ISR-safe API functions end with FromISR.
They are designed to be called inside interrupts.
Use xHigherPriorityTaskWoken to detect if a higher priority task was woken.
Call portYIELD_FROM_ISR to request immediate context switch.
Normal FreeRTOS APIs are NOT safe inside ISRs.

Full Transcript

When an interrupt occurs, you must use special FreeRTOS API functions that are safe to call from interrupt context. These functions have the suffix FromISR. Inside the ISR, you declare a variable xHigherPriorityTaskWoken initialized to pdFALSE. When calling a FromISR function like xQueueSendFromISR, this variable may be set to pdTRUE if the operation wakes a higher priority task. After the call, you check xHigherPriorityTaskWoken and call portYIELD_FROM_ISR if it is true. This causes the scheduler to switch to the higher priority task immediately after the ISR finishes. If you do not call portYIELD_FROM_ISR, the higher priority task will wait until the next normal context switch. Normal FreeRTOS API functions are not safe to call inside ISRs because they may block or cause unsafe operations. Using FromISR APIs ensures safe and efficient interrupt handling in FreeRTOS.