Quality RTOS & Embedded Software

 Real time embedded FreeRTOS RSS feed 
Real time embedded FreeRTOS mailing list 
Quick Start Supported MCUs PDF Books Trace Tools Ecosystem TCP & FAT Training




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:

  • FreeRTOS/Source/tasks.c
  • FreeRTOS/Source/queue.c
  • FreeRTOS/Source/list.c
  • FreeRTOS/Source/portable/[compiler]/[architecture]/port.c.
  • FreeRTOS/Source/portable/MemMang/heap_x.c where 'x' is 1, 2, 3, 4 or 5.
If the directory that contains the port.c file also contains an assembly language file, then the assembly language file must also be used.

If you need software timer functionality, then include FreeRTOS/Source/timers.c.

If you need co-routine functionality, then include FreeRTOS/Source/croutine.c.


Header Files

As a minimum, the following directories must be in the compiler's include path (the compiler must be told to search these directories for header files):
  • FreeRTOS/Source/include
  • FreeRTOS/Source/portable/[compiler]/[architecture].
Depending on the port, it may also be necessary for the same directories to be in the assemblers 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.




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




Copyright (C) 2004-2010 Richard Barry. Copyright (C) 2010-2016 Real Time Engineers Ltd.
Any and all data, files, source code, html content and documentation included in the FreeRTOSTM distribution or available on this site are the exclusive property of Real Time Engineers Ltd.. See the files license.txt (included in the distribution) and this copyright notice for more information. FreeRTOSTM and FreeRTOS.orgTM are trade marks of Real Time Engineers Ltd.

Latest News:

FreeRTOS V9.0.0 is now available for download.


Free TCP/IP and file system demos for the RTOS


Sponsored Links

⇓ Now With No Code Size Limit! ⇓
⇑ Free Download Without Registering ⇑


FreeRTOS Partners

ARM Connected RTOS partner for all ARM microcontroller cores

Renesas Electronics Gold Alliance RTOS Partner.jpg

Microchip Premier RTOS Partner

RTOS partner of NXP for all NXP ARM microcontrollers

Atmel RTOS partner supporting ARM Cortex-M3 and AVR32 microcontrollers

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

Xilinx Microblaze and Zynq partner

Silicon Labs low power RTOS partner

Altera RTOS partner for Nios II and Cortex-A9 SoC

Freescale Alliance RTOS Member supporting ARM and ColdFire microcontrollers

Infineon ARM Cortex-M microcontrollers

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

Cypress RTOS partner supporting ARM Cortex-M3

Fujitsu RTOS partner supporting ARM Cortex-M3 and FM3

Microsemi (previously Actel) RTOS partner supporting ARM Cortex-M3

Atollic Partner

IAR Partner

Keil ARM Partner

Embedded Artists