FreeRTOS POSIX - POSIX Compatibility Layer for FreeRTOS Applications

July 17, 2026 · View on GitHub

Overview

FreeRTOS POSIX provides a lightweight POSIX compatibility layer on top of FreeRTOS for threading, synchronization, timing, and messaging APIs. It helps teams reuse POSIX-style application code and shorten migration time from Linux/Unix environments to embedded FreeRTOS targets.

Features

POSIX-like thread management via pthread APIs.
POSIX synchronization primitives: mutexes, condition variables, barriers, and semaphores.
POSIX message queues for asynchronous inter-thread communication.
POSIX timer and clock APIs mapped to FreeRTOS services.
Designed for embedded systems with constrained resources.

When to Use

Use this library when your project needs to:

Port existing POSIX-based code to a FreeRTOS platform.
Keep application code portable across desktop/server and embedded targets.
Use standard pthread/semaphore/message-queue design patterns instead of OS-specific wrappers.
Build multi-threaded FreeRTOS applications with familiar POSIX semantics.

How to Use

Use the Reference Manual Quick Start Guide and Configuration sections as the primary setup path.

Integration Checklist

Before copying the examples into an application, verify the following:

Include FreeRTOS_POSIX.h before any BSP, HAL, or C library header that may pull in time.h, sys/types.h, or sys/sched.h.
Do not mix FreeRTOS POSIX headers with the toolchain-provided pthread.h, time.h, or sys/types.h in the same translation unit.
Enable configUSE_POSIX_ERRNO and configUSE_APPLICATION_TASK_TAG in FreeRTOSConfig.h.
Call POSIX thread APIs only after the FreeRTOS scheduler is running.
Treat the code blocks below as function-scope examples unless the example explicitly shows a complete main.c flow.

Include POSIX Headers

Include FreeRTOS_POSIX.h before any POSIX headers so the port can suppress conflicts with toolchain-provided POSIX and time types. In application sources, place it before BSP or HAL headers if those headers may indirectly include the toolchain time.h or sys/types.h. Do not mix these headers with standard pthread.h, time.h, or sys/types.h from the C library.

#include "FreeRTOS_POSIX.h"
#include "FreeRTOS_POSIX/pthread.h"
#include "FreeRTOS_POSIX/semaphore.h"
#include "FreeRTOS_POSIX/time.h"
#include "cybsp.h"

Start FreeRTOS and Create Threads

Initialize your platform and start the FreeRTOS scheduler first. Create POSIX threads only after the scheduler is running. The snippets below are function-scope examples, not file-scope declarations to paste directly at the top level of main.c.

pthread_t thread_id;

void *worker_thread(void *arg)
{
    /* Application logic */
    return NULL;
}

int rc = pthread_create(&thread_id, NULL, worker_thread, NULL);
if (rc == 0)
{
    pthread_join(thread_id, NULL);
}

For an application source file, the same pattern should look like this:

#include "FreeRTOS_POSIX.h"
#include "FreeRTOS_POSIX/pthread.h"
#include "FreeRTOS_POSIX/semaphore.h"

static void *worker_thread(void *arg)
{
    (void)arg;
    return NULL;
}

static void run_posix_example(void)
{
    pthread_t thread_id;
    int rc = pthread_create(&thread_id, NULL, worker_thread, NULL);

    if (rc == 0)
    {
        pthread_join(thread_id, NULL);
    }
}

For a complete application flow, create a regular FreeRTOS task before starting the scheduler, then call POSIX APIs from that task:

#include "FreeRTOS_POSIX.h"
#include "FreeRTOS_POSIX/pthread.h"
#include "FreeRTOS.h"
#include "task.h"
#include "cybsp.h"

static void *worker_thread(void *arg)
{
    (void)arg;
    return NULL;
}

static void app_task(void *arg)
{
    pthread_t thread_id;

    (void)arg;

    if (pthread_create(&thread_id, NULL, worker_thread, NULL) == 0)
    {
        pthread_join(thread_id, NULL);
    }

    vTaskDelete(NULL);
}

int main(void)
{
    cybsp_init();

    xTaskCreate(app_task,
                "app",
                configMINIMAL_STACK_SIZE * 4,
                NULL,
                ( UBaseType_t ) tskIDLE_PRIORITY + 1U,
                NULL);

    vTaskStartScheduler();

    for (;;)
    {
    }
}

Synchronize Access to Shared Resources

Use POSIX synchronization primitives to protect shared data and coordinate execution.

Create and use these objects inside a function or task context, not as a loose statement sequence at file scope.

pthread_mutex_t lock = PTHREAD_MUTEX_INITIALIZER;

pthread_mutex_lock(&lock);
/* Critical section */
pthread_mutex_unlock(&lock);

sem_t ready;
sem_init(&ready, 0, 0);

/* Producer */
sem_post(&ready);

/* Consumer */
sem_wait(&ready);

Configuration

Validate the following before production use:

FreeRTOS configuration enables required kernel capabilities for mutexes and synchronization.
configUSE_APPLICATION_TASK_TAG is set to 1 in FreeRTOSConfig.h.
configUSE_POSIX_ERRNO is set to 1 in FreeRTOSConfig.h.
Thread priorities are mapped correctly for your system scheduling policy.
Heap and thread stack sizes are sufficient for worst-case workload.
Time-related APIs are configured consistently with your system tick and clock source.

Add the following to your project's FreeRTOSConfig.h if not already present:

#define configUSE_MUTEXES              1  /* Required: enables mutex API (xSemaphoreGetMutexHolder) */
#define configUSE_RECURSIVE_MUTEXES    1  /* Required: enables recursive mutexes */
#define configUSE_POSIX_ERRNO          1  /* Required: enables errno for POSIX error reporting */
#define configUSE_APPLICATION_TASK_TAG 1  /* Required: used internally by pthread_self() */
#define configUSE_TIMERS               1  /* Required: enables timer API used by POSIX timers */
#define configUSE_COUNTING_SEMAPHORES  1  /* Required: enables counting semaphores for sem_t */

#define INCLUDE_xSemaphoreGetMutexHolder 1  /* Required: used by pthread_mutex_unlock() */
#define INCLUDE_eTaskGetState            1  /* Required: used by pthread_detach() */

Without these defines the library will fail to compile.

Note: After adding or changing FreeRTOSConfig.h settings, do a Clean Build to ensure the compiler picks up the new configuration (ModusToolbox: Project → Clean All → Build).

Dependencies

FreeRTOS Kernel
ModusToolbox software environment and BSPs

Reference Manual

Reference Manual

Release Notes

FreeRTOS POSIX provides a POSIX compatibility layer on top of FreeRTOS for selected threading and synchronization APIs.

v1.0.2: DOC Update.
v1.0.1: Minor bug fixes.
v1.0.0: Initial release.

License

This library is licensed under the MIT License.

LICENSE - Primary license terms (MIT).