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 2020.x releases, FreeRTOS kernel 10.3.0 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.

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:

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 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

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

Double click on platform.spr file under platform project
Click on "Modify BSP Setting" button of domain_psu_cortexa53_0, you would see following dialogue,
Select freertos<release>_xilinx from top left corner of dialogue box, you can see FreeRTOS configuration dialogue as shown below,
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.

Adding a New Kernel Parameter

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

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

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

Now create FreeRTOS applications with changes mentioned in steps #1 and #2 of this section in builds
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 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 https://github.com/Xilinx/embeddedsw/tree/master/lib/sw_apps/freertos_hello_world .

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 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.

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 https://aws.amazon.com/partners/dqp/partners/ for more information.

AWS Qualified Devices

MicroZed Industrial IoT Kit

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

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

2018.3:

Updated FreeRTOS tcl to support hierarchical designs

FreeRTOS

Table of Contents