Operating SystemsReal-Time Operating Systems

RTOS Examples

LevelAdvanced

Duration90 mins

TopicReal-Time Operating Systems

1 / 5

FreeRTOS

The World's Most Deployed RTOS

Every day, billions of embedded devices silently execute their tasks with unwavering precision—from your smart thermostat adjusting temperatures to industrial sensors monitoring critical infrastructure. At the heart of countless such systems lies FreeRTOS, an open-source real-time operating system that has become the de facto standard for microcontroller-based development.

FreeRTOS represents a remarkable achievement in systems software: a full-featured, production-quality RTOS kernel contained in just a handful of source files, consuming as little as 4-9KB of ROM and minimal RAM. This compact footprint, combined with its permissive MIT license, portability across 40+ architectures, and robust feature set, has made FreeRTOS the most widely deployed RTOS in the embedded world.

What You Will Learn

By the end of this page, you will master FreeRTOS architecture, kernel internals, task management, synchronization primitives, memory allocation strategies, and practical development patterns. You'll understand how FreeRTOS achieves deterministic behavior on resource-constrained microcontrollers and why it powers everything from consumer IoT to industrial automation.

FreeRTOS History and Ecosystem

Understanding FreeRTOS's evolution from a hobby project to the dominant embedded RTOS reveals crucial insights about what makes real-time operating systems successful in the embedded space.

Origins and Evolution:

FreeRTOS was created by Richard Barry in 2003 as a response to the high cost and complexity of commercial RTOS solutions. His vision was simple yet revolutionary: provide a professional-quality, free real-time kernel that could run on affordable microcontrollers.

The timeline of FreeRTOS development reflects the evolution of embedded systems themselves:

FreeRTOS Evolution Timeline
Year	Milestone	Significance
2003	Initial Release	First public version targeting PIC, AVR, and ARM7 microcontrollers
2005	Commercial Support	Real Time Engineers Ltd. formed for professional services
2010	FreeRTOS+TCP	First-party TCP/IP stack integration
2017	Amazon Acquisition	AWS acquires FreeRTOS, expands IoT focus
2018	MIT License	Transition from modified GPL enables broader adoption
2020	Symmetric Multiprocessing	SMP kernel variant for multi-core processors
2023	Long-Term Support	LTS releases with 2-year security patches

The FreeRTOS Ecosystem:

FreeRTOS is not merely a kernel—it's an ecosystem of integrated components designed for embedded system development:

FreeRTOS Component Ecosystem

•FreeRTOS Kernel — The core scheduler, providing task management, timing, synchronization, and memory management. This portable kernel runs on 40+ processor architectures.
•FreeRTOS+TCP — A thread-safe, production-quality TCP/IP stack designed specifically for FreeRTOS. Supports DHCP, DNS, TCP, UDP, and zero-copy networking.
•FreeRTOS+FAT — A DOS-compatible FAT12/16/32 file system with long filename support, thread safety, and optional write-through caching.
•FreeRTOS+CLI — Command-line interface library for creating debug and configuration interfaces. Essential for device management and diagnostics.
•AWS IoT Libraries — MQTT client, device shadow, over-the-air updates, and cloud integration for IoT applications.
•coreMQTT/coreHTTP/coreJSON — Lightweight, memory-safe implementations of common protocols for constrained devices.

Amazon FreeRTOS vs. FreeRTOS

Since Amazon's acquisition, there are two related but distinct offerings: FreeRTOS (the RTOS kernel, maintained by the community and Amazon) and Amazon FreeRTOS (a bundled distribution including AWS IoT libraries). The core kernel remains identical—Amazon FreeRTOS simply adds cloud connectivity libraries and reference configurations. For non-cloud applications, the standard FreeRTOS kernel is typically used.

Kernel Architecture

FreeRTOS's architecture exemplifies the principle of minimalist design for maximum portability. Understanding the kernel's internal structure is essential for writing efficient, deterministic real-time applications.

Core Architecture Principles:

FreeRTOS follows a microkernel-inspired design philosophy with several key characteristics:

Minimal Footprint: The kernel compiles to 4-9KB of code, depending on configuration and architecture
Single Address Space: All tasks share the same memory space (MMU optional on supported hardware)
Cooperative and Preemptive Scheduling: Configurable scheduling modes
Tick-Based Timing: Configurable tick rate drives all timing operations
Static or Dynamic Allocation: Choose compile-time or runtime resource creation

Source File Organization:

FreeRTOS's compact codebase is organized for clarity and portability:

FreeRTOS Source Structure
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
FreeRTOS/
├── Source/
│   ├── tasks.c              # Task management (create, delete, scheduling)
│   ├── queue.c              # Queue implementation (basis for all IPC)
│   ├── list.c               # Generic linked list (internal data structure)
│   ├── timers.c             # Software timer management
│   ├── event_groups.c       # Event flag groups
│   ├── stream_buffer.c      # Lightweight message buffers
│   ├── croutine.c           # Co-routines (legacy, rarely used)
│   │
│   ├── portable/            # Architecture-specific code
│   │   ├── GCC/
│   │   │   ├── ARM_CM4F/    # Cortex-M4F port
│   │   │   │   ├── port.c       # Context switching, tick ISR
│   │   │   │   └── portmacro.h  # Architecture definitions
│   │   │   ├── ARM_CM7/     # Cortex-M7 port
│   │   │   └── ...          # Other GCC ports
│   │   │
│   │   └── MemMang/         # Memory allocation schemes
│   │       ├── heap_1.c     # Static allocation only
│   │       ├── heap_2.c     # Best fit, no coalescence
│   │       ├── heap_3.c     # Wraps standard malloc
│   │       ├── heap_4.c     # First fit with coalescence
│   │       └── heap_5.c     # heap_4 with multiple regions
│   │
│   └── include/             # Portable header files
│       ├── FreeRTOS.h       # Main configuration header
│       ├── task.h           # Task API declarations
│       ├── queue.h          # Queue API declarations
│       └── ...              # Other API headers
│
└── FreeRTOSConfig.h         # Project-specific configuration (user creates)

The Scheduler Core:

At the heart of FreeRTOS lies the scheduler, implemented primarily in tasks.c. The scheduler maintains task readiness using a priority-indexed array of ready lists—each priority level has its own doubly-linked list of tasks ready to execute:

// Simplified representation of internal ready list structure
static List_t pxReadyTasksLists[ configMAX_PRIORITIES ];
static List_t xDelayedTaskList1;
static List_t xDelayedTaskList2;
static List_t * volatile pxDelayedTaskList;
static List_t * volatile pxOverflowDelayedTaskList;
static List_t xPendingReadyList;
static List_t xSuspendedTaskList;

This structure enables O(1) scheduling decisions: the scheduler simply examines uxTopReadyPriority to find the highest priority with ready tasks, then selects the next task from that priority's list using round-robin rotation.

Critical Section Implementation

FreeRTOS implements critical sections by manipulating interrupt priorities rather than disabling all interrupts. On Cortex-M, configMAX_SYSCALL_INTERRUPT_PRIORITY defines a threshold—ISRs with higher priority (lower numeric value) continue executing during critical sections, enabling true 'interrupt-nesting' behavior. Only ISRs calling FreeRTOS API functions need to respect this boundary.

Task Management Deep Dive

