Source Organization
[FreeRTOS Fundamentals]

Basic directory structure

The FreeRTOS download includes source code for every processor port, and every demo application. Placing all the ports in a single download greatly simplifies distribution, but the number of files may seem daunting. The directory structure is however very simple, and the FreeRTOS real time kernel is contained in just 3 files (4 if co-routines are used).

From the top, the download is split into two sub directories:

FreeRTOS 
    ¦
    +-Demo      Contains the demo application.
    ¦
    +-Source    Contains the real time kernel source code.

The majority of the real time kernel code is contained in three files that are common to every processor architecture (four if co-routines are used). These files, tasks.c, queue.c and list.c, are in the source directory.

Each processor architecture requires a small amount of kernel code specific to that architecture. The processor specific code is contained in a directory called Portable, under the Source directory.

The download also contains a demo application for every processor architecture and compiler port. The majority of the demo application code is common to all ports and is contained in a directory called Common, under the Demo directory. The remaining sub directories under Demo contain build files for building the demo for that particular port.

FreeRTOS 
    ¦
    +-Demo 		
    ¦   ¦
    ¦   +-Common    The demo application files that are used by all the ports.
    ¦   +-Dir x     The demo application build files for port x
    ¦   +-Dir y     The demo application build files for port y
    ¦
    +-Source	
        ¦
        +-Portable  Processor specific code.

The following subsections provide more details of the Demo and Source directories.

RTOS source code directory list
[the Source directory]

To use FreeRTOS you need to include the real time kernel source files in your makefile. It is not necessary to modify them or understand their implementation.

The real time kernel source code consists of three files that are common to all microcontroller ports (four if co-routines are used), and a single file that is specific to the port you are using. The common files can be found in the FreeRTOS/Source directory. The port specific files can be found in subdirectories contained in the FreeRTOS/Source/Portable directory.

For example:

If using the MSP430 port with the GCC compiler:
The MSP430 specific file (port.c) can be found in the FreeRTOS/Source/Portable/GCC/MSP430F449 directory, and all the other sub directories in the FreeRTOS/Source/Portable directory relate to other microcontroller ports and can be ignored.
If using the PIC18 port with the MPLAB compiler:
The PIC18 specific file (port.c) can be found in the FreeRTOS/Source/Portable/MPLAB/PIC18 directory, and all the other sub directories in the FreeRTOS/Source/Portable directory relate to other microcontroller ports and can be ignored.
And so on for all the ports ...

FreeRTOS/Portable/MemMang contains the sample memory allocators as described in the memory management section.

Demo application source code directory list
[the Demo directory]

The Demo directory tree contains a demo application for each port. Most of the code for the demo application is common to every port. The code that is common to every port is located in the FreeRTOS/Demo/Common directory. See the demo application section for more details. Port specific code, including the demo application project files, can be found in sub directories contained in the FreeRTOS/Demo directory.

For example:

If building the MSP430 GCC demo application:
The MSP430 demo application makefile can be found in the FreeRTOS/Demo/MSP430 directory. All the other sub directories contained in the FreeRTOS/Demo directory (other than the Common directory) relate to demo application's targeted at other microcontrollers and can be ignored.
If building the PIC18 MPLAB demo application:
The PIC18 demo application project file can be found in the FreeRTOS/Demo/PIC18_MPLAB directory. All the other sub directories contained in the FreeRTOS/Demo directory (other than the Common directory) relate to demo application's targeted at other microcontrollers and can be ignored.
And so on for all the ports ...

Creating your own application

When writing your own application it is preferable to use the demo application makefile (or project file) as a starting point. You can leave all the files included from the Source directory included in the makefile, and replace the files included from the Demo directory with those for your own application. This will ensure both the RTOS source files included in the makefile and the compiler switches used in the makefile are both correct.

The complete directory tree

The entire directory tree is shown below - including a brief description of each node:

