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

...

Introduction 

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 https://www.freertos.org/RTOS.html for further information.

FreeRTOS Support for Xilinx Devices

FreeRTOS kernel port is available for following Xilinx processors:

• 64-bit Cortex-A53 Application processor (APU) & 32-bit Cortex-R5 Real-time processor (RPU)
  • ZynqUS+ SoC devices
• 64-bit Cortex-A72 Application processor (APU) & 32-bit Cortex-R5 Real-time processor (RPU)
  
  • Versal SoC devices

• 32-bit Cortex-A9 Application processor (APU)
  • Zynq-7000 SoC devices 
• 32-bit MicroBlaze processor
  • All Xilinx device families
    
    

Xilinx FreeRTOS source code: FreeRTOS port for Xilinx HW can be found at https://github.com/Xilinx/embeddedsw/tree/master/ThirdParty/bsp

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 2021.x releases,  FreeRTOS kernel 10.4.3 is being used

• • FreeRTOS core kernel: Xilinx uses core kernel source as-is from https://sourceforge.net/projects/freertos/files/FreeRTOS
  • Porting layer: Source code for porting  FreeRTOS to various Xilinx HW can be found at  embeddedsw/ThirdParty/bsp/freertos<FreeRTOS major version>_xilinx/src/Source/portable/GCC 

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.

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:

• Zynq UltraScale+: Cortex-A53 64 bit processor - Triple Counter Counter (TTC)  IP
                          Cortex-R5 32 bit processor - TTC IP
• Versal : Cortex-A72 64 bit processor - Triple Counter Counter (TTC)  IP
                          Cortex-R5 32 bit processor - TTC IP
• Zynq-7000: Cortex-A9 32 bit processor - TTC IP
• MicroBlaze Processor :  AXI Timer or  TTC IP from PS block interrupting to the MicroBlaze (via AXI interrupt controller)

FreeRTOS Application Creation and Customization

This section describes procedures to create FreeRTOS template applications and customization of kernel configuration using the Vitis Unified Software Platform. 

FreeRTOS Application creation

The following steps describe the procedure to create FreeRTOS hello world application. 

1. Select "New->Application Project" from the Vitis "File" menu. The New Project dialogue box will appear.
   
   Image Modified
   
2. Click Next button, In the New Project dialogue box, select the hardware platform as appropriate.
   
   Image Modified
   
   
   
3.  Click "Next" button
4. Select intended processor i.e. "psu_cortexa53_0","psu_cortexr5_0","ps7_cortexa9_0","microblaze_0"  as the processor.
   
   Image Modified
5. Click "Next" button
6. Select available FreeRTOS version as Operating system
   
   Image Modified
7. Click "Next" button
8. Now application template dialogue box would appear on the screen.Select the FreeRTOS Hello World template, and click "Finish". 
   
   Image Modified
   
   
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.
   Image Modified
   

Customizing the FreeRTOS BSP configuration

• Double click on platform.spr file under platform project
  
  Image Modified
  
  
  
• Click on "Modify BSP Setting" button of domain_psu_cortexa53_0, you would see following dialogue,
  
  Image Modified
  
  
  
• Select freertos<release>_xilinx from top left corner of dialogue box, you can see FreeRTOS configuration dialogue as shown below,
  
  Image Modified
  
  
  
• You can edit the configurations as per your requirement and click OK button, <BSP path>/<processor name>/libsrc/<FreeRTOS release version>/src/FreeRTOSConfig.h would be updated with the edited settings.
• Note:
  • From 2023.2, the default Vitis GUI would be different, in order to match with these steps ,open Vitis in classic mode as “Vitis - -classic"

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."; END CATEGORY

   
   

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 CONFIG.foo $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,