Tasks are the fundamental units of execution in FreeRTOS. Each task operates as an independent thread of execution with its own stack and context. Understanding task internals is crucial for designing responsive, reliable real-time systems.

Task Control Block (TCB):

Every task is represented internally by a Task Control Block—a structure containing all state required to manage and schedule the task:

Task Control Block (Simplified)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
typedef struct tskTaskControlBlock {
    // Stack pointer - MUST be first member for context switch
    volatile StackType_t *pxTopOfStack;
    
    // List management for ready/blocked/suspended lists
    ListItem_t xStateListItem;
    ListItem_t xEventListItem;
    
    // Task priority (0 = lowest, configMAX_PRIORITIES-1 = highest)
    UBaseType_t uxPriority;
    
    // Stack memory region
    StackType_t *pxStack;
    
    // Task name for debugging
    char pcTaskName[ configMAX_TASK_NAME_LEN ];
    
    // MPU settings (if configUSE_MPU_SUPPORT == 1)
    #if ( portUSING_MPU_WRAPPERS == 1 )
        xMPU_SETTINGS xMPUSettings;
    #endif
    
    // Stack overflow detection
    #if ( ( configCHECK_FOR_STACK_OVERFLOW > 1 ) || ... )
        StackType_t *pxEndOfStack;
    #endif
    
    // Critical section nesting count
    #if ( portCRITICAL_NESTING_IN_TCB == 1 )
        UBaseType_t uxCriticalNesting;
    #endif
    
    // Task notification values (up to configTASK_NOTIFICATION_ARRAY_ENTRIES)
    #if ( configUSE_TASK_NOTIFICATIONS == 1 )
        volatile uint32_t ulNotifiedValue[ configTASK_NOTIFICATION_ARRAY_ENTRIES ];
        volatile uint8_t ucNotifyState[ configTASK_NOTIFICATION_ARRAY_ENTRIES ];
    #endif
    
    // Runtime statistics
    #if ( configGENERATE_RUN_TIME_STATS == 1 )
        configRUN_TIME_COUNTER_TYPE ulRunTimeCounter;
    #endif
    
} tskTCB;

Task States and Transitions:

FreeRTOS tasks exist in one of four states, with well-defined transitions between them:

FreeRTOS Task States
State	Description	List Membership	Transition Triggers
Running	Currently executing on the processor	Not in any list (referenced by pxCurrentTCB)	Preemption, yield, block, suspend
Ready	Able to execute but awaiting scheduler selection	pxReadyTasksLists[priority]	Higher-priority task blocks, tick rotation
Blocked	Waiting for temporal or external event	xDelayedTaskList or event-specific list	Timeout expires, event occurs
Suspended	Explicitly suspended, not participating in scheduling	xSuspendedTaskList	Explicit vTaskResume() call

Task Creation Internals:

When xTaskCreate() is called, FreeRTOS performs a carefully orchestrated sequence:

Task Creation Process

•Memory Allocation: Allocate memory for TCB and stack (contiguous or separate based on heap scheme)
•Stack Initialization: Initialize stack with initial register values mimicking a context restore (architecture-specific)
•TCB Initialization: Set priority, name, initialize list items, set stack bounds
•List Item Configuration: Configure xStateListItem.pvOwner and xEventListItem.pvOwner to point to TCB
•Add to Ready List: Insert task into appropriate ready list at specified priority
•Yield if Necessary: If new task has higher priority than current, trigger context switch

Task Creation Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
// Task function prototype
void vSensorTask(void *pvParameters);
 
// Task creation with all parameters
TaskHandle_t xSensorTaskHandle = NULL;
 
BaseType_t xReturned = xTaskCreate(
    vSensorTask,           // Task function pointer
    "SensorTask",          // Task name (for debugging)
    configMINIMAL_STACK_SIZE * 2,  // Stack depth in words
    (void *)&sensorConfig, // Parameter passed to task
    tskIDLE_PRIORITY + 2,  // Priority (0 = lowest)
    &xSensorTaskHandle     // Task handle output (optional)
);
 
if (xReturned != pdPASS) {
    // Task creation failed - likely heap exhausted
    configASSERT(0);
}
 
// Static allocation alternative (no heap required)
StaticTask_t xTaskBuffer;
StackType_t xStack[256];
 
xTaskCreateStatic(
    vSensorTask,
    "SensorTask",
    256,                    // Stack size in words
    NULL,
    tskIDLE_PRIORITY + 2,
    xStack,                 // Pre-allocated stack
    &xTaskBuffer            // Pre-allocated TCB
);

Stack Sizing is Critical

Stack overflow is the most common failure mode in FreeRTOS applications. Each task's stack must accommodate: local variables, function call depth, ISR stacking (on Cortex-M), and any RTOS calls. Use uxTaskGetStackHighWaterMark() to measure actual usage and configure configCHECK_FOR_STACK_OVERFLOW during development.

Synchronization and Inter-Task Communication

Real-time systems require robust mechanisms for tasks to synchronize and communicate. FreeRTOS provides a comprehensive set of primitives, all built upon a unified queue infrastructure.

The Queue Abstraction:

Queues are the fundamental IPC mechanism in FreeRTOS. Semaphores, mutexes, and event groups are all implemented using or extending the queue primitive:

FreeRTOS Synchronization Primitives
Primitive	Implementation	Primary Use Case	Key Characteristics
Queue	Circular buffer with blocking	Data passing between tasks	FIFO, configurable item size, thread-safe
Binary Semaphore	Queue of length 1, item size 0	Event signaling (ISR to task)	Cannot cause priority inversion
Counting Semaphore	Queue of length N, item size 0	Resource counting, event counting	Initial count configurable
Mutex	Binary semaphore + ownership	Mutual exclusion	Priority inheritance to prevent inversion
Recursive Mutex	Mutex + nesting count	Nested lock acquisition	Same task can acquire multiple times
Event Groups	Bit flags + waiting list	Multi-condition synchronization	Wait for any/all bits, atomic set/clear
Task Notifications	TCB-embedded signaling	Ultra-light unary events	Fastest mechanism, limited flexibility

Queue Implementation Details:

Queues are implemented as circular buffers with blocking support. The structure maintains head/tail pointers and waiting task lists:

Queue Usage Patterns
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
// Create a queue holding 10 sensor readings
typedef struct {
    uint32_t timestamp;
    int16_t  temperature;
    uint16_t sensorId;
} SensorReading_t;
 
QueueHandle_t xSensorQueue = xQueueCreate(10, sizeof(SensorReading_t));
 
// Producer task: sends sensor readings
void vSensorProducerTask(void *pvParameters) {
    SensorReading_t reading;
    
    for (;;) {
        reading.timestamp = xTaskGetTickCount();
        reading.temperature = readTemperatureSensor();
        reading.sensorId = SENSOR_ID_TEMP_1;
        
        // Block up to 100ms if queue is full
        if (xQueueSend(xSensorQueue, &reading, pdMS_TO_TICKS(100)) != pdPASS) {
            // Queue full - log or handle overflow
            incrementOverflowCounter();
        }
        
        vTaskDelay(pdMS_TO_TICKS(50));  // 20 Hz sampling
    }
}
 
