This page provides general guidance for using the FreeRTOS real-time operating system with Xilinx devices. 

Table of Contents


Developed in partnership with the world’s leading chip companies over a 15-year period, FreeRTOS is a market-leading real-time operating system (RTOS) for microcontrollers and small microprocessors. Distributed freely under the MIT open source license, FreeRTOS includes a kernel and a growing set of libraries suitable for use across all industry sectors. FreeRTOS is built with an emphasis on reliability and ease of use.

The FreeRTOS kernel was originally developed by Richard Barry around 2003, and was later developed and maintained by Richard's company, Real Time Engineers Ltd. FreeRTOS was a runaway success, and in 2017 Real Time Engineers Ltd. passed stewardship of the FreeRTOS project to Amazon Web Services (AWS). Richard continues to work on FreeRTOS as part of an AWS team. 

Please refer for further information.

FreeRTOS Support for Xilinx Devices

FreeRTOS kernel port is available for following Xilinx processors:

Xilinx FreeRTOS source code: FreeRTOS port for Xilinx HW can be found at

FreeRTOS in the Xilinx Ecosystem

Xilinx FreeRTOS BSP comprises of FreeRTOS kernel, Xilinx libraries, Xilinx peripheral drivers  and Xilinx standalone library. Each of these components are explained in subsequent sections,

FreeRTOS Kernel

The FreeRTOS kernel consist of FreeRTOS core kernel + porting layer. For 2020.x releases,  FreeRTOS kernel 10.3.0 is being used

Xilinx Libraries 

Xilinx provides various OS independent libraries and 3rd party libraries (e.g. lwip). These libraries can be seamlessly used in Xilinx FreeRTOS environment.

Note about FreeRTOS+:  The FreeRTOS website supports an ecosystem of add-on products/components that are referred to as FreeRTOS+.  This ecosystem is separate from, and unrelated to, the Xilinx ecosystem support described on this page.  So, for example, the FreeRTOS+TCP product should not be confused with the Xilinx ecosystem solution that leverages FreeRTOS and lwip.  Additionally, several examples of FreeRTOS+ products running on Xilinx devices exist and these should not be interpreted as examples of how Xilinx supports FreeRTOS but, rather, examples of community driven contributions.

Xilinx peripheral drivers 

All Xilinx provided drivers are OS agnostic, they can be used with Xilinx FreeRTOS ecosystem

Xilinx Standalone library

Standalone library consist of boot code, vectors, basic IO APIs, light weight print functions, MMU/MPU APIs. and cache APIs Driver deals with the hardware through direct hardware interface implemented in standalone Library. Direct hardware interface is typically implemented as macros and constants, and it is designed such that developer can create a small applications or create a custom device driver using it. FreeRTOS kernel uses few of the APIs available in Xilinx standalone library

HW Platform requirement to run FreeRTOS

FreeRTOS requires tick timer to schedule the tasks. In order to run FreeRTOS on specific processor, the HW platform must have valid timer peripheral connected to the interrupt controller. Timer peripherals which can be used as tick timer in Xilinx ecosystem are as given below:

FreeRTOS Application Creation and Customization with Xilinx SDK

This section describes procedures to create FreeRTOS template applications and customization of kernel configuration.

FreeRTOS Application creation

Following steps describes procedure to create FreeRTOS hello world application using Xilinx SDK

  1. Select "New->Application Project" from the Vitis"File" menu. The New Project dialogue box will appear.

  2. Click Next button, In the New Project dialogue box, select the hardware platform as appropriate.

  3.  Click "Next" button
  4. Select intended processor i.e. "psu_cortexa53_0","psu_cortexr5_0","ps7_cortexa9_0","microblaze_0"  as the processor.

  5. Click "Next" button
  6. Select available FreeRTOS version as Operating system

  7. Click "Next" button
  8. Now application template dialogue box would appear on the screen.Select the FreeRTOS Hello World template, and click "Finish". 

  9. Vitis would create hw_platform, FreeRTOS BSP and application project. FreeRTOS kernel and other peripheral drivers for IP's in HW platform would be included in BSP project.

Customizing the FreeRTOS BSP configuration

Adding a New Kernel Parameter

