Practical RTOS Internals · 46/53

FreeRTOS 소스 분석 — tasks.c·queue.c·port.c 추적

2026년 5월 8일 · Hawk · 7분 읽기

freertos source-analysis tasks queue port

#한 줄 요약

“FreeRTOS 커널은 세 파일만 이해하면 전체가 보입니다.” — tasks.c가 스케줄러, queue.c가 IPC, port.c가 아키텍처 경계입니다.

#어떤 문제를 푸는가

FreeRTOS는 1만 줄 안팎의 작은 커널입니다. 그래도 처음 소스를 열면 어디부터 읽어야 할지 막막합니다. 파일 수십 개, 매크로 수백 개, #if 분기가 함수 한 줄 단위로 박혀 있습니다.

이 글의 목표는 세 핵심 파일만 골라 읽는 길을 만드는 것입니다. tasks.c에서 스케줄러의 자료구조와 진입점을 따라가고, queue.c에서 큐·세마포어·뮤텍스가 같은 구현을 공유하는 모습을 보고, port.c에서 아키텍처에 의존하는 경계가 어디까지인지 확인합니다. 이 흐름을 한 번 잡아 두면 SMP, MPU, tickless 같은 확장 옵션도 같은 지도 위에서 자연스럽게 읽힙니다.

저장소는 github.com/FreeRTOS/FreeRTOS-Kernel입니다. 커널만 분리되어 있어 빌드 시스템과 BSP에 끌려다니지 않고 본체만 읽기 좋습니다.

#저장소 구조와 진입점

1
FreeRTOS-Kernel/
2
├── include/                       # public API
3
│   ├── FreeRTOS.h                 # 모든 컴파일 단위의 시작
4
│   ├── task.h
5
│   ├── queue.h
6
│   └── semphr.h
7
├── tasks.c                        # 스케줄러 본체 (~5000 lines)
8
├── queue.c                        # 큐·세마포어·뮤텍스 통합
9
├── timers.c                       # software timer
10
├── event_groups.c
11
├── stream_buffer.c
12
├── list.c                         # 양방향 list 자료구조
13
├── portable/                      # 아키텍처별 port
14
│   ├── GCC/ARM_CM4F/
15
│   ├── GCC/ARM_CM33_NTZ/
16
│   ├── GCC/RISC-V/
17
│   └── MemMang/                   # heap_1 ~ heap_5
18
└── License/

읽는 순서는 FreeRTOS.h → list.c → tasks.c → queue.c → portable/<your-arch>/port.c가 자연스럽습니다. list.c를 먼저 보는 이유는 ready list와 wait list의 모든 연결이 같은 자료구조 위에 얹혀 있기 때문입니다.

#tasks.c — 스케줄러 본체

tasks.c의 첫 줄에 가까운 곳에 모든 것의 출발점이 있습니다.

1
PRIVILEGED_DATA TCB_t * volatile pxCurrentTCB = NULL;

지금 어느 CPU에서 어느 task가 돌고 있는지를 가리키는 단일 포인터입니다. 컨텍스트 스위치는 결국 이 포인터를 바꾸고 그 안의 pxTopOfStack을 새 PSP로 옮기는 일입니다.

TCB는 task의 모든 상태를 담는 구조체입니다.

1
typedef struct tskTaskControlBlock {
2
    volatile StackType_t * pxTopOfStack;   /* MUST be first */
3

4
    #if (portUSING_MPU_WRAPPERS == 1)
5
    xMPU_SETTINGS xMPUSettings;
6
    #endif
7

8
    ListItem_t  xStateListItem;            /* ready/delay/suspend */
9
    ListItem_t  xEventListItem;            /* queue/semaphore wait */
10
    UBaseType_t uxPriority;
11
    StackType_t *pxStack;
12
    char        pcTaskName[configMAX_TASK_NAME_LEN];
13

14
    #if (configUSE_MUTEXES == 1)
15
    UBaseType_t uxBasePriority;            /* PI base */
16
    UBaseType_t uxMutexesHeld;
17
    #endif
18
    /* ... 다른 필드 */
19
} tskTCB;