// Consumer task: processes sensor readings
void vSensorConsumerTask(void *pvParameters) {
    SensorReading_t reading;
    
    for (;;) {
        // Block indefinitely until reading available
        if (xQueueReceive(xSensorQueue, &reading, portMAX_DELAY) == pdPASS) {
            processSensorReading(&reading);
        }
    }
}
 
// ISR-safe queue send (for interrupt context)
void SENSOR_IRQHandler(void) {
    SensorReading_t reading;
    BaseType_t xHigherPriorityTaskWoken = pdFALSE;
    
    reading.timestamp = xTaskGetTickCountFromISR();
    reading.temperature = SENSOR->DATA_REG;
    reading.sensorId = SENSOR_ID_TEMP_1;
    
    xQueueSendFromISR(xSensorQueue, &reading, &xHigherPriorityTaskWoken);
    
    // Yield to higher-priority task if one was woken
    portYIELD_FROM_ISR(xHigherPriorityTaskWoken);
}

Mutex with Priority Inheritance:

Mutexes include automatic priority inheritance to mitigate priority inversion. When a high-priority task blocks on a mutex held by a lower-priority task, the holder's priority is temporarily elevated:

Mutex with Priority Inheritance
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
// Create a mutex for shared I2C bus access
SemaphoreHandle_t xI2CMutex = xSemaphoreCreateMutex();
 
// Protected I2C transaction
BaseType_t xPerformI2CTransaction(uint8_t addr, uint8_t *data, size_t len) {
    BaseType_t xResult = pdFAIL;
    
    // Acquire mutex with 100ms timeout
    // If a lower-priority task holds this mutex, its priority will be
    // temporarily raised to match the calling task's priority
    if (xSemaphoreTake(xI2CMutex, pdMS_TO_TICKS(100)) == pdTRUE) {
        
        // Critical section - exclusive I2C access
        i2c_start();
        xResult = i2c_write(addr, data, len);
        i2c_stop();
        
        // MUST release mutex - failing to do so permanently blocks other tasks
        xSemaphoreGive(xI2CMutex);
    }
    
    return xResult;
}
 
// Multiple tasks can safely call xPerformI2CTransaction() concurrently

Task Notifications: The Fastest Primitive

Task notifications are 45% faster than binary semaphores and use no additional RAM. Each task has a 32-bit notification value embedded in its TCB. Use xTaskNotifyGive()/ulTaskNotifyTake() for simple signaling or xTaskNotify()/xTaskNotifyWait() for value passing. Ideal for ISR-to-task signaling with minimal overhead.

Memory Management Strategies

Memory management in real-time systems requires careful consideration of determinism, fragmentation, and failure handling. FreeRTOS provides five heap implementations, each with distinct characteristics:

Heap Implementation Comparison:

FreeRTOS Heap Schemes
Scheme	Algorithm	Free Support	Coalescence	Determinism	Best For
heap_1	Simple increment	❌ No	N/A	⭐⭐⭐⭐⭐	Static allocation patterns
heap_2	Best fit	✅ Yes	❌ No	⭐⭐⭐⭐	Fixed-size allocations
heap_3	Wraps malloc()	✅ Yes	Depends	⭐⭐	Integration with libc
heap_4	First fit	✅ Yes	✅ Yes	⭐⭐⭐	General purpose (recommended)
heap_5	First fit	✅ Yes	✅ Yes	⭐⭐⭐	Non-contiguous memory regions

heap_4 Internals:

The most commonly used scheme, heap_4, implements a first-fit allocator with adjacent block coalescence. The heap is organized as a linked list of free blocks:

heap_4 Block Structure
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
// Block header structure (8 bytes on 32-bit systems)
typedef struct A_BLOCK_LINK {
    struct A_BLOCK_LINK *pxNextFreeBlock;  // Next free block in list
    size_t xBlockSize;                      // Size including header
} BlockLink_t;
 
// Memory layout after several allocations:
//
// |------ Heap Memory ----------------------------------------------|
// |                                                                 |
// | [HDR|Allocated] [HDR|    FREE    ] [HDR|Allocated] [HDR| FREE ] |
// |      Task A            500 bytes       Queue           200 bytes|
// |                            ↓                             ↓      |
// |                      pxFirstFreeBlock ──────────────→ pxEnd     |
// |                                                                 |
// |-----------------------------------------------------------------|
 
// Allocation process:
// 1. Walk free list to find first block >= requested size + header
// 2. If block significantly larger, split and return remainder to list
// 3. Remove allocated portion from free list
// 4. Return pointer to usable memory (after header)
 
// Deallocation process:
// 1. Insert freed block back into free list (sorted by address)
// 2. Check if adjacent to previous free block → merge
// 3. Check if adjacent to next free block → merge

heap_5 for Non-Contiguous Memory:

Many microcontrollers have memory at non-contiguous addresses (internal SRAM, external RAM, CCM on STM32). heap_5 allows defining multiple heap regions:

heap_5 Configuration
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
// Define heap regions before any FreeRTOS calls
// Typically in startup code or main() before vTaskStartScheduler()
 
// Memory regions available on STM32F4
extern uint8_t __heap_start__;  // From linker script
extern uint8_t __heap_end__;
 
const HeapRegion_t xHeapRegions[] = {
    // Region 1: Internal SRAM (128KB)
    { (uint8_t *)&__heap_start__, (size_t)(&__heap_end__ - &__heap_start__) },
    
    // Region 2: CCM RAM (64KB, close-coupled for fast access)
    { (uint8_t *)0x10000000, 64 * 1024 },
    
    // Region 3: External SDRAM (if configured)
    { (uint8_t *)0xC0000000, 8 * 1024 * 1024 },
    
    // Terminate list with NULL
    { NULL, 0 }
};
 
int main(void) {
    // Initialize heap before any FreeRTOS calls
    vPortDefineHeapRegions(xHeapRegions);
    
    // Now create tasks, queues, etc.
    xTaskCreate(...);
    
    vTaskStartScheduler();
    
    for (;;); // Should never reach here
}

Static Allocation for Safety-Critical Systems

For DO-178C, IEC 61508, or ISO 26262 certification, dynamic memory allocation is often prohibited or heavily restricted. FreeRTOS supports full static allocation via configSUPPORT_STATIC_ALLOCATION. All kernel objects (tasks, queues, semaphores) can be created from pre-allocated memory, enabling deterministic memory usage and eliminating allocation failure paths.

Configuration and Porting

FreeRTOS's portability stems from its clean separation between portable kernel code and architecture-specific ports. Understanding this structure is essential for both configuration and potential custom porting.

FreeRTOSConfig.h — The Configuration Hub:

Every FreeRTOS project requires a FreeRTOSConfig.h file containing project-specific settings. A comprehensive configuration might include:

FreeRTOSConfig.h (Production Template)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
#ifndef FREERTOS_CONFIG_H
#define FREERTOS_CONFIG_H
 
/* Scheduler Configuration */
#define configUSE_PREEMPTION                    1
#define configUSE_PORT_OPTIMISED_TASK_SELECTION 1
#define configUSE_TICKLESS_IDLE                 0  // Enable for low power
#define configCPU_CLOCK_HZ                      ( 168000000UL )  // 168 MHz STM32F4
#define configTICK_RATE_HZ                      ( 1000 )  // 1ms tick
#define configMAX_PRIORITIES                    ( 7 )
#define configMINIMAL_STACK_SIZE                ( 128 )
#define configTOTAL_HEAP_SIZE                   ( 32 * 1024 )
 
