Creating a New FreeRTOS Project
[More Advanced]

Introduction

FreeRTOS is designed to be simple and easy to use: Only 3 source files that are common to all RTOS ports, and one microcontroller specific source file are required, and its API is designed to be simple and intuitive.

FreeRTOS is ported to many different microcontroller architectures, and many different compilers. Each official port comes with an official demo that (at least at the time of its creation) compiles and executes on the hardware platform on which it was developed without any modification.

The demo projects are provided to ensure new users can get started with FreeRTOS in the quickest possible time, and with the minimum of fuss.

Each architecture supported by FreeRTOS is used in many different microcontrollers, meaning FreeRTOS can be used with literally thousands of different microcontroller part numbers. Multiplying this number by the number of supported compilers, and then multiplying again by the ever increasing number of starter kits and evaluation boards that are being brought to the market, and it is obvious that, despite our best efforts, we can only provide official demo projects that exactly match a tiny fraction of possible combinations.

It is always recommended that a new FreeRTOS project is created by starting with, and then adapting, one of the provided pre-configured demos. Doing this ensures the new project includes all the necessary source and header files, and installs the necessary interrupt service routines, with no effort on the part of the project's creator.

Some FreeRTOS users also want to know how to create FreeRTOS projects by means other than adapting an existing project. The procedure for doing this is documented below.


Anatomy of a FreeRTOS Project

A FreeRTOS application will start up and execute just like a non-RTOS application until vTaskStartScheduler() is called. vTaskStartScheduler() is normally called from the application's main() function. The RTOS only controls the execution sequencing after vTaskStartScheduler() has been called.


It is highly recommended to ensure that code is executing correctly (correct start up code, correct linker configuration, etc.) on the chosen target before attempting to use any RTOS functionality.


Source Files

FreeRTOS is supplied as standard C source files that are be built along with all the other C files in your project. The FreeRTOS source files are distributed in a zip file. The RTOS source code organisation page describes the structure of the files in the zip file.

As a minimum, the following source files must be included in your project:

If the directory that contains the port.c file also contains an assembly language file, then the assembly language file must also be used.


Optional Source Files

If you need software timer functionality, then add FreeRTOS/Source/timers.c to your project.

If you need event group functionality, then add FreeRTOS/Source/event_groups.c to your project.

If you need steam buffer or message buffer functionality, then add FreeRTOS/Source/stream_buffer.c to your project.

If you need co-routine functionality, then add FreeRTOS/Source/croutine.c to your project (note co-routines are deprecated and not recommended for new designs).


Header Files

The following directories must be in the compiler's include path (the compiler must be told to search these directories for header files): Depending on the port, it may also be necessary for the same directories to be in the assembler's include path.


Configuration File

Every project also requires a file called FreeRTOSConfig.h. FreeRTOSConfig.h tailors the RTOS kernel to the application being built. It is therefore specific to the application, not the RTOS, and should be located in an application directory, not in one of the RTOS kernel source code directories.

If heap_1, heap_2, heap_4 or heap_5 is included in your project, then the FreeRTOSConfig.h definition configTOTAL_HEAP_SIZE will dimension the FreeRTOS heap. Your application will not link if configTOTAL_HEAP_SIZE is set too high.

The FreeRTOSConfig.h definition configMINIMAL_STACK_SIZE sets the size of the stack used by the idle task. If configMINIMAL_STACK_SIZE is set too low, then the idle task will generate stack overflows. It is advised to copy the configMINIMAL_STACK_SIZE setting from an official FreeRTOS demo provided for the same microcontroller architecture. The FreeRTOS demo projects are stored in sub directories of the FreeRTOS/Demo directory. Note that some demo projects are old, so do not contain all the available configuration options.


Interrupt Vectors

[Cortex-M users: Information on installing interrupt handers is provided in the "The application I created compiles, but does not run" FAQ]

Every RTOS port uses a timer to generate a periodic tick interrupt. Many ports use additional interrupts to manage context switching. The interrupts required by an RTOS port are serviced by the provided RTOS port source files.

The method used to install the interrupt handlers provided by the RTOS port is dependent on the port and compiler being used. Refer to, and if necessary copy, the provided official demo application for the port being used. Also refer to the documentation page provided for the official demo application.