Overview

Overview

FreeRTOS is an RTOS class designed to be small enough to run on a microcontroller - although its use is not limited to microcontroller applications. This MW is full-featured and highly configurable via config flags. FreeRTOS is hardware agnostic and deployed across all STM32 series.

FreeRTOS overall block diagram

FreeRTOS overall block diagram

Features

FreeRTOS is an RTOS library supporting all CortexM & CortexA CPUs. It provides usual RTOS functionalities as thread management, inter-thread communication, signaling, as well as specific features like low power mode management and MPU support.

FreeRTOS is composed of several parts:

  • Kernel configuration and scheduler: that is Core/toolchain dependent and responsible for the tasks scheduling, interrupt handling, resource management.

  • Common API: hardware agnostic part implementing the common RTOS features (tasks management, memory management, message queues…)

  • Hooks: are split between the kernel and application.

  • MPU: is split between the kernel and application and implements the memory protection feature.

More details are available in the FreeRTOS official documentation.

Overall architecture

The main structural elements of a FreeRTOS codebase are:

  • Source/include/: public API headers (tasks, queues, timers, event groups, etc.).

  • Source/*.c: core kernel implementation files.

  • Source/portable/[compiler]/[arch]/: port layer (port.c, portmacro.h) for a specific CPU + toolchain.

  • portable/MemMang/heap_x.c: heap management strategy (choose one).

  • FreeRTOSConfig.h: project-specific kernel configuration.

FreeRTOS folder structure

FreeRTOS folder structure

A common layout looks like this: 

FreeRTOS/
├─ Source/
│  ├─ include/           # Public API headers
│  ├─ portable/          # CPU + compiler specific ports
│  ├─ tasks.c            # Core scheduler + task management
│  ├─ queue.c            # Queues, semaphores, mutexes
│  ├─ list.c             # Internal linked lists
│  ├─ event_groups.c     # Event groups
│  ├─ timers.c           # Software timers
│  ├─ stream_buffer.c    # Stream buffers
│  ├─ message_buffer.c   # Message buffers
│  └─ croutine.c         # (Legacy coroutines, optional)
│
├─ portable/
│  └─ MemMang/           # Heap management implementations
│     ├─ heap_1.c
│     ├─ heap_2.c
│     ├─ heap_3.c
│     ├─ heap_4.c
│     └─ heap_5.c
│
└─ FreeRTOSConfig.h      # Project-specific configuration

Public API headers

This directory contains the public headers that the user includes in the application.

  • FreeRTOS.h: Main FreeRTOS header. It includes FreeRTOSConfig.h and declares core kernel types, configuration macros, and global definitions.

  • task.h: Task and scheduler API

  • queue.h: API for Queues, Semaphores (binary, counting), Mutexes and recursive mutexes.

  • semphr.h: Convenience macros and functions for semaphores and mutexes, built on top of the queue mechanism defined in queue.c.

  • event_groups.h: Event group API for bit-based synchronization.

  • timers.h: Software timer API.

  • stream_buffer.h: Stream buffer API:

  • message_buffer.h:Message buffer API:

  • Other headers

    Files such as projdefs.h, portable.h, mpu_prototypes.h provide internal definitions, common typedefs, and MPU-related prototypes for ports that support an MPU.

Kernel source files

These files implement the RTOS kernel functionality.

  • tasks.c: Core scheduler and task management:

    • Task creation and deletion.

    • Priority-based scheduling (preemptive or cooperative).

    • Task states (running, ready, blocked, suspended).

    • Tick handling and timeout management.

    • Manipulation of TCBs (Task Control Blocks) and task lists.

  • queue.c: Implements: Queues (fixed-size FIFO), Semaphores (binary and counting), Mutexes (with priority inheritance), Recursive mutexes.

  • list.c: Generic doubly linked list implementation used internally by the kernel:

    • Scheduler ready and delayed task lists.

    • Timer lists.

    • Other internal lists.

  • event_groups.c: Event group implementation:

    • Waiting on one or more bits (ANY/ALL).

    • Setting and clearing bits from tasks and ISRs.

    • Blocking/unblocking tasks based on bit masks and timeouts.

  • timers.c: Software timer implementation:

    • Timer service (daemon) task.

    • Lists of active timers.

    • Timer expiration checks and callback execution.

    • Command queue used to manage timer actions (start/stop/reset).

  • stream_buffer.c: Stream buffer implementation:

    • Byte-oriented, one-way communication channels.

    • Support for blocking until a minimum number of bytes is available.

  • message_buffer.c: Message buffer implementation:

    • Built on stream_buffer.c.

    • Handles variable-length messages prefixed with their size.

  • croutine.c (legacy / optional)

    Coroutine implementation:

    • Older mechanism for lightweight cooperative “tasks”.

    • Rarely used in modern applications.

    • Often disabled via configuration (configUSE_CO_ROUTINES).

Port layer

The port layer adapts the portable kernel code to a specific CPU architecture and toolchain.

Typical structure: 

Source/portable/
├─ GCC/
│  ├─ ARM_CM4F/port.c
│  ├─ ARM_CM4F/portmacro.h
│  └─ ...
├─ IAR/
│  └─ ...
├─ RVDS/
│  └─ ...
└─ MemMang/
   └─ heap_x.c

For each compiler/architecture pair, user usually find:

  • port.c: Architecture-specific code:

    • Context switching (saving/restoring CPU registers).

    • Initializing task stacks so tasks start correctly.

    • Tick timer setup and tick ISR wrapper functions.

    • Critical section entry/exit implementation.

    • Yield from task and from ISR.

  • portmacro.h: Architecture-specific macros and types:

    • Basic types, e.g. portSTACK_TYPE, portBASE_TYPE, TickType_t.

    • Macros for critical sections:

      • portENTER_CRITICAL()

      • portEXIT_CRITICAL()

    • Macros for interrupt control:

      • portDISABLE_INTERRUPTS()

      • portENABLE_INTERRUPTS()

    • Macros for yielding:

      • portYIELD()

      • portYIELD_FROM_ISR(xHigherPriorityTaskWoken) (or equivalent).

    • Stack growth direction, alignment constraints, etc.

Heap management

FreeRTOS provides several heap management implementations in portable/MemMang/. The user must include one heap_x.c file in the project if dynamic memory allocation is selected.

The typical files are:

  • heap_1.c

    • Only allocates memory; there is no free.

    • Very simple and deterministic.

    • Suitable when all objects and tasks are created once at startup.

  • heap_2.c

    • Basic malloc/free with coalescing of adjacent free blocks.

    • More flexible than heap_1 but can fragment over time.

  • heap_3.c

    • Thin wrapper around the standard C library malloc() and free().

    • Simple but depends on the behavior and determinism of the C library allocator.

  • heap_4.c

    • More advanced allocator with coalescing and better fragmentation control.

    • Commonly used as a good general-purpose choice in RTOS systems.

  • heap_5.c

    • Supports multiple non-contiguous memory regions.

    • Useful when the MCU has several RAM banks or separate memory areas (e.g. internal and external RAM).

All heap implementations provide pvPortMalloc() and vPortFree() (except heap_1, which only allocates).

Folder structure in STM32Cube

The STM32Cube firmware architecture principles are based on the concept of software component packs. The packs are extended to add configuration description files to each configurable component.

For FreeRTOS middleware, some folders and files are added to the native FreeRTOS middleware source files to implement the STM32Cube architecture. The following figure presents the folder structure.

FreeRTOS STM32Cube folder structure

FreeRTOS STM32Cube folder structure

  • .config folder:

    • freertos_config_parameters.json: JSON file containing various FreeRTOS configuration flags.

    • gen_code.bat: Windows batch script for code generation.

    • gen_code.sh: Shell script (Linux/macOS) for code generation.

    • mw_freertos_codegen.gpdsc.hbs: Template file (Handlebars format) used to generate a CMSIS-Pack .gpdsc description for FreeRTOS.

FreeRTOS-config-folder-structure

FreeRTOS .config folder structure

  • .config/template:

    • FreeRTOSConfig_template.h.hbs: template for generating FreeRTOSConfig.h file.

    • mx_freertos_app_template.c.hbs: template for generating the FreeRTOS application source file.

    • mx_freertos_app_template.h.hbs: template for generating the FreeRTOS application header file.

FreeRTOS .config template folder structure

FreeRTOS .config/template folder structure

  • templates folder: user-modifiable files. This folder contains a copy of all generated files needed for FreeRTOS-based examples to work correctly. It is intended for developers using the middleware without the STM32MX2 tool.

    • mx_freertos_app.c

    • mx_freertos_app.h: files where the application code is implemented.

    • FreeRTOSConfig.h: copy of the FreeRTOS configuration file.

FreeRTOS template folder structure

FreeRTOS templates folder structure