pxTopOfStack이 반드시 첫 필드여야 합니다. 컨텍스트 스위치 어셈블리가 TCB 포인터를 받으면 offset 0에서 SP를 꺼내고 새 SP를 다시 그 자리에 저장합니다. 이 필드를 옮기면 어셈블리와 C 구조가 어긋나면서 첫 스위치 직후 모든 task가 깨집니다.

ready list는 priority별로 분리되어 있습니다.

1
PRIVILEGED_DATA static List_t pxReadyTasksLists[configMAX_PRIORITIES];

각 priority가 FIFO list입니다. 같은 priority 안에서 round-robin이 자연스럽게 돌아가는 이유입니다. 최상위 priority를 찾는 일은 별도의 비트맵으로 가속됩니다.

1
#if (configUSE_PORT_OPTIMISED_TASK_SELECTION == 1)
2
    static volatile UBaseType_t uxTopReadyPriority;
3
#endif
4

5
#define portRECORD_READY_PRIORITY(uxPriority, uxTopReadyPriority) \
6
    (uxTopReadyPriority) |= (1U << (uxPriority))
7
#define portGET_HIGHEST_PRIORITY(uxTopPriority, uxReadyPriorities) \
8
    uxTopPriority = (31U - __CLZ(uxReadyPriorities))

Cortex-M의 CLZ 한 명령으로 최상위 ready priority가 한 사이클에 나옵니다. 32개 priority 안에서는 O(1) 결정입니다.

#xTaskCreate부터 PendSV까지

새 task 하나가 만들어져서 실제로 실행되기까지의 흐름을 함수 이름으로만 추리면 다음과 같습니다.

1
BaseType_t xTaskCreate(TaskFunction_t pxTaskCode,
2
                       const char *pcName,
3
                       configSTACK_DEPTH_TYPE usStackDepth,
4
                       void *pvParameters,
5
                       UBaseType_t uxPriority,
6
                       TaskHandle_t *pxCreatedTask)
7
{
8
    StackType_t *pxStack = pvPortMalloc(usStackDepth * sizeof(StackType_t));
9
    TCB_t *pxNewTCB = pvPortMalloc(sizeof(TCB_t));
10

11
    prvInitialiseNewTask(pxTaskCode, pcName, usStackDepth, pvParameters,
12
                         uxPriority, pxCreatedTask, pxNewTCB, NULL);
13

14
    prvAddNewTaskToReadyList(pxNewTCB);
15
    return pdPASS;
16
}

prvInitialiseNewTask 안에서 initial stack frame이 만들어집니다. 이 부분이 port 계층으로 위임됩니다.

1
StackType_t *pxPortInitialiseStack(StackType_t *pxTopOfStack,
2
                                    TaskFunction_t pxCode,
3
                                    void *pvParameters)
4
{
5
    pxTopOfStack--; *pxTopOfStack = portINITIAL_XPSR;
6
    pxTopOfStack--; *pxTopOfStack = (StackType_t)pxCode;
7
    pxTopOfStack--; *pxTopOfStack = (StackType_t)prvTaskExitError;
8
    pxTopOfStack -= 5;                              /* R12, R3, R2, R1 */
9
    *pxTopOfStack = (StackType_t)pvParameters;      /* R0 */
10
    pxTopOfStack -= 8;                              /* R4-R11 */
11
    return pxTopOfStack;
12
}

이렇게 가짜 컨텍스트 스위치가 stack 위에 한 번 펼쳐져 있어야 첫 PendSV가 pop할 때 자연스럽게 task의 진입점으로 점프합니다.

스케줄러는 vTaskSwitchContext에서 다음 실행 대상을 결정합니다.

1
void vTaskSwitchContext(void)
2
{
3
    if (uxSchedulerSuspended != pdFALSE) {
4
        xYieldPending = pdTRUE;
5
        return;
6
    }
7
    xYieldPending = pdFALSE;
8
    taskSELECT_HIGHEST_PRIORITY_TASK();
9
}
10

11
#define taskSELECT_HIGHEST_PRIORITY_TASK()                          \
12
    UBaseType_t uxTopPriority;                                      \
13
    portGET_HIGHEST_PRIORITY(uxTopPriority, uxTopReadyPriority);    \
14
    listGET_OWNER_OF_NEXT_ENTRY(pxCurrentTCB,                       \
15
                                &(pxReadyTasksLists[uxTopPriority]))

