FreeRTOS Source Code Analysis – Observing How the OS Starts Running from the main Function

FreeRTOS is a lightweight real-time operating system kernel suitable for microcontrollers and embedded systems. Its open-source, lightweight, and portable characteristics make it a popular and widely used RTOS in embedded systems.To further learn the underlying principles of RTOS, this series will analyze the implementation of FreeRTOS from the source code perspective based on the STM32 HAL library.

1. FreeRTOS Source File Structure

FreeRTOS-Kernel
├─ CMSIS_RTOS_V2/
│  ├─ cmsis_os.h
│  ├─ cmsis_os2.c
│  ├─ cmsis_os2.h
│  ├─ freertos_mpool.h
│  └─ freertos_os2.h
|
├─ include/
│  ├─ atomic.h
│  ├─ croutine.h                 → Coroutines (deprecated, still compatible)
│  ├─ deprecated_definitions.h  
│  ├─ event_groups.h             → Event flag groups
│  ├─ FreeRTOS.h                 → Must include "main entry"
│  ├─ FreeRTOSConfig_template.h  
│  ├─ list.h  
│  ├─ message_buffer.h           → Message buffer (V10.0+)
│  ├─ mpu_prototypes.h      
│  ├─ mpu_wrappers.h     
│  ├─ portable.h
│  ├─ projdefs.h
│  ├─ queue.h                    → Queue / Semaphore / Mutex API
│  ├─ semphr.h                   → Semaphore/Mutex macro wrappers
│  ├─ stack_macros.h             
│  ├─ stackMacros.h              → Stack overflow detection helper macros
│  ├─ stream_buffer.h            → Stream buffer (V10.0+)
│  ├─ task.h                     → Task management API
│  └─ timers.h                   → Software timers
|
├─ portable/                     ← "Porting layer" - code related to compiler/hardware
│  ├─ MemMang/                   ← Heap management porting points (only "entry" for heap_1~5)
│  │  ├─ heap_1.c
│  │  ├─ heap_2.c
│  │  ├─ heap_3.c
│  │  ├─ heap_4.c
│  │  └─ heap_5.c
│  └─ RVDS/
│     └─ ARM_CM4F/
│        ├─ port.c
│        └─ portmacro.h                   
|
├─ croutine.c                    ← Coroutines (legacy)
├─ event_groups.c                ← Event flag groups
├─ list.c                        ← Doubly linked list (basis for ready list, delay list, suspended list)
├─ queue.c                       ← Unified implementation of queue / semaphore / mutex  
├─ stream_buffer.c               ← Shared implementation of stream / message buffer          
├─ tasks.c                       ← Core scheduler implementation (task creation, switching, ready list, delay list)
├─ timers.c                      ← Software timer Daemon task
|
└─ LICENSE.md

CMSIS_RTOS_V2

CMSIS (Cortex Microcontroller Software Interface Standard – Real-Time Operating System) is a unified RTOS interface standard defined by ARM for Cortex-M.Common APIs for FreeRTOS are encapsulated in cmsis_os2.c, allowing users to not worry about which OS is specifically used at the lower level.

portable

Porting adaptation, files related to hardware/compiler

• MemMangDifferent heap memory management implementations
• RVDS/ARM_Cm4F/port.cInterrupt switching, scheduler startup, PendSV context switching, SysTick heartbeat, critical section nesting, miscellaneous barriers.

Kernel

Tasks, timers, queues, event groups, etc.

2. Analyzing from the main Function

int main(void)
{
    ...

    /* Init scheduler */
    osKernelInitialize();  /* Call init function for freertos objects (in cmsis_os2.c) */
    MX_FREERTOS_Init();

    /* Start scheduler */
    osKernelStart();

    /* We should never get here as control is now taken by the scheduler */

    while (1)
    {

    }
}

osKernelInitialize

osKernelInitialize sets the kernel state to Ready

osStatus_t osKernelInitialize (void) {
  osStatus_t stat;

if (IS_IRQ()) {
    stat = osErrorISR;
  }
else {
    if (KernelState == osKernelInactive) {
      ...
      KernelState = osKernelReady;
      stat = osOK;
    } else {
      stat = osError;
    }
  }

return (stat);
}

MX_FREERTOS_Init

A default task is created in MX_FREERTOS_Init, and a dedicated article will analyze task creation later, so we will skip it for now.

void MX_FREERTOS_Init(void) {
    /* Create the thread(s) */
    /* creation of defaultTask */
    defaultTaskHandle = osThreadNew(StartDefaultTask, NULL, &amp;defaultTask_attributes);
}

osKernelStart

osKernelStart is the main function of focus in this article, as the kernel starts scheduling from this function

osStatus_t osKernelStart (void) {
  osStatus_t stat;

if (IS_IRQ()) {
    stat = osErrorISR;
  }
else {
    if (KernelState == osKernelReady) {
      /* Ensure SVC priority is at the reset value */
      SVC_Setup();
      /* Change state to enable IRQ masking check */
      KernelState = osKernelRunning;
      /* Start the kernel scheduler */
      vTaskStartScheduler();
      stat = osOK;
    } else {
      stat = osError;
    }
  }

return (stat);
}