/* Feature Inclusion */
#define configUSE_MUTEXES                       1
#define configUSE_RECURSIVE_MUTEXES             1
#define configUSE_COUNTING_SEMAPHORES           1
#define configUSE_QUEUE_SETS                    0
#define configUSE_TASK_NOTIFICATIONS            1
#define configTASK_NOTIFICATION_ARRAY_ENTRIES   3
#define configUSE_TIMERS                        1
#define configTIMER_TASK_PRIORITY               ( configMAX_PRIORITIES - 1 )
#define configTIMER_QUEUE_LENGTH                10
#define configTIMER_TASK_STACK_DEPTH            ( configMINIMAL_STACK_SIZE * 2 )
 
/* Memory Allocation */
#define configSUPPORT_STATIC_ALLOCATION         1
#define configSUPPORT_DYNAMIC_ALLOCATION        1
 
/* Hook Functions */
#define configUSE_IDLE_HOOK                     1
#define configUSE_TICK_HOOK                     0
#define configUSE_MALLOC_FAILED_HOOK            1
#define configCHECK_FOR_STACK_OVERFLOW          2
 
/* Debug and Statistics */
#define configUSE_TRACE_FACILITY                1
#define configUSE_STATS_FORMATTING_FUNCTIONS    1
#define configGENERATE_RUN_TIME_STATS           1
#define portCONFIGURE_TIMER_FOR_RUN_TIME_STATS()  configureTimerForRunTimeStats()
#define portGET_RUN_TIME_COUNTER_VALUE()        getRunTimeCounterValue()
 
/* Cortex-M Specific */
#define configPRIO_BITS                         4  // STM32 uses 4 priority bits
#define configLIBRARY_LOWEST_INTERRUPT_PRIORITY 15
#define configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY 5
#define configKERNEL_INTERRUPT_PRIORITY         ( configLIBRARY_LOWEST_INTERRUPT_PRIORITY << (8 - configPRIO_BITS) )
#define configMAX_SYSCALL_INTERRUPT_PRIORITY    ( configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY << (8 - configPRIO_BITS) )
 
/* Assert for development */
#define configASSERT( x ) if( ( x ) == 0 ) { taskDISABLE_INTERRUPTS(); for(;;); }
 
/* API function inclusion */
#define INCLUDE_vTaskPrioritySet                1
#define INCLUDE_uxTaskPriorityGet               1
#define INCLUDE_vTaskDelete                     1
#define INCLUDE_vTaskSuspend                    1
#define INCLUDE_xResumeFromISR                  1
#define INCLUDE_vTaskDelayUntil                 1
#define INCLUDE_vTaskDelay                      1
#define INCLUDE_xTaskGetSchedulerState          1
#define INCLUDE_uxTaskGetStackHighWaterMark     1
 
#endif /* FREERTOS_CONFIG_H */

Port Layer Responsibilities:

Each processor architecture requires a port consisting of port.c and portmacro.h. The port implements:

Port Layer Components

•pxPortInitialiseStack() — Initialize a task's stack frame to appear as if the task was previously interrupted mid-execution
•xPortSysTickHandler() — Tick interrupt handler, increments tick count and checks for context switch
•xPortPendSVHandler() — Context switch implementation, saves/restores full CPU context
•vPortSVCHandler() — Supervisor call handler, starts first task during scheduler initialization
•portYIELD() — Trigger context switch request (typically pending PendSV on Cortex-M)
•portENTER_CRITICAL() / portEXIT_CRITICAL() — Disable/enable interrupts up to syscall priority
•portTICK_PERIOD_MS — Macro defining milliseconds per tick for timing conversions

Leveraging Manufacturer BSPs

Most microcontroller vendors (STMicroelectronics, NXP, Nordic, TI) provide pre-configured FreeRTOS integrations with their HAL libraries. These include optimized ports, configuration templates, and example projects. Starting from vendor BSPs significantly accelerates development and ensures correct interrupt priority configuration.

Best Practices and Design Patterns

Years of industry experience have established proven patterns for FreeRTOS application development. Adhering to these practices ensures robust, maintainable real-time systems.

Task Design Principles:

Recommended Practices

•Each task has single, well-defined responsibility
•Use infinite loops with blocking calls
•Place shortest deadline tasks at highest priority
•Minimize time spent at high priority
•Use software timers for periodic work
•Profile stack usage during development

Anti-Patterns to Avoid

•Busy-waiting or polling without yielding
•Blocking in ISRs (never!)
•Holding mutexes across long operations
•Creating/deleting tasks at runtime frequently
•Ignoring function return values
•Using vTaskDelete() on running task carelessly

ISR-to-Task Deferred Processing Pattern:

The canonical pattern for handling hardware interrupts in FreeRTOS:

Deferred Interrupt Processing
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
// ISR-safe task notification for deferred processing
TaskHandle_t xUARTTaskHandle;
 
// Runs in interrupt context - keep FAST
void USART1_IRQHandler(void) {
    BaseType_t xHigherPriorityTaskWoken = pdFALSE;
    
    if (USART1->SR & USART_SR_RXNE) {
        uint8_t byte = USART1->DR;  // Read clears interrupt
        
        // Minimal work in ISR: just buffer the byte
        rxBuffer[rxHead++] = byte;
        rxHead &= RX_BUFFER_MASK;  // Circular buffer
        
        // Wake processing task
        vTaskNotifyGiveFromISR(xUARTTaskHandle, &xHigherPriorityTaskWoken);
    }
    
    portYIELD_FROM_ISR(xHigherPriorityTaskWoken);
}
 
// UART processing task - handles heavy lifting
void vUARTProcessingTask(void *pvParameters) {
    for (;;) {
        // Block until ISR signals data available
        ulTaskNotifyTake(pdTRUE, portMAX_DELAY);
        
        // Process all buffered bytes
        while (rxTail != rxHead) {
            uint8_t byte = rxBuffer[rxTail++];
            rxTail &= RX_BUFFER_MASK;
            
            // Heavy processing here (parsing, validation, etc.)
            processReceivedByte(byte);
        }
    }
}

Resource Management Pattern:

Centralize shared resources with dedicated handler tasks:

Resource Handler Pattern
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
// Resource handler for SPI flash
typedef enum {
    FLASH_CMD_READ,
    FLASH_CMD_WRITE,
    FLASH_CMD_ERASE
} FlashCommand_t;
 
typedef struct {
    FlashCommand_t command;
    uint32_t address;
    uint8_t *buffer;
    size_t length;
    TaskHandle_t requestingTask;
    BaseType_t result;
} FlashRequest_t;
 
QueueHandle_t xFlashQueue;
static SemaphoreHandle_t xFlashComplete;
 
// Flash handler task - exclusive SPI access
void vFlashHandlerTask(void *pvParameters) {
    FlashRequest_t request;
    
    for (;;) {
        if (xQueueReceive(xFlashQueue, &request, portMAX_DELAY) == pdPASS) {
            switch (request.command) {
                case FLASH_CMD_READ:
                    request.result = spiFlashRead(request.address, 
                                                   request.buffer, 
                                                   request.length);
                    break;
                case FLASH_CMD_WRITE:
                    request.result = spiFlashWrite(request.address, 
                                                    request.buffer, 
                                                    request.length);
                    break;
                case FLASH_CMD_ERASE:
                    request.result = spiFlashErase(request.address);
                    break;
            }
            
            // Notify requesting task of completion
            xTaskNotify(request.requestingTask, 
                       request.result, 
                       eSetValueWithOverwrite);
        }
    }
}
 
