|
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.
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):
-
FreeRTOS/Source/include
-
FreeRTOS/Source/portable/[compiler]/[architecture].
-
Whichever directory contains the FreeRTOSConfig.h file to be used - see the Configuration File paragraph below.
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.
Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.
|