• Zynq UltraScale+
  • Cortex-A53 BSP:  By default floating point context saving/restoring  will be disabled. Any task that uses the floating point unit must call vPortTaskUsesFPU() before any floating point instructions are executed.
    
  • Cortex-R5 BSP: : By default floating point context saving/restoring  will be disabled. Any task that uses the floating point unit must call vPortTaskUsesFPU() before any floating point instructions are executed.
• Zynq-7000
  
  • Cortex-A9 BSP:  HW floating point context saving/restoring  depends on the kernel configuration parameter "use_task_fpu_support". Possible values for these parameter are 1 & 2,
    
    • use_task_fpu_support = 1 -   create tasks without FPU context,  . Any task that uses the floating point unit must call vPortTaskUsesFPU() before any floating point instructions are executed.
      
    • use_task_fpu_support = 2 -   have tasks with FPU context by default
      
    Default value of  use_task_fpu_support  is 1 in Xilinx ecosystem.
• Non-Zynq Devices :  Floating point support is not available for the MicroBlaze FreeRTOS BSP.
  

FreeRTOS Application Templates 

The following FreeRTOS application templates are provided with Vitis. 

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 https://github.com/Xilinx/embeddedsw/tree/master/lib/sw_apps/freertos_hello_world .

The expected output is shown below: 

LwiP based FreeRTOS applications

• FreeRTOS lwIP echo server: https://github.com/Xilinx/embeddedsw/tree/master/lib/sw_apps/freertos_lwip_echo_server 
• FreeRTOS lwIP TCP perf client: https://github.com/Xilinx/embeddedsw/tree/master/lib/sw_apps/freertos_lwip_tcp_perf_client
• FreeRTOS lwIP TCP perf server: https://github.com/Xilinx/embeddedsw/tree/master/lib/sw_apps/freertos_lwip_tcp_perf_server
• FreeRTOS lwIP UDP perf client: https://github.com/Xilinx/embeddedsw/tree/master/lib/sw_apps/freertos_lwip_udp_perf_client
• FreeRTOS lwIP UDP perf server: https://github.com/Xilinx/embeddedsw/tree/master/lib/sw_apps/freertos_lwip_udp_perf_server

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.

...

• Avnet Product Page: http://zedboard.org/product/microzed-iiot-bundle-amazon-freertos
• AWS Partner Catalog: https://devices.amazonaws.com/detail/a3G0L00000AANtqUAH/MicroZed-IIoT-Bundle-with-Amazon-FreeRTOS
• AWS Getting Started Guide: https://docs.aws.amazon.com/freertos/latest/userguide/getting_started_xilinx.html
• Code and Demos (2018.2): https://github.com/aws/amazon-freertos

Change Log

2024.1

https://github.com/Xilinx/embeddedsw/blob/xlnx_rel_v2024.1/doc/ChangeLog#L744

2023.2

https://github.com/Xilinx/embeddedsw/blob/xlnx_rel_v2023.2/doc/ChangeLog#L522

2023.1

https://github.com/Xilinx/embeddedsw/blob/xlnx_rel_v2023.1/doc/ChangeLog#L224

2022.2

https://github.com/Xilinx/embeddedsw/blob/xlnx_rel_v2022.2/doc/ChangeLog#L216

2022.1

https://github.com/Xilinx/embeddedsw/blob/xlnx_rel_v2022.1/doc/ChangeLog#L24

2021.2

https://github.com/Xilinx/embeddedsw/blob/xlnx_rel_v2021.2/doc/ChangeLog#L88

2021.1

https://github.com/Xilinx/embeddedsw/blob/xlnx_rel_v2021.1/doc/ChangeLog#L155

2020.2:

•  Added support for FreeRTOS domU guest for CortexA53
•  Added example to demonstrate interrupt handling in FreeRTOS applications
• Updated makefile for parallel make execution and incremental build support.

2020.1:

•  Upgraded FreeRTOS version from 10.1.1 to 10.3.0
• Fix memory allocation issue in freertos_static_allocation.c application

2019.1: 

• Updated to FreeRTOS 10.1.1

...