// Client API - called from any task
BaseType_t flashRead(uint32_t addr, uint8_t *buf, size_t len) {
    FlashRequest_t request = {
        .command = FLASH_CMD_READ,
        .address = addr,
        .buffer = buf,
        .length = len,
        .requestingTask = xTaskGetCurrentTaskHandle()
    };
    
    xQueueSend(xFlashQueue, &request, portMAX_DELAY);
    
    // Wait for completion notification
    uint32_t result;
    xTaskNotifyWait(0, ULONG_MAX, &result, portMAX_DELAY);
    
    return (BaseType_t)result;
}

Debugging Tools

Enable configUSE_TRACE_FACILITY and vTaskList()/vTaskGetRunTimeStats() during development for task state inspection. For advanced tracing, integrate Percepio Tracealyzer or SEGGER SystemView—both provide real-time visualization of task execution, queue operations, and timing analysis.

Summary: FreeRTOS Mastery

FreeRTOS has earned its position as the dominant RTOS for microcontrollers through principled design, minimal footprint, and exceptional portability. Let's consolidate the key concepts:

Key Takeaways

•Minimal Yet Complete — 4-9KB kernel provides full preemptive multitasking, synchronization, and timing services
•Priority-Based Scheduling — Highest ready priority always runs; round-robin within priority levels
•Unified IPC Model — Queues form the foundation; semaphores and mutexes are specialized queue types
•Flexible Memory — Five heap schemes from static-only to multi-region dynamic allocation
•Deterministic Design — Bounded execution times for kernel operations enable real-time guarantees
•Portability — 40+ architectures with clean port abstraction for custom targets

What's Next:

With FreeRTOS fundamentals mastered, we turn to VxWorks—the aerospace and defense industry standard that powers satellites, aircraft, and mission-critical infrastructure. VxWorks represents the opposite end of the RTOS spectrum: a commercial, certified, feature-rich platform where reliability literally means life or death.

Page Complete

You now possess professional-grade understanding of FreeRTOS architecture, APIs, and best practices. Whether developing IoT devices, industrial controllers, or prototyping embedded systems, you have the foundation to build robust real-time applications.

1 / 5

Loading learning content...

Operating SystemsReal-Time Operating Systems

RTOS Examples

LevelAdvanced

Duration90 mins

TopicReal-Time Operating Systems

1 / 5

FreeRTOS

The World's Most Deployed RTOS

What You Will Learn

FreeRTOS History and Ecosystem

Understanding FreeRTOS's evolution from a hobby project to the dominant embedded RTOS reveals crucial insights about what makes real-time operating systems successful in the embedded space.

Origins and Evolution:

The timeline of FreeRTOS development reflects the evolution of embedded systems themselves:

FreeRTOS Evolution Timeline
Year	Milestone	Significance
2003	Initial Release	First public version targeting PIC, AVR, and ARM7 microcontrollers
2005	Commercial Support	Real Time Engineers Ltd. formed for professional services
2010	FreeRTOS+TCP	First-party TCP/IP stack integration
2017	Amazon Acquisition	AWS acquires FreeRTOS, expands IoT focus
2018	MIT License	Transition from modified GPL enables broader adoption
2020	Symmetric Multiprocessing	SMP kernel variant for multi-core processors
2023	Long-Term Support	LTS releases with 2-year security patches

The FreeRTOS Ecosystem:

FreeRTOS is not merely a kernel—it's an ecosystem of integrated components designed for embedded system development:

FreeRTOS Component Ecosystem

•FreeRTOS Kernel — The core scheduler, providing task management, timing, synchronization, and memory management. This portable kernel runs on 40+ processor architectures.
•FreeRTOS+TCP — A thread-safe, production-quality TCP/IP stack designed specifically for FreeRTOS. Supports DHCP, DNS, TCP, UDP, and zero-copy networking.
•FreeRTOS+FAT — A DOS-compatible FAT12/16/32 file system with long filename support, thread safety, and optional write-through caching.
•FreeRTOS+CLI — Command-line interface library for creating debug and configuration interfaces. Essential for device management and diagnostics.
•AWS IoT Libraries — MQTT client, device shadow, over-the-air updates, and cloud integration for IoT applications.
•coreMQTT/coreHTTP/coreJSON — Lightweight, memory-safe implementations of common protocols for constrained devices.

Amazon FreeRTOS vs. FreeRTOS

Kernel Architecture

Core Architecture Principles:

FreeRTOS follows a microkernel-inspired design philosophy with several key characteristics:

Minimal Footprint: The kernel compiles to 4-9KB of code, depending on configuration and architecture
Single Address Space: All tasks share the same memory space (MMU optional on supported hardware)
Cooperative and Preemptive Scheduling: Configurable scheduling modes
Tick-Based Timing: Configurable tick rate drives all timing operations
Static or Dynamic Allocation: Choose compile-time or runtime resource creation

Source File Organization:

FreeRTOS's compact codebase is organized for clarity and portability:

FreeRTOS Source Structure
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
FreeRTOS/
├── Source/
│   ├── tasks.c              # Task management (create, delete, scheduling)
│   ├── queue.c              # Queue implementation (basis for all IPC)
│   ├── list.c               # Generic linked list (internal data structure)
│   ├── timers.c             # Software timer management
│   ├── event_groups.c       # Event flag groups
│   ├── stream_buffer.c      # Lightweight message buffers
│   ├── croutine.c           # Co-routines (legacy, rarely used)
│   │
│   ├── portable/            # Architecture-specific code
│   │   ├── GCC/
│   │   │   ├── ARM_CM4F/    # Cortex-M4F port
│   │   │   │   ├── port.c       # Context switching, tick ISR
│   │   │   │   └── portmacro.h  # Architecture definitions
│   │   │   ├── ARM_CM7/     # Cortex-M7 port
│   │   │   └── ...          # Other GCC ports
│   │   │
│   │   └── MemMang/         # Memory allocation schemes
│   │       ├── heap_1.c     # Static allocation only
│   │       ├── heap_2.c     # Best fit, no coalescence
│   │       ├── heap_3.c     # Wraps standard malloc
│   │       ├── heap_4.c     # First fit with coalescence
│   │       └── heap_5.c     # heap_4 with multiple regions
│   │
│   └── include/             # Portable header files
│       ├── FreeRTOS.h       # Main configuration header
│       ├── task.h           # Task API declarations
│       ├── queue.h          # Queue API declarations
│       └── ...              # Other API headers
│
└── FreeRTOSConfig.h         # Project-specific configuration (user creates)

The Scheduler Core:

// Simplified representation of internal ready list structure
static List_t pxReadyTasksLists[ configMAX_PRIORITIES ];
static List_t xDelayedTaskList1;
static List_t xDelayedTaskList2;
static List_t * volatile pxDelayedTaskList;
static List_t * volatile pxOverflowDelayedTaskList;
static List_t xPendingReadyList;
static List_t xSuspendedTaskList;