listGET_OWNER_OF_NEXT_ENTRY가 같은 priority list 안에서 다음 항목을 가리키므로, 같은 priority의 task들은 자연스럽게 round-robin으로 순환합니다.

실제 레지스터 교체는 PendSV 핸들러가 합니다.

1
PendSV_Handler:
2
    mrs r0, psp
3
    isb
4
    ldr r3, =pxCurrentTCB
5
    ldr r2, [r3]
6

7
    tst lr, #0x10
8
    it eq
9
    vstmdbeq r0!, {s16-s31}
10

11
    stmdb r0!, {r4-r11, lr}
12
    str r0, [r2]               ; save SP into TCB
13

14
    push {r3}
15
    cpsid f
16
    bl vTaskSwitchContext
17
    cpsie f
18
    pop {r3}
19

20
    ldr r1, [r3]               ; new pxCurrentTCB
21
    ldr r0, [r1]               ; new SP
22
    ldmia r0!, {r4-r11, lr}
23

24
    tst lr, #0x10
25
    it eq
26
    vldmiaeq r0!, {s16-s31}
27

28
    msr psp, r0
29
    isb
30
    bx lr                      ; HW pops {R0-R3, R12, LR, PC, xPSR}

Cortex-M4 168 MHz에서 한 번 스위치에 30~50 사이클입니다. 300 ns 안쪽으로 마무리됩니다.

#queue.c — 하나의 구현으로 세 가지 IPC

queue.c를 처음 보면 놀라는 부분이 있습니다. 큐, 세마포어, 뮤텍스가 같은 자료구조를 공유합니다.

1
typedef struct QueueDefinition {
2
    int8_t *pcHead;
3
    int8_t *pcWriteTo;
4
    union {
5
        int8_t *pcReadFrom;                   /* 큐 모드 */
6
        UBaseType_t uxRecursiveCallCount;     /* recursive mutex */
7
    } u;
8

9
    List_t xTasksWaitingToSend;
10
    List_t xTasksWaitingToReceive;
11

12
    volatile UBaseType_t uxMessagesWaiting;
13
    UBaseType_t uxLength;
14
    UBaseType_t uxItemSize;
15

16
    volatile int8_t cRxLock;
17
    volatile int8_t cTxLock;
18

19
    UBaseType_t uxQueueType;
20
} Queue_t;
21

22
typedef Queue_t Semaphore_t;
23
typedef Queue_t Mutex_t;

세마포어는 길이 1, item 크기 0인 큐이고, 뮤텍스는 추가로 owner와 recursion count를 들고 다니는 큐입니다. 한 구현을 셋이 공유하므로 버그 수정과 검증이 한 곳에 집중됩니다.

송신 경로는 3-07: Queue 구현에서 더 자세히 다루지만, 골격만 보면 critical section과 event list 패턴이 그대로 드러납니다.

1
BaseType_t xQueueGenericSend(QueueHandle_t xQueue,
2
                              const void *pvItemToQueue,
3
                              TickType_t xTicksToWait,
4
                              BaseType_t xCopyPosition)
5
{
6
    Queue_t *pxQueue = xQueue;
7
    for (;;) {
8
        taskENTER_CRITICAL();
9
        {
10
            if (pxQueue->uxMessagesWaiting < pxQueue->uxLength) {
11
                prvCopyDataToQueue(pxQueue, pvItemToQueue, xCopyPosition);
12

13
                if (listLIST_IS_EMPTY(&pxQueue->xTasksWaitingToReceive) == pdFALSE) {
14
                    if (xTaskRemoveFromEventList(&pxQueue->xTasksWaitingToReceive) != pdFALSE) {
15
                        queueYIELD_IF_USING_PREEMPTION();
16
                    }
17
                }
18
                taskEXIT_CRITICAL();
19
                return pdPASS;
20
            }
21
            if (xTicksToWait == 0) {
22
                taskEXIT_CRITICAL();
23
                return errQUEUE_FULL;
24
            }
25
            vTaskPlaceOnEventList(&pxQueue->xTasksWaitingToSend, xTicksToWait);
26
        }
27
        taskEXIT_CRITICAL();
28
        portYIELD_WITHIN_API();
29
    }
30
}