Following steps describe procedure to add new configuration parameter to the FreeRTOS kernel,

  1. Add new parameter entry into entry into ThirdParty/bsp/freertos<release>_xilinx/data/freertos<release>_xilinx.mld. Let us say you need to add new parameter "foo" of type "int" under kernel_features category, entry in mld file will be as given below,

    BEGIN CATEGORY kernel_features
    PARAM name = kernel_features, type = bool, default = true, desc = "Include or exclude kernel features", permit = none;
    PARAM name = use_freertos_asserts, type = bool, default = true, desc = "Defines configASSERT() to assist development and debugging. The application can override the default implementation of vApplicationAssert( char *pcFile, uint32_t ulLine )";
    PARAM name = use_mutexes, type = bool, default = true, desc = "Set to true to include mutex functionality, or false to exclude mutex functionality.";
    PARAM name = use_getmutex_holder, type = bool, default = true, desc = "Set to true to use mutex xSemaphoreGetMutexHolder API, or false to exclude it.";
    PARAM name = use_recursive_mutexes, type = bool, default = true, desc = "Set to true to include recursive mutex functionality, or false to exclude recursive mutex functionality.";
    PARAM name = use_counting_semaphores, type = bool, default = true, desc = "Set to true to include counting semaphore functionality, or false to exclude recursive mutex functionality.";
    PARAM name = queue_registry_size, type = int, default = 10, desc = "The maximum number of queues that can be registered at any one time. Only registered queues can be viewed in the Eclipse/GDB kernel aware debugger plug-in.";
    PARAM name = use_trace_facility, type = bool, default = true, desc = "Set to true to include the legacy trace functionality, and a few other features. traceMACROS are the preferred method of tracing now.";
    PARAM name = use_newlib_reent, type = bool, default = false, desc = "When true each task will have its own Newlib reent structure.";
    PARAM name = use_queue_sets, type = bool, default = true, desc = "Set to true to include queue set functionality.";
    PARAM name = use_task_notifications, type = bool, default = true, desc = "Set to true to include direct to task notification functionality.";
    PARAM name = check_for_stack_overflow, type = int, default = 2, desc = "Set to 0 for no overflow checking. Set to 1 to include basic run time task stack checking. Set to 2 to include more comprehensive run time task stack checking.";
    PARAM name = use_stats_formatting_functions, type = bool, default = true, desc = "Set to 1 to include the vTaskList() and vTaskGetRunTimeStats() functions, which format run-time data into human readable text.";
    PARAM name = num_thread_local_storage_pointers, type = int, default = 0, desc ="Sets the number of pointers each task has to store thread local values.";
    PARAM name = use_task_fpu_support, type = int, default = 1, desc ="Set to 1 to create tasks without FPU context, set to 2 to have tasks with FPU context by default.";
    PARAM name = foo, type = int, default = 5, desc = "This is newly added parameter.";

  2. Read newly added parameter from  ThirdParty/bsp/freertos<release>_xilinx/data/freertos<release>_xilinx.mld and export it to  FreeRTOSConfig.h in the form of constants.  Code to do so can be found at end of "generate" proc inThirdParty/bsp/freertos<release>_xilinx/data/freertos<release>_xilinx.tcl. It needs to be added after below code snippet,

    ## Add constants common to all architectures to the configuration file.

    set config_file [xopen_new_include_file "./src/FreeRTOSConfig.h" "FreeRTOS Configuration parameters"]
    puts $config_file "\#include \"xparameters.h\" \n"

    e.g Following code snippet needs to be added to export constant for newly added kernel parameter "foo",

    set val [common::get_property $os_handle]
    xput_define $config_file "configUSE_FOO_VALUE" $val

  3. Now create FreeRTOS applications with changes mentioned in steps #1 and #2  of this section in builds

  4. Open FreeRTOS kernel configuration settings by right clicking on BSP project, you can see configuration for new parameter.

Floating Point Support

Details for configuration parameters related to the floating point support are as given below,

FreeRTOS Application Templates 

The following FreeRTOS application templates are provided with XSDK. 

FreeRTOS Hello World application 

This application demonstrates data sharing in-between different tasks through queues. It uses FreeRTOS software timer to check number of messages transmitted and received in between tasks through queue.  The source code for application can be found at .

The expected output is shown below: 

Hello from Freertos example main
Rx task received string from Tx task: Hello World
Rx task received string from Tx task: Hello World
Rx task received string from Tx task: Hello World
Rx task received string from Tx task: Hello World
Rx task received string from Tx task: Hello World
Rx task received string from Tx task: Hello World
Rx task received string from Tx task: Hello World
Rx task received string from Tx task: Hello World
Rx task received string from Tx task: Hello World
FreeRTOS Hello World Example PASSED.

LwiP based FreeRTOS applications

FreeRTOS Debug/Trace

FreeRTOS applications can be debugged in the Xilinx IDE (SDK or Vitis) as normal standalone applications.  So, for example, you can step through or break on task code but information about OS/task context is not provided by the IDE.

For task-aware debugging the IDE supports tracing with the System Trace Macrocell (STM) that became available as of ZynqUS+ devices (see UG1416 for details).  The results of doing an STM trace will provide detailed task information in a manner that is less invasive, and therefore preferred over, using traditional FreeRTOS trace hooks.  For architectures that do not have the STM (e.g. Zynq-7000 and MicroBlaze) 3rd party tools can be used to do task-aware debugging.  For example, users have reported success with Percepio Tracealyzer for both Zynq-7000 and MicroBlaze using the FreeRTOS trace hooks.

Xilinx Partnership with AWS for FreeRTOS IoT Solutions

Xilinx is an AWS partner and active participant in the AWS Device Qualification Program (DQP).   See for more information. 

AWS Qualified Devices

MicroZed Industrial IoT Kit

Change Log