Critical Section Implementation

Task Management Deep Dive

Task Control Block (TCB):

Every task is represented internally by a Task Control Block—a structure containing all state required to manage and schedule the task:

Task Control Block (Simplified)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
typedef struct tskTaskControlBlock {
    // Stack pointer - MUST be first member for context switch
    volatile StackType_t *pxTopOfStack;
    
    // List management for ready/blocked/suspended lists
    ListItem_t xStateListItem;
    ListItem_t xEventListItem;
    
    // Task priority (0 = lowest, configMAX_PRIORITIES-1 = highest)
    UBaseType_t uxPriority;
    
    // Stack memory region
    StackType_t *pxStack;
    
    // Task name for debugging
    char pcTaskName[ configMAX_TASK_NAME_LEN ];
    
    // MPU settings (if configUSE_MPU_SUPPORT == 1)
    #if ( portUSING_MPU_WRAPPERS == 1 )
        xMPU_SETTINGS xMPUSettings;
    #endif
    
    // Stack overflow detection
    #if ( ( configCHECK_FOR_STACK_OVERFLOW > 1 ) || ... )
        StackType_t *pxEndOfStack;
    #endif
    
    // Critical section nesting count
    #if ( portCRITICAL_NESTING_IN_TCB == 1 )
        UBaseType_t uxCriticalNesting;
    #endif
    
    // Task notification values (up to configTASK_NOTIFICATION_ARRAY_ENTRIES)
    #if ( configUSE_TASK_NOTIFICATIONS == 1 )
        volatile uint32_t ulNotifiedValue[ configTASK_NOTIFICATION_ARRAY_ENTRIES ];
        volatile uint8_t ucNotifyState[ configTASK_NOTIFICATION_ARRAY_ENTRIES ];
    #endif
    
    // Runtime statistics
    #if ( configGENERATE_RUN_TIME_STATS == 1 )
        configRUN_TIME_COUNTER_TYPE ulRunTimeCounter;
    #endif
    
} tskTCB;

Task States and Transitions:

FreeRTOS tasks exist in one of four states, with well-defined transitions between them:

FreeRTOS Task States
State	Description	List Membership	Transition Triggers
Running	Currently executing on the processor	Not in any list (referenced by pxCurrentTCB)	Preemption, yield, block, suspend
Ready	Able to execute but awaiting scheduler selection	pxReadyTasksLists[priority]	Higher-priority task blocks, tick rotation
Blocked	Waiting for temporal or external event	xDelayedTaskList or event-specific list	Timeout expires, event occurs
Suspended	Explicitly suspended, not participating in scheduling	xSuspendedTaskList	Explicit vTaskResume() call

Task Creation Internals:

When xTaskCreate() is called, FreeRTOS performs a carefully orchestrated sequence:

Task Creation Process

•Memory Allocation: Allocate memory for TCB and stack (contiguous or separate based on heap scheme)
•Stack Initialization: Initialize stack with initial register values mimicking a context restore (architecture-specific)
•TCB Initialization: Set priority, name, initialize list items, set stack bounds
•List Item Configuration: Configure xStateListItem.pvOwner and xEventListItem.pvOwner to point to TCB
•Add to Ready List: Insert task into appropriate ready list at specified priority
•Yield if Necessary: If new task has higher priority than current, trigger context switch

Task Creation Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
// Task function prototype
void vSensorTask(void *pvParameters);
 
// Task creation with all parameters
TaskHandle_t xSensorTaskHandle = NULL;
 
BaseType_t xReturned = xTaskCreate(
    vSensorTask,           // Task function pointer
    "SensorTask",          // Task name (for debugging)
    configMINIMAL_STACK_SIZE * 2,  // Stack depth in words
    (void *)&sensorConfig, // Parameter passed to task
    tskIDLE_PRIORITY + 2,  // Priority (0 = lowest)
    &xSensorTaskHandle     // Task handle output (optional)
);
 
if (xReturned != pdPASS) {
    // Task creation failed - likely heap exhausted
    configASSERT(0);
}
 
// Static allocation alternative (no heap required)
StaticTask_t xTaskBuffer;
StackType_t xStack[256];
 
xTaskCreateStatic(
    vSensorTask,
    "SensorTask",
    256,                    // Stack size in words
    NULL,
    tskIDLE_PRIORITY + 2,
    xStack,                 // Pre-allocated stack
    &xTaskBuffer            // Pre-allocated TCB
);

Stack Sizing is Critical

Synchronization and Inter-Task Communication

Real-time systems require robust mechanisms for tasks to synchronize and communicate. FreeRTOS provides a comprehensive set of primitives, all built upon a unified queue infrastructure.

The Queue Abstraction:

Queues are the fundamental IPC mechanism in FreeRTOS. Semaphores, mutexes, and event groups are all implemented using or extending the queue primitive:

FreeRTOS Synchronization Primitives
Primitive	Implementation	Primary Use Case	Key Characteristics
Queue	Circular buffer with blocking	Data passing between tasks	FIFO, configurable item size, thread-safe
Binary Semaphore	Queue of length 1, item size 0	Event signaling (ISR to task)	Cannot cause priority inversion
Counting Semaphore	Queue of length N, item size 0	Resource counting, event counting	Initial count configurable
Mutex	Binary semaphore + ownership	Mutual exclusion	Priority inheritance to prevent inversion
Recursive Mutex	Mutex + nesting count	Nested lock acquisition	Same task can acquire multiple times
Event Groups	Bit flags + waiting list	Multi-condition synchronization	Wait for any/all bits, atomic set/clear
Task Notifications	TCB-embedded signaling	Ultra-light unary events	Fastest mechanism, limited flexibility

Queue Implementation Details:

Queues are implemented as circular buffers with blocking support. The structure maintains head/tail pointers and waiting task lists:

Queue Usage Patterns
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
// Create a queue holding 10 sensor readings
typedef struct {
    uint32_t timestamp;
    int16_t  temperature;
    uint16_t sensorId;
} SensorReading_t;
 
QueueHandle_t xSensorQueue = xQueueCreate(10, sizeof(SensorReading_t));
 
// Producer task: sends sensor readings
void vSensorProducerTask(void *pvParameters) {
    SensorReading_t reading;
    
    for (;;) {
        reading.timestamp = xTaskGetTickCount();
        reading.temperature = readTemperatureSensor();
        reading.sensorId = SENSOR_ID_TEMP_1;
        
        // Block up to 100ms if queue is full
        if (xQueueSend(xSensorQueue, &reading, pdMS_TO_TICKS(100)) != pdPASS) {
            // Queue full - log or handle overflow
            incrementOverflowCounter();
        }
        
        vTaskDelay(pdMS_TO_TICKS(50));  // 20 Hz sampling
    }
}
 
// Consumer task: processes sensor readings
void vSensorConsumerTask(void *pvParameters) {
    SensorReading_t reading;
    
    for (;;) {
        // Block indefinitely until reading available
        if (xQueueReceive(xSensorQueue, &reading, portMAX_DELAY) == pdPASS) {
            processSensorReading(&reading);
        }
    }
}
 