vTaskPlaceOnEventList는 현재 task를 event list에 끼우고 ready list에서 빼는 작업입니다. 깨우는 쪽은 xTaskRemoveFromEventList로 빼서 ready로 돌립니다. 큐, 세마포어, 뮤텍스가 모두 이 한 쌍의 함수에 의존합니다.

#port.c — 아키텍처 경계

portable/<toolchain>/<arch>/port.c가 아키텍처에 의존하는 모든 동작을 떠맡습니다. Cortex-M4F를 예로 보면, 스케줄러의 시작 자체가 SVC 한 줄로 압축됩니다.

1
BaseType_t xPortStartScheduler(void)
2
{
3
    portNVIC_SHPR3_REG |= portNVIC_PENDSV_PRI;
4
    portNVIC_SHPR3_REG |= portNVIC_SYSTICK_PRI;
5

6
    vPortSetupTimerInterrupt();      /* SysTick */
7
    vPortEnableVFP();
8
    *(portFPCCR) |= portASPEN_AND_LSPEN_BITS;
9

10
    __asm volatile ("svc 0");        /* 첫 task로 진입 */
11
    return 0;
12
}

svc 0이 SVC_Handler로 떨어지면 그 안에서 pxCurrentTCB가 가리키는 task의 stack을 PSP로 옮기고 bx lr로 빠져나오면서 첫 task가 시작됩니다.

매 tick의 진입점은 SysTick 핸들러입니다.

1
void xPortSysTickHandler(void)
2
{
3
    portDISABLE_INTERRUPTS();
4
    {
5
        if (xTaskIncrementTick() != pdFALSE) {
6
            portNVIC_INT_CTRL_REG = portNVIC_PENDSVSET_BIT;
7
        }
8
    }
9
    portENABLE_INTERRUPTS();
10
}

xTaskIncrementTick이 time slice 만료와 delay 카운트다운을 모두 처리하고, 더 높은 priority의 task가 깨어났다면 PendSV bit를 set해서 핸들러 복귀 직후에 컨텍스트 스위치가 일어나도록 합니다.

critical section은 BASEPRI를 사용합니다.

1
#define portDISABLE_INTERRUPTS()                                  \
2
    __asm volatile (                                              \
3
        "msr basepri, %0\n"                                       \
4
        "isb\n" "dsb\n"                                           \
5
        : : "r"(configMAX_SYSCALL_INTERRUPT_PRIORITY)             \
6
    )
7

8
#define portENABLE_INTERRUPTS()  __set_BASEPRI(0)

configMAX_SYSCALL_INTERRUPT_PRIORITY보다 낮은 priority의 IRQ만 막힙니다. 그보다 높은 hard-RT IRQ는 critical section 안에서도 그대로 통과하므로, 안전 회로처럼 응답 시간이 절대적으로 중요한 IRQ는 FreeRTOS의 영향을 받지 않게 설계할 수 있습니다.

#흥미로운 세 곳

소스를 끝까지 따라가 보면 의외로 인상적인 코드가 모입니다. 세 곳을 꼽으면 다음과 같습니다.

첫째, uxTopReadyPriority 비트맵과 CLZ 결합입니다. 평범한 정수 한 워드가 32 priority에 대한 O(1) lookup을 만들어 냅니다. 비트맵의 단순함과 명령어 한 줄이 합쳐졌습니다.

둘째, Queue_t가 세 IPC를 동시에 표현하는 union 설계입니다. 큐의 read 포인터와 뮤텍스의 recursion count가 같은 union 자리를 공유합니다. 코드가 늘지 않은 채 기능이 셋으로 갈라집니다.

셋째, 첫 task의 진입을 위한 가짜 stack frame입니다. pxPortInitialiseStack이 만든 모양은 PendSV가 어떻게 pop할지를 정확히 모사합니다. 실행과 자료구조가 서로를 거울처럼 비추는 부분입니다.

#SMP — FreeRTOS 11

FreeRTOS 11에서 SMP가 공식화되면서 pxCurrentTCB가 배열로 바뀌었습니다.

1
TCB_t * volatile pxCurrentTCBs[configNUMBER_OF_CORES];
2
#define pxCurrentTCB  pxCurrentTCBs[xPortGetCoreID()]

매크로 한 줄로 단일 코어 코드가 그대로 동작합니다. ready list는 여전히 하나이고, task/ISR 두 단계 spinlock으로 보호됩니다. 구조의 자세한 비교는 4-07: SMP RTOS에서 다룹니다.