FreeRTOS 
 ¦
 +-Demo             Contains all directories associated with the demo application, one sub directory per port.
 ¦   ¦
 ¦   +-Common                   Demo application files common to all ports
 ¦   ¦   +-Minimal                 Minimal version of common demo application files 
 ¦   ¦   +-Full                    Full version of common demo application files 
 ¦   ¦   +-include                 Demo application header files
 ¦   ¦
 ¦   +-ARM7_AtmelSAM7S64_IAR    Demo application source code for the AT91SAM7S64 port using the IAR compiler
 ¦   ¦   +-ParTest 	
 ¦   ¦   +-serial	
 ¦   ¦
 ¦   +-ARM7_AT91SAM7X256_Eclipse Demo application source code for the AT91SAM7X port using GCC and Eclipse
 ¦   ¦   +-Webserver 	
 ¦   ¦   +-USB	
 ¦   ¦
 ¦   +-ARM7_LPC2106_GCC         Demo application source code for the LPC2106 port
 ¦   ¦   +-ParTest 	
 ¦   ¦   +-serial	
 ¦   ¦
 ¦   +-ARM7_LPC2129_Keil        Demo application source code for the LPC2109 port using the Keil compiler
 ¦   ¦   +-ParTest 	
 ¦   ¦   +-serial	
 ¦   ¦
 ¦   +-ARM7_AT91FR40008_GCC     Demo application source code for the AT91 port using the GCC compiler
 ¦   ¦   +-ParTest 	
 ¦   ¦   +-serial	
 ¦   ¦
 ¦   +-ARM7_STR75x_IAR          Demo application source code for the STR75x port using the IAR compiler
 ¦   ¦   +-ParTest 	
 ¦   ¦   +-serial	
 ¦   ¦
 ¦   +-ARM7_STR71x_IAR          Demo application source code for the STR71x port using the IAR compiler
 ¦   ¦   +-ParTest 	
 ¦   ¦   +-serial	
 ¦   ¦
 ¦   +-ARM9_STR91X_IAR          Demo application source code for the STR912 port using the IAR compiler
 ¦   ¦   +-ParTest 	
 ¦   ¦   +-serial	
 ¦   ¦   +-webserver
 ¦   ¦
 ¦   +-ARM7_LPC2138_Rowley      Demo application project for the LPC2138 ARM7 port using the CrossStudio tools
 ¦   ¦
 ¦   +-ARM7_LPC2138_Eclipse     Demo application project for the LPC2138 ARM7 port using GCC and Eclipse.
 ¦   ¦
 ¦   +-HCS12_CodeWarrior_small  Demo application source code for the HCS12 port small memory model
 ¦   ¦   +-ParTest 	
 ¦   ¦   +-serial	
 ¦   ¦
 ¦   +-HCS12_CodeWarrior_banked Demo application source code for the HCS12 port banked memory model
 ¦   ¦   +-ParTest 	
 ¦   ¦   +-serial	
 ¦   ¦
 ¦   +-H8S                      Demo application source code for the H8/S port
 ¦   ¦   +-ParTest 	
 ¦   ¦   +-serial	
 ¦   ¦
 ¦   +-MSP430                   Demo application source code for the MSP430F449 port
 ¦   ¦   +-ParTest 	
 ¦   ¦   +-serial	
 ¦   ¦
 ¦   +-AVR32_UC3                Demo application source code for the AVR32 port using the GCC and IAR compiler
 ¦   ¦   +-AT32UC3A 	
 ¦   ¦       +-GCC              Make file to build the standard AVR32 demo using the GCC compiler
 ¦   ¦       +-IAR              Make file to build the standard AVR32 demo using the IAR compiler
 ¦   ¦
 ¦   +-AVR_ATMega323_WinAVR     Demo application source code for the AVR port using the GCC compiler
 ¦   ¦   +-ParTest 	
 ¦   ¦   +-serial	
 ¦   ¦
 ¦   +-AVR_ATMega323_IAR        Demo application source code for the AVR port using the IAR compiler
 ¦   ¦   +-ParTest 	
 ¦   ¦   +-serial	
 ¦   ¦
 ¦   +-PIC32_MPLAB              Demo application source code for PIC32 (MIPS M4K) port using MPLAB and the C32 compiler
 ¦   ¦   +-ParTest 	
 ¦   ¦   +-serial	
 ¦   ¦
 ¦   +-PIC18_MPLAB              Demo application source code for PIC18 port using the MPLAB compiler
 ¦   ¦   +-ParTest 	
 ¦   ¦   +-serial	
 ¦   ¦
 ¦   +-PIC18_WIZC               Demo application source code for PIC18 port using the WizC compiler
 ¦   ¦   +-ParTest 	
 ¦   ¦   +-serial	
 ¦   ¦
 ¦   +-PIC24_MPLAB              Demo application source code for PIC24 port using the MPLAB compiler
 ¦   ¦   +-ParTest 	
 ¦   ¦   +-serial	
 ¦   ¦
 ¦   +-dsPIC_MPLAB              Demo application source code for dsPIC port using the MPLAB compiler
 ¦   ¦   +-ParTest 	
 ¦   ¦   +-serial	
 ¦   ¦
 ¦   +-Cygnal                   Demo application source code for Cygnal (Silicon labs) 8051 port
 ¦   ¦   +-ParTest 	
 ¦   ¦   +-serial	
 ¦   ¦
 ¦   +-Flshlite                 Demo application source for Flashlite 186 port
 ¦   ¦   +-FileIO		
 ¦   ¦   +-serial	
 ¦   ¦   +-ParTest	
 ¦   ¦
 ¦   +-Microblaze               Demo application source for Xilinx Microblaze port
 ¦   ¦   +-serial	
 ¦   ¦   +-ParTest	
 ¦   ¦
 ¦   +-CORTEX_STM32F103_IAR     Demo application source for the STM32F103 Cortex-M3 port using the IAR tools
 ¦   ¦
 ¦   +-CORTEX_STM32F103_Primer_GCC Demo application source for the STM32F103 Cortex-M3 port using the GCC and RIDE tools
 ¦   ¦
 ¦   +-CORTEX_LM3S102_GCC       Demo application source for the LM3S102 Cortex-M3 port using the GCC tools
 ¦   ¦
 ¦   +-CORTEX_LM3S102_Keil      Demo application source for the LM3S102 Cortex-M3 port using the Keil/RVDS tools
 ¦   ¦
 ¦   +-CORTEX_LM3S102_Rowley    Demo application source for the LM3S102 Cortex-M3 port using Rowley CrossWorks
 ¦   ¦
 ¦   +-CORTEX_LM3S316_IAR       Demo application source for the LM3S314 Cortex-M3 port using IAR
 ¦   ¦
 ¦   +-CORTEX_LM3S811_GCC       Demo application source for the LM3S811 Cortex-M3 port using the GCC tools
 ¦   ¦
 ¦   +-CORTEX_LM3S811_IAR       Demo application source for the LM3S811 Cortex-M3 port using IAR
 ¦   ¦
 ¦   +-CORTEX_LM3S811_KEIL      Demo application source for the LM3S811 Cortex-M3 port using Keil
 ¦   ¦
 ¦   +-CORTEX_LM3Sxxxx_IAR_Keil Demo application source for the LM3S6965, LM3S2965, LM3S1962 and LM3S8962 Cortex-M3 port using IAR and Keil
 ¦   ¦
 ¦   +-CORTEX_LM3Sxxxx_Eclipse  Demo application source for the LM3S6965, LM3S2965, LM3S1962 and LM3S8962 Cortex-M3 port using Eclipse with GCC
 ¦   ¦
 ¦   +-uIP_Demo_IAR_ARM7        Embedded WEB server demo using uIP and the IAR development tools
 ¦   ¦
 ¦   +-lwIP_Demo_Rowley_ARM7    Embedded WEB server demo using lwIP and the Rowley development tools
 ¦   ¦
 ¦   +-lwIP_AVR32_UC3           Embedded WEB and TFTP server demo using lwIP and GCC on the AT32UC3A0512 AVR32
 ¦   ¦
 ¦   +-uIP_Demo_Rowley_ARM7     Embedded WEB server demo using uIP and the Rowley development tools
 ¦   ¦
 ¦   +-WizNET_DEMO_GCC_ARM7     Embedded WEB server demo application using the WizNET coprocessor with I2C interface
 ¦   ¦
 ¦   +-WizNET_DEMO_TERN_186     Embedded WEB server demo application using the WizNET coprocessor with mapped interface
 ¦   ¦
 ¦   +-MB91460_Softune          Demo application source for the MB91460 series of microcontrollers from Fujitsu
 ¦   ¦
 ¦   +-MB96340_Softune          Demo application source for the MB96340 series of microcontrollers from Fujitsu
 ¦   ¦
 ¦   +-PC                       Demo application source for PC port
 ¦       +-FileIO	
 ¦       +-ParTest	
 ¦       +-serial	
 ¦   
 +-Source           Contains all directories associated with the scheduler source code
    ¦
    ¦               3 core scheduler files common to all ports (4 is using co-routines)
    ¦
     +-include                  Scheduler header files
     ¦	
     +-portable                 Scheduler port layer for all ports
         ¦
         +-MemMang                  Sample memory allocators can be used for all ports
         ¦
         ¦
         +-GCC                      Scheduler port layer for ports using GCC compiler
         ¦   +-ATmega32                 Scheduler port files for AVR using GCC compiler
         ¦   +-MSP430F449               Scheduler port files for MSP430 using GCC compiler
         ¦   +-ARM7_LPC2000             Scheduler port files for LPC2106 using GCC compiler
         ¦   +-ARM7_AT91FR40008         Scheduler port files for AT91 using GCC compiler
         ¦   +-H8S2329                  Scheduler port files for H8/S using GCC compiler
         ¦   +-Microblaze               Scheduler port files for Microblaze using GCC compiler
         ¦   +-ARM_MC3                  Scheduler port files for ARM Cortex-M3 using GCC compiler
         ¦   +-AVR32_UC3                Scheduler port files for AVR32 AT32UC3A using GCC compiler
         ¦
         ¦
         +-RVDS                     Scheduler port layer for ports using RVDS/Keil compiler
         ¦   +-ATmega32                 Scheduler port files for ARM Cortex-M3 port
         ¦
         ¦
         +-IAR                      Scheduler port layer for ports using IAR compiler
         ¦   +-ATmega32                 Scheduler port files for AVR using IAR compiler
         ¦   +-AtmelSAM7S64             Scheduler port files for SAM7 using IAR compiler
         ¦   +-STR71x                   Scheduler port files for STR71x using IAR compiler
         ¦   +-STR91x                   Scheduler port files for STR91x using IAR compiler
         ¦   +-ARM_CM3                  Scheduler port files for Cortex-M3 using IAR compiler
         ¦   +-LPC2000                  Scheduler port files for Philips LPC2000 using IAR compiler
         ¦   +-AVR32_UC3                Scheduler port files for AVR32 AT32UC3A using the IAR compiler
         ¦
         ¦
         +-Keil                     Scheduler port layer for ports using Keil compiler
         ¦   +-ARM7                     Scheduler port files for ARM7 using Keil compiler
         ¦
         ¦
         +-Softune                  Scheduler port layer for ports using Softune compiler
         ¦   +-MB91460                  Scheduler port files for MB91460 using the Softune compiler
         ¦   +-MB96340                  Scheduler port files for MB96340 using the Softune compiler
         ¦
         ¦
         +-CodeWarrior              Scheduler port layer for ports using CodeWarrior compiler
         ¦   +-HCS12                    Scheduler port files for HCS12 using CodeWarrior compiler
         ¦
         ¦
         +-MPLAB                    Scheduler port layer for ports using Microchip C18 compiler
         ¦   +-PIC18                    Scheduler port files for PIC18 using Microchip C18 compiler
         |   +-PIC24_dsPIC              Scheduler port files for PIC24, dsPIC
         |   +-PIC32                    Scheduler port files for PIC32
         ¦
         ¦
         +-SDCC                     Scheduler port layer for ports using SDCC compiler
         ¦   +-Cygnal                   Scheduler port files for Cygnal 8051 using SDCC compiler
         ¦
         ¦
         +-oWatcom                  Scheduler port layer for ports using Open Watcom compiler
         ¦   +-Flsh186                  Scheduler port files for Flashlite 186 port	
         ¦   +-common                   Scheduler port files common to all OW DOS based ports
         ¦   +-PC                       Scheduler port files for PC port
         ¦
         ¦
         +-Paradigm                 Scheduler port layer for ports using Paradigm compiler
         ¦   +-Tern_EE                  Scheduler port files for Tern 186 port	
         ¦      +-small                    Small memory model port for Tern 186
         ¦      +-large_untested           Large memory model port for Tern 186 - untested!
         ¦
         ¦
         +-BCC                      Scheduler port layer for ports using Borland compiler
             +-Flsh186                  Scheduler port files for Flashlite 186 port	
             +-common                   Scheduler port files common to all BCC DOS based ports
             +-PC                       Scheduler port files for PC port