// ISR-safe queue send (for interrupt context)
void SENSOR_IRQHandler(void) {
    SensorReading_t reading;
    BaseType_t xHigherPriorityTaskWoken = pdFALSE;
    
    reading.timestamp = xTaskGetTickCountFromISR();
    reading.temperature = SENSOR->DATA_REG;
    reading.sensorId = SENSOR_ID_TEMP_1;
    
    xQueueSendFromISR(xSensorQueue, &reading, &xHigherPriorityTaskWoken);
    
    // Yield to higher-priority task if one was woken
    portYIELD_FROM_ISR(xHigherPriorityTaskWoken);
}

Mutex with Priority Inheritance:

Mutex with Priority Inheritance
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
// Create a mutex for shared I2C bus access
SemaphoreHandle_t xI2CMutex = xSemaphoreCreateMutex();
 
// Protected I2C transaction
BaseType_t xPerformI2CTransaction(uint8_t addr, uint8_t *data, size_t len) {
    BaseType_t xResult = pdFAIL;
    
    // Acquire mutex with 100ms timeout
    // If a lower-priority task holds this mutex, its priority will be
    // temporarily raised to match the calling task's priority
    if (xSemaphoreTake(xI2CMutex, pdMS_TO_TICKS(100)) == pdTRUE) {
        
        // Critical section - exclusive I2C access
        i2c_start();
        xResult = i2c_write(addr, data, len);
        i2c_stop();
        
        // MUST release mutex - failing to do so permanently blocks other tasks
        xSemaphoreGive(xI2CMutex);
    }
    
    return xResult;
}
 
// Multiple tasks can safely call xPerformI2CTransaction() concurrently

Task Notifications: The Fastest Primitive

Memory Management Strategies

Heap Implementation Comparison:

FreeRTOS Heap Schemes
Scheme	Algorithm	Free Support	Coalescence	Determinism	Best For
heap_1	Simple increment	❌ No	N/A	⭐⭐⭐⭐⭐	Static allocation patterns
heap_2	Best fit	✅ Yes	❌ No	⭐⭐⭐⭐	Fixed-size allocations
heap_3	Wraps malloc()	✅ Yes	Depends	⭐⭐	Integration with libc
heap_4	First fit	✅ Yes	✅ Yes	⭐⭐⭐	General purpose (recommended)
heap_5	First fit	✅ Yes	✅ Yes	⭐⭐⭐	Non-contiguous memory regions

heap_4 Internals:

The most commonly used scheme, heap_4, implements a first-fit allocator with adjacent block coalescence. The heap is organized as a linked list of free blocks:

heap_4 Block Structure
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
// Block header structure (8 bytes on 32-bit systems)
typedef struct A_BLOCK_LINK {
    struct A_BLOCK_LINK *pxNextFreeBlock;  // Next free block in list
    size_t xBlockSize;                      // Size including header
} BlockLink_t;
 
// Memory layout after several allocations:
//
// |------ Heap Memory ----------------------------------------------|
// |                                                                 |
// | [HDR|Allocated] [HDR|    FREE    ] [HDR|Allocated] [HDR| FREE ] |
// |      Task A            500 bytes       Queue           200 bytes|
// |                            ↓                             ↓      |
// |                      pxFirstFreeBlock ──────────────→ pxEnd     |
// |                                                                 |
// |-----------------------------------------------------------------|
 
// Allocation process:
// 1. Walk free list to find first block >= requested size + header
// 2. If block significantly larger, split and return remainder to list
// 3. Remove allocated portion from free list
// 4. Return pointer to usable memory (after header)
 
// Deallocation process:
// 1. Insert freed block back into free list (sorted by address)
// 2. Check if adjacent to previous free block → merge
// 3. Check if adjacent to next free block → merge

heap_5 for Non-Contiguous Memory:

Many microcontrollers have memory at non-contiguous addresses (internal SRAM, external RAM, CCM on STM32). heap_5 allows defining multiple heap regions:

heap_5 Configuration
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
// Define heap regions before any FreeRTOS calls
// Typically in startup code or main() before vTaskStartScheduler()
 
// Memory regions available on STM32F4
extern uint8_t __heap_start__;  // From linker script
extern uint8_t __heap_end__;
 
const HeapRegion_t xHeapRegions[] = {
    // Region 1: Internal SRAM (128KB)
    { (uint8_t *)&__heap_start__, (size_t)(&__heap_end__ - &__heap_start__) },
    
    // Region 2: CCM RAM (64KB, close-coupled for fast access)
    { (uint8_t *)0x10000000, 64 * 1024 },
    
    // Region 3: External SDRAM (if configured)
    { (uint8_t *)0xC0000000, 8 * 1024 * 1024 },
    
    // Terminate list with NULL
    { NULL, 0 }
};
 
int main(void) {
    // Initialize heap before any FreeRTOS calls
    vPortDefineHeapRegions(xHeapRegions);
    
    // Now create tasks, queues, etc.
    xTaskCreate(...);
    
    vTaskStartScheduler();
    
    for (;;); // Should never reach here
}

Static Allocation for Safety-Critical Systems

Configuration and Porting

FreeRTOSConfig.h — The Configuration Hub:

Every FreeRTOS project requires a FreeRTOSConfig.h file containing project-specific settings. A comprehensive configuration might include:

FreeRTOSConfig.h (Production Template)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
#ifndef FREERTOS_CONFIG_H
#define FREERTOS_CONFIG_H
 
/* Scheduler Configuration */
#define configUSE_PREEMPTION                    1
#define configUSE_PORT_OPTIMISED_TASK_SELECTION 1
#define configUSE_TICKLESS_IDLE                 0  // Enable for low power
#define configCPU_CLOCK_HZ                      ( 168000000UL )  // 168 MHz STM32F4
#define configTICK_RATE_HZ                      ( 1000 )  // 1ms tick
#define configMAX_PRIORITIES                    ( 7 )
#define configMINIMAL_STACK_SIZE                ( 128 )
#define configTOTAL_HEAP_SIZE                   ( 32 * 1024 )
 
/* Feature Inclusion */
#define configUSE_MUTEXES                       1
#define configUSE_RECURSIVE_MUTEXES             1
#define configUSE_COUNTING_SEMAPHORES           1
#define configUSE_QUEUE_SETS                    0
#define configUSE_TASK_NOTIFICATIONS            1
#define configTASK_NOTIFICATION_ARRAY_ENTRIES   3
#define configUSE_TIMERS                        1
#define configTIMER_TASK_PRIORITY               ( configMAX_PRIORITIES - 1 )
#define configTIMER_QUEUE_LENGTH                10
#define configTIMER_TASK_STACK_DEPTH            ( configMINIMAL_STACK_SIZE * 2 )
 
/* Memory Allocation */
#define configSUPPORT_STATIC_ALLOCATION         1
#define configSUPPORT_DYNAMIC_ALLOCATION        1
 
/* Hook Functions */
#define configUSE_IDLE_HOOK                     1
#define configUSE_TICK_HOOK                     0
#define configUSE_MALLOC_FAILED_HOOK            1
#define configCHECK_FOR_STACK_OVERFLOW          2
 
/* Debug and Statistics */
#define configUSE_TRACE_FACILITY                1
#define configUSE_STATS_FORMATTING_FUNCTIONS    1
#define configGENERATE_RUN_TIME_STATS           1
#define portCONFIGURE_TIMER_FOR_RUN_TIME_STATS()  configureTimerForRunTimeStats()
#define portGET_RUN_TIME_COUNTER_VALUE()        getRunTimeCounterValue()
 