#빌드 — CMake 모듈로 묶기

최근 FreeRTOS는 CMake 통합이 깔끔해졌습니다.

1
add_subdirectory(FreeRTOS-Kernel)
2

3
target_link_libraries(my_firmware PRIVATE
4
    freertos_kernel
5
    freertos_config       # FreeRTOSConfig.h 가진 INTERFACE 타깃
6
)
7

8
target_include_directories(freertos_config INTERFACE
9
    ${CMAKE_SOURCE_DIR}/config)

freertos_config는 사용자 측에서 정의하는 INTERFACE 타깃입니다. 여기에 FreeRTOSConfig.h의 위치를 알려 주면 커널이 그 헤더를 끌어다 씁니다.

#자주 보는 함정

경고 — pxTopOfStack을 첫 필드에서 옮김

TCB 구조체 안에서 pxTopOfStack이 첫 필드가 아니면 컨텍스트 스위치 어셈블리가 엉뚱한 주소를 SP로 사용합니다. 첫 PendSV 직후 hard fault로 죽습니다.

경고 — Cortex-M3 binary에 Cortex-M4F port 링크

portable/GCC/ARM_CM3과 ARM_CM4F는 FPU 처리와 BASEPRI 사용이 다릅니다. 디렉터리 한 단계 잘못 잡으면 빌드는 통과해도 런타임에 무한 fault가 납니다.

경고 — critical section 안에서 긴 작업

taskENTER_CRITICAL이 BASEPRI로 IRQ를 막는 동안은 SysTick도 멈춥니다. 안에서 hash 계산이나 printf를 호출하면 수 ms 동안 모든 RT IRQ가 막힙니다. critical은 수 µs 안에 끝나는 작업에만 씁니다.

경고 — heap_1에서 vTaskDelete 반복

heap_1은 free가 동작하지 않으므로 vTaskDelete를 호출해도 메모리가 돌아오지 않습니다. 동적 생성/삭제가 있는 시스템은 heap_4 이상으로 옮겨야 합니다.

#정리

FreeRTOS 커널은 tasks.c + queue.c + port.c 세 파일을 중심으로 읽으면 전체 구조가 잡힙니다.
pxCurrentTCB는 시스템 전체에서 현재 실행 중인 task를 가리키는 단일 포인터이며, 컨텍스트 스위치의 회전축입니다.
ready list는 priority별 FIFO이며, uxTopReadyPriority 비트맵과 CLZ로 최상위 priority를 한 사이클에 찾습니다.
큐·세마포어·뮤텍스는 Queue_t 하나를 공유하므로 검증과 버그 수정이 한 곳에 모입니다.
port 계층은 pxPortInitialiseStack, xPortStartScheduler, xPortSysTickHandler, PendSV 핸들러, BASEPRI 매크로로 좁혀집니다.
SMP는 pxCurrentTCB를 배열로 바꾸고 spinlock을 추가한 확장이며, 단일 코어 구조와 같은 지도 위에서 읽힙니다.
critical section은 BASEPRI 기반이므로 configMAX_SYSCALL_INTERRUPT_PRIORITY보다 높은 IRQ는 그대로 통과합니다.

다음 편은 5-02 Zephyr 커널 분석에서 devicetree와 driver model 위에서 동작하는 더 큰 RTOS를 봅니다.

FreeRTOS 소스 분석 — tasks.c·queue.c·port.c 추적

#한 줄 요약

#어떤 문제를 푸는가

#저장소 구조와 진입점

#tasks.c — 스케줄러 본체

#xTaskCreate부터 PendSV까지

#queue.c — 하나의 구현으로 세 가지 IPC

#port.c — 아키텍처 경계

#흥미로운 세 곳

#SMP — FreeRTOS 11

#빌드 — CMake 모듈로 묶기

#자주 보는 함정

#정리

#관련 항목

Practical RTOS Internals · 47 of 53

관련 글

RTOS 선택 가이드 — Footprint·License·Certification·Ecosystem

RT-Thread 분석 — Object 모델·Components·Smart·Studio

Zephyr 커널 분석 — k_thread·k_sem·Driver Model

이 글을 참조하는 글 (4)