FreeRTOS

Created by Confluence Wiki Admin (Unlicensed)
Last updated: Mar 03, 2022 by Terry O'NealVersion comment

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

Table of Contents

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.

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

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.


  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

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

  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: 

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

AWS Qualified Devices

MicroZed Industrial IoT Kit


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