Naming Conventions

The RTOS kernel and demo application source code use the following conventions:

Variables

Variables of type char are prefixed c
Variables of type short are prefixed s
Variables of type long are prefixed l
Variables of type float are prefixed f
Variables of type double are prefixed d
Enumerated variables are prefixed e
Other types (e.g. structs) are prefixed x
Pointers have an additional prefixed p, for example a pointer to a short will have prefix ps
Unsigned variables have an additional prefixed u, for example an unsigned short will have prefix us

Functions

File private functions are prefixed with prv
API functions are prefixed with their return type, as per the convention defined for variables
Function names start with the file in which they are defined. For example vTaskDelete is defined in Task. c

Data Types

Data types are not directly referenced within the RTOS kernel source code. Instead each port has it's own set of definitions. For example, the char type is #defined to portCHAR, the short data type is #defined to portSHORT, etc. The demo application source code also uses this notation - but this is not necessary and your application can use whatever notation you prefer.

In addition there are two other types that are defined for each port. These are:

portTickType
This is a configurable as either an unsigned 16bit type or an unsigned 32bit type. See the customisation section of the API documentation for full information.
portBASE_TYPE
This is defined for each port to be the most efficient type for that particular architecture.

If portBASE_TYPE is define to char then particular care must be taken to ensure signed chars are used for function return values that can be negative to indicate an error.

Copyright (C) 2003 - 2008 Richard Barry
Any and all data, files, source code, html content and documentation included in the FreeRTOS distribution or available on this site are the exclusive property of Richard Barry. See the files license.txt (included in the distribution) and this copyright notice for more information. FreeRTOS^TM and FreeRTOS.org^TM are trade marks of Richard Barry.

Source Organization [FreeRTOS Fundamentals]