/* Cortex-M Specific */
#define configPRIO_BITS                         4  // STM32 uses 4 priority bits
#define configLIBRARY_LOWEST_INTERRUPT_PRIORITY 15
#define configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY 5
#define configKERNEL_INTERRUPT_PRIORITY         ( configLIBRARY_LOWEST_INTERRUPT_PRIORITY << (8 - configPRIO_BITS) )
#define configMAX_SYSCALL_INTERRUPT_PRIORITY    ( configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY << (8 - configPRIO_BITS) )
 
/* Assert for development */
#define configASSERT( x ) if( ( x ) == 0 ) { taskDISABLE_INTERRUPTS(); for(;;); }
 
/* API function inclusion */
#define INCLUDE_vTaskPrioritySet                1
#define INCLUDE_uxTaskPriorityGet               1
#define INCLUDE_vTaskDelete                     1
#define INCLUDE_vTaskSuspend                    1
#define INCLUDE_xResumeFromISR                  1
#define INCLUDE_vTaskDelayUntil                 1
#define INCLUDE_vTaskDelay                      1
#define INCLUDE_xTaskGetSchedulerState          1
#define INCLUDE_uxTaskGetStackHighWaterMark     1
 
#endif /* FREERTOS_CONFIG_H */

Port Layer Responsibilities:

Each processor architecture requires a port consisting of port.c and portmacro.h. The port implements:

Port Layer Components

•pxPortInitialiseStack() — Initialize a task's stack frame to appear as if the task was previously interrupted mid-execution
•xPortSysTickHandler() — Tick interrupt handler, increments tick count and checks for context switch
•xPortPendSVHandler() — Context switch implementation, saves/restores full CPU context
•vPortSVCHandler() — Supervisor call handler, starts first task during scheduler initialization
•portYIELD() — Trigger context switch request (typically pending PendSV on Cortex-M)
•portENTER_CRITICAL() / portEXIT_CRITICAL() — Disable/enable interrupts up to syscall priority
•portTICK_PERIOD_MS — Macro defining milliseconds per tick for timing conversions

Leveraging Manufacturer BSPs

Best Practices and Design Patterns

Years of industry experience have established proven patterns for FreeRTOS application development. Adhering to these practices ensures robust, maintainable real-time systems.

Task Design Principles:

Recommended Practices

•Each task has single, well-defined responsibility
•Use infinite loops with blocking calls
•Place shortest deadline tasks at highest priority
•Minimize time spent at high priority
•Use software timers for periodic work
•Profile stack usage during development

Anti-Patterns to Avoid

•Busy-waiting or polling without yielding
•Blocking in ISRs (never!)
•Holding mutexes across long operations
•Creating/deleting tasks at runtime frequently
•Ignoring function return values
•Using vTaskDelete() on running task carelessly

ISR-to-Task Deferred Processing Pattern:

The canonical pattern for handling hardware interrupts in FreeRTOS:

Deferred Interrupt Processing
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
// ISR-safe task notification for deferred processing
TaskHandle_t xUARTTaskHandle;
 
// Runs in interrupt context - keep FAST
void USART1_IRQHandler(void) {
    BaseType_t xHigherPriorityTaskWoken = pdFALSE;
    
    if (USART1->SR & USART_SR_RXNE) {
        uint8_t byte = USART1->DR;  // Read clears interrupt
        
        // Minimal work in ISR: just buffer the byte
        rxBuffer[rxHead++] = byte;
        rxHead &= RX_BUFFER_MASK;  // Circular buffer
        
        // Wake processing task
        vTaskNotifyGiveFromISR(xUARTTaskHandle, &xHigherPriorityTaskWoken);
    }
    
    portYIELD_FROM_ISR(xHigherPriorityTaskWoken);
}
 
// UART processing task - handles heavy lifting
void vUARTProcessingTask(void *pvParameters) {
    for (;;) {
        // Block until ISR signals data available
        ulTaskNotifyTake(pdTRUE, portMAX_DELAY);
        
        // Process all buffered bytes
        while (rxTail != rxHead) {
            uint8_t byte = rxBuffer[rxTail++];
            rxTail &= RX_BUFFER_MASK;
            
            // Heavy processing here (parsing, validation, etc.)
            processReceivedByte(byte);
        }
    }
}

Resource Management Pattern:

Centralize shared resources with dedicated handler tasks:

Resource Handler Pattern
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
// Resource handler for SPI flash
typedef enum {
    FLASH_CMD_READ,
    FLASH_CMD_WRITE,
    FLASH_CMD_ERASE
} FlashCommand_t;
 
typedef struct {
    FlashCommand_t command;
    uint32_t address;
    uint8_t *buffer;
    size_t length;
    TaskHandle_t requestingTask;
    BaseType_t result;
} FlashRequest_t;
 
QueueHandle_t xFlashQueue;
static SemaphoreHandle_t xFlashComplete;
 
// Flash handler task - exclusive SPI access
void vFlashHandlerTask(void *pvParameters) {
    FlashRequest_t request;
    
    for (;;) {
        if (xQueueReceive(xFlashQueue, &request, portMAX_DELAY) == pdPASS) {
            switch (request.command) {
                case FLASH_CMD_READ:
                    request.result = spiFlashRead(request.address, 
                                                   request.buffer, 
                                                   request.length);
                    break;
                case FLASH_CMD_WRITE:
                    request.result = spiFlashWrite(request.address, 
                                                    request.buffer, 
                                                    request.length);
                    break;
                case FLASH_CMD_ERASE:
                    request.result = spiFlashErase(request.address);
                    break;
            }
            
            // Notify requesting task of completion
            xTaskNotify(request.requestingTask, 
                       request.result, 
                       eSetValueWithOverwrite);
        }
    }
}
 
// Client API - called from any task
BaseType_t flashRead(uint32_t addr, uint8_t *buf, size_t len) {
    FlashRequest_t request = {
        .command = FLASH_CMD_READ,
        .address = addr,
        .buffer = buf,
        .length = len,
        .requestingTask = xTaskGetCurrentTaskHandle()
    };
    
    xQueueSend(xFlashQueue, &request, portMAX_DELAY);
    
    // Wait for completion notification
    uint32_t result;
    xTaskNotifyWait(0, ULONG_MAX, &result, portMAX_DELAY);
    
    return (BaseType_t)result;
}

Debugging Tools

Summary: FreeRTOS Mastery

FreeRTOS has earned its position as the dominant RTOS for microcontrollers through principled design, minimal footprint, and exceptional portability. Let's consolidate the key concepts:

Key Takeaways

•Minimal Yet Complete — 4-9KB kernel provides full preemptive multitasking, synchronization, and timing services
•Priority-Based Scheduling — Highest ready priority always runs; round-robin within priority levels
•Unified IPC Model — Queues form the foundation; semaphores and mutexes are specialized queue types
•Flexible Memory — Five heap schemes from static-only to multi-region dynamic allocation
•Deterministic Design — Bounded execution times for kernel operations enable real-time guarantees
•Portability — 40+ architectures with clean port abstraction for custom targets

What's Next:

Page Complete

1 / 5