osKernelStart() is the only entry point for “starting the scheduler” in the CMSIS-RTOS2 encapsulation of FreeRTOS (in cmsis_os2.c). It hands over control of the CPU to FreeRTOS, and from then on, tasks begin to compete for execution, while the main() thread becomes the idle context.

1. Check if currently in interrupt state

if (IS_IRQ()) {
    stat = osErrorISR;

• CMSIS stipulates: the scheduler cannot be started in IRQ context.
• IS_IRQ() typically reads __get_IPSR(), where a non-zero value indicates an exception/interrupt is occurring.

2. State machine check

if (KernelState == osKernelReady)

• Kernel state machine:

• osKernelInactive → osKernelReady (after osKernelInitialize())
• osKernelReady → osKernelRunning (set by this function)

• Only ready state is allowed to enter running state, repeated calls return osError.

3. Ensure SVC priority is at the lowest

__STATIC_INLINE void SVC_Setup (void) {
#if (__ARM_ARCH_7A__ == 0U)
  /* Service Call interrupt might be configured before kernel start     */
  /* and when its priority is lower or equal to BASEPRI, svc instruction */
  /* causes a Hard Fault.                                               */
  NVIC_SetPriority (SVCall_IRQ_NBR, 0U);
#endif
}

• Set NVIC_SVC_PRIORITY to the lowest priority (highest value).
• Prevent user misconfiguration from causing SVC exceptions to be preempted, leading to context switch crashes.
• Effective for Cortex-M3/4/7/33 cores with SVC; empty function for M0/M0+/M23 without SVC.

4. Switch global state

KernelState = osKernelRunning;

After this, macros like IS_IRQ_MASKING() will prohibit object creation outside critical sections, ensuring API timing safety.

5. Start FreeRTOS scheduler

Call vTaskStartScheduler to start the scheduler

3. How the Scheduler is Started

vTaskStartScheduler

void vTaskStartScheduler( void )
{
  StaticTask_t *pxIdleTaskTCBBuffer = NULL;
  StackType_t *pxIdleTaskStackBuffer = NULL;
uint32_t ulIdleTaskStackSize;

/* The Idle task is created using user provided RAM - obtain the
  address of the RAM then create the idle task. */
  vApplicationGetIdleTaskMemory( &amp;pxIdleTaskTCBBuffer, &amp;pxIdleTaskStackBuffer, &amp;ulIdleTaskStackSize );
  xIdleTaskHandle = xTaskCreateStatic(    prvIdleTask,
                      configIDLE_TASK_NAME,
                      ulIdleTaskStackSize,
                      ( void * ) NULL, /*lint !e961.  The cast is not redundant for all compilers. */
                      portPRIVILEGE_BIT, /* In effect ( tskIDLE_PRIORITY | portPRIVILEGE_BIT ), but tskIDLE_PRIORITY is zero. */
                      pxIdleTaskStackBuffer,
                      pxIdleTaskTCBBuffer ); /*lint !e961 MISRA exception, justified as it is not a redundant explicit cast to all supported compilers. */
  ...

  xTimerCreateTimerTask();

  ...

/* Interrupts are turned off here, to ensure a tick does not occur
  before or during the call to xPortStartScheduler().  The stacks of
  the created tasks contain a status word with interrupts switched on
  so interrupts will automatically get re-enabled when the first task
  starts to run. */
  portDISABLE_INTERRUPTS();  

/* Setting up the timer tick is hardware specific and thus in the
  portable interface. */
  xPortStartScheduler();
}

vTaskStartScheduler mainly accomplishes the following tasks:

• Create idle task (static or dynamic), #define configMINIMAL_STACK_SIZE ((uint16_t)128)
• Create Timer daemon task (if configUSE_TIMERS is enabled), further analysis in the Timer section.
• Disable interrupts
• Call xPortStartScheduler() to start the scheduler

xPortStartScheduler

BaseType_t xPortStartScheduler( void )
{
  ...

/* Make PendSV and SysTick the lowest priority interrupts. */
  portNVIC_SYSPRI2_REG |= portNVIC_PENDSV_PRI;
  portNVIC_SYSPRI2_REG |= portNVIC_SYSTICK_PRI;

/* Start the timer that generates the tick ISR.  Interrupts are disabled
  here already. */
  vPortSetupTimerInterrupt();

  ...

/* Ensure the VFP is enabled - it should be anyway. */
  prvEnableVFP();

/* Start the first task. */
  prvStartFirstTask();
}

xPortStartScheduler mainly accomplishes the following tasks:

• Set PendSV/Systick priority

• Set PendSV and SysTick to the lowest priority (<code>configKERNEL_INTERRUPT_PRIORITY)
• Load SysTick->LOAD with <code>configCPU_CLOCK_HZ / configTICK_RATE_HZ and start counting

• Enable FPU (if for <code>CM4F/CM7 and <code>configENABLE_FPU is 1)
• Call prvStartFirstTask, starting the first task

prvStartFirstTask

__asm void prvStartFirstTask( void )
{
    PRESERVE8

    /* Use the NVIC offset register to locate the stack. */
    ldr r0, =0xE000ED08
    ldr r0, [r0]
    ldr r0, [r0]
    /* Set the msp back to the start of the stack. */
    msr msp, r0
    /* Clear the bit that indicates the FPU is in use in case the FPU was used
    before the scheduler was started - which would otherwise result in the
    unnecessary leaving of space in the SVC stack for lazy saving of FPU
    registers. */
    mov r0, #0
    msr control, r0
    /* Globally enable interrupts. */
    cpsie i
    cpsie f
    dsb
    isb
    /* Call SVC to start the first task. */
    svc 0
    nop
    nop
}

prvStartFirstTask is written in assembly language and will trigger the first context switch via SVC 0 - hardware jumps to the context of the first task:

1. Find the “birth address” of the main stack`MSP`

ldr r0, =0xE000ED08     ; r0 = &amp;SCB->VTOR
ldr r0, [r0]            ; r0 = VTOR value (vector table base address)
ldr r0, [r0]            ; r0 = vector table item 0 = main stack top (_estack)

In Cortex-M, the vector table offset register <code>VTOR contains the "starting address of the vector table", and the first word of the table is the initial value of <code>MSP after reset. This step retrieves the "stack top written in Flash during the Boot phase" to ensure that the subsequent <code>msp points to a valid and 8-byte aligned RAM top.

2. Reset MSP to factory settings

msr msp, r0             ; Write back to MSP officially

Before this, FreeRTOS may have used <code>MSP as a temporary stack or even run C code; now the old stack is completely discarded to prevent "upper layer" residual data from contaminating the first task. After this, <code>MSP<code> will only be used for exception frames, while <code>PSP will run task code.

3. Clear FPU active flag

mov r0, #0
msr control, r0         ; CONTROL.FPCA = 0

CONTROL[2] (FPCA) = 1 indicates that the hardware will automatically push floating-point registers S0-S15&FPSCR on exception entry, occupying 68 bytes. If the <code>bootloader or early C code used the <code>FPU, and this is not cleared, then upon entering <code>SVC, 68 bytes of garbage will be pushed, wasting <code>RAM and disrupting alignment. After clearing, if the first task uses <code>FPU, it will be re-enabled in <code>vPortEnableVFP(), implementing "lazy saving".

4. Globally enable interrupts

cpsie i         ; Enable IRQ  （= __enable_irq()）
cpsie f         ; Enable FIQ  （in M series, FIQ is the global interrupt switch）
dsb
isb             ; Pipeline and bus barrier, ensuring the previous "enable" takes effect immediately

vTaskStartScheduler()<code> calls <code>portDISABLE_INTERRUPTS() to disable global interrupts; here is the formal "release". If not opened, after <code>SVC, both <code>PendSV and <code>SysTick will not respond, causing the scheduler to deadlock.

5. Trigger the first context switch

    svc 0           ; Trigger SVC exception
    nop
    nop

SVC 0 jumps to vPortSVCHandler(), and the following two nops are just placeholders that will never execute

We will analyze up to this point for now; the next step is the formal jump to the first task to start running. In the next article, we will continue to analyze how tasks are created and how multiple tasks switch between each other.

FreeRTOS Source Code Analysis: Preparing to Start the First Task

FreeRTOS Source Code Analysis – Observing How the OS Starts Running from the main Function

1. FreeRTOS Source File Structure

CMSIS_RTOS_V2

portable

Kernel

2. Analyzing from the main Function

osKernelInitialize

MX_FREERTOS_Init

osKernelStart

1. Check if currently in interrupt state

2. State machine check

3. Ensure SVC priority is at the lowest

4. Switch global state

5. Start FreeRTOS scheduler

3. How the Scheduler is Started

vTaskStartScheduler

xPortStartScheduler

prvStartFirstTask

1. Find the “birth address” of the main stack`<span>MSP</span>`

2. Reset MSP to factory settings

3. Clear FPU active flag

4. Globally enable interrupts

5. Trigger the first context switch

Leave a Comment Cancel reply

FreeRTOS Source Code Analysis – Observing How the OS Starts Running from the main Function

1. FreeRTOS Source File Structure

CMSIS_RTOS_V2

portable

Kernel

2. Analyzing from the main Function

osKernelInitialize

MX_FREERTOS_Init

osKernelStart

1. Check if currently in interrupt state

2. State machine check

3. Ensure SVC priority is at the lowest

4. Switch global state

5. Start FreeRTOS scheduler

3. How the Scheduler is Started

vTaskStartScheduler

xPortStartScheduler

prvStartFirstTask

1. Find the “birth address” of the main stack<span>MSP</span>

2. Reset MSP to factory settings

3. Clear FPU active flag

4. Globally enable interrupts

5. Trigger the first context switch

Related posts

Leave a Comment Cancel reply

1. Find the “birth address” of the main stack`<span>MSP</span>`