Quality RTOS & Embedded Software

 Real time embedded FreeRTOS RSS feed 
Quick Start Supported MCUs PDF Books Trace Tools Ecosystem

Creating a New FreeRTOS Port
[More Advanced]

You do not need to read or understand this page if using one of the many existing ports and demo applications!

Porting FreeRTOS to a completely different and as yet unsupported microcontroller is not a trivial task. The aim of this page is to describe the house keeping preliminaries required to get a new port started.

Each port is moderately unique and very dependent on the processor and tools being used, so this page cannot provide specifics on the porting detail. There are however plenty of other FreeRTOS ports already in existence and it is suggested that these are used as a reference.

Porting within the same processor family is a much more straight forward task - for example, from one ARM7 based device to another. The documentation page detailing how to modify an existing demo application would be a good point to start reading if this is your aim.

Setting up the Directory Structure

The FreeRTOS kernel source code is generally contained within 3 source files (4 if co-routines are used) that are common to all ports, and one or two 'port' files that tailor the RTOS kernel to a particular architecture.

Suggested steps:

  1. Download the latest version of the FreeRTOS source code.

  2. Unzip the files into a convenient location, taking care to maintain the directory structure.

  3. Familiarise yourself with the source code organisation and directory structure.

  4. Create a directory that will contain the 'port' files for the [architecture] port. Following the convention outlined in the link, the directory should be of the form: FreeRTOS/Source/portable/[compiler name]/[processor name]. For example, if you are using the GCC compiler you can create a [architecture] directory off the existing FreeRTOS/Source/portable/GCC directory.

  5. Copy empty port.c and portmacro.h files into the directory you have just created. These files should just contain the stubs of the functions and macro's that require implementing. See existing port.c and portmacro.h files for a list of such functions and macros. You can create a stub file from one of these existing files by simply deleting the function and macro bodies.

  6. If the stack on the microcontroller being ported to grows downward from high memory to low memory then set portSTACK_GROWTH in portmacro.h to -1, otherwise set portSTACK_GROWTH to 1.

  7. Create a directory that will contain the demo application files for the [architecture] port. Following the convention again this should be of the form FreeRTOS/Demo/[architecture_compiler], or something similar.

  8. Copy existing FreeRTOSConfig.h and main.c files into the directory just created. Again these should be edited to be just stub files.

  9. Take a look at the FreeRTOSConfig.h file. It contains some macro's that will need setting for your chosen hardware.

  10. Create a directory off the directory just created and call it ParTest (probably FreeRTOS/Demo/[architecture_compiler]/ParTest). Copy into this directory a ParTest.c stub file.

  11. ParTest.c contains three simple functions to:

    1. Setup some GPIO that can flash a few LEDs,
    2. Set or clear a specific LED, and
    3. Toggle the state of an LED.

    These three functions need implementing for your development board. Having LED outputs working will facilitate the rest of the required work. Take a look at the many existing ParTest.c files included in the other demo projects for examples (the ParTest name is a historical anomaly for PARallel port TEST), and the page describing how to modify an existing demo application for information on writing and testing the ParTest.c functions.

Creating a Project

Now all the required files are in place you need to create a project (or makefile) that will successfully build them. Obviously they just contain stubs so will not yet do anything, but once they are building the stubs can incrementally be replaced with working functions.

The project will need to contain the following files:

  • Source/tasks.c
  • Source/Queue.c
  • Source/List.c
  • Source/portable/[compiler name]/[processor name]/port.c
  • Source/portable/MemMang/heap_1.c (or heap_2.c or heap_3.c or heap_4.c)
  • Demo/[processor name]/main.c
  • Demo/[Processor name]/ParTest/ParTest.c

The following directories need to be in the include path - please use relative paths from the Demo/[Process name] directory - NOT absolute paths:

  • Demo/Common (i.e. ../Common)
  • Demo/[Processor Name]
  • Source/include
  • Source/portable/[Compiler name]/[Processor name]

Implementing the Stubs

Now the difficult bit. Once the project is compiling the portable layer stubs require implementation. It is suggested that pxPortInitialiseStack() is the first function to be implemented. To implement pxPortInitialiseStack() you must first decide upon your task context stack frame structure, which is very architecture dependent.

Getting Help

Don't forget that WITTENSTEIN high integrity systems offer a full porting and testing service!

[ Back to the top ]    [ About FreeRTOS ]    [ Privacy ]    [ Sitemap ]    [ ]

Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.

Latest News

NXP tweet showing LPC5500 (ARMv8-M Cortex-M33) running FreeRTOS.

Meet Richard Barry and learn about running FreeRTOS on RISC-V at FOSDEM 2019

Version 10.1.1 of the FreeRTOS kernel is available for immediate download. MIT licensed.

View a recording of the "OTA Update Security and Reliability" webinar, presented by TI and AWS.


FreeRTOS and other embedded software careers at AWS.

FreeRTOS Partners

ARM Connected RTOS partner for all ARM microcontroller cores

Espressif ESP32

IAR Partner

Microchip Premier RTOS Partner

RTOS partner of NXP for all NXP ARM microcontrollers


STMicro RTOS partner supporting ARM7, ARM Cortex-M3, ARM Cortex-M4 and ARM Cortex-M0

Texas Instruments MCU Developer Network RTOS partner for ARM and MSP430 microcontrollers

OpenRTOS and SafeRTOS

Xilinx Microblaze and Zynq partner