Homepage  

FreeRTOS.org Demo Applications
[RTOS Demo Applications]

Introduction

The RTOS source code download includes a demonstration project for each port. The sample projects are preconfigured to execute on the single board computer or prototyping board used during the port development. Each should build directly as downloaded without any warnings or errors.

The demonstration projects are provided as:

1. An aid to learning how to use FreeRTOS - each source file demonstrates a component of the RTOS.

2. A preconfigured starting point for new applications - to ensure the correct development tool setup (compiler switches, debugger format, etc) it is recommended that new applications are created by modifying the existing demo projects.

Locating a demo application

Every demo application is located in a subdirectory off the FreeRTOS/Demo directory. The name of each such subdirectory describes the configuration of the demo application it contains. Please see the FreeRTOS.org source code organization page for a full explanation of the FreeRTOS.org directory structure.

Demo specific documentation

This WEB site contains a documentation page for each demo application included in the FreeRTOS.org download. These pages contain valuable and time saving information, such as how to setup the hardware and how to build the demo. Links to each demo documentation page can be found under 'RTOS Ports' in the menu frame on the left (click the 'homepage' link at the top of this page if you cannot see the menu frame).

Locating the port documentation pages in the left menu frame

The structure of a demo application

Each demo application creates a set of demo real time tasks and/or co-routines - most of which are not specific to any one demo but common to many. These tasks are created within main(), which in turn is defined within main.c. For example, the main() function for the Luminary Micro LM3S811 GCC demo is contained within FreeRTOS/Demo/CORTEX_LM3S811_GCC/main.c.

Most demos applications also create a 'check' task in one form or another. The 'check' task will execute infrequently (typically every 3 or 5 seconds) but has a high priority so is guaranteed to get processor time. Its primary responsibility is to check that all the other tasks are still operating as expected, and that no errors have been detected. The check task will report the system status either on an LCD (if present) or by toggling an LED.

A typical main() function will have the following structure:

    int main( void )
    {
        /* Setup the microcontroller hardware for the demo. */
        prvSetupHardware();

        /* Create the common demo application tasks, for example: */
        vCreateFlashTasks();
        vCreatePollQTasks();
        vCreateComTestTasks();
        Etc.

        /* Create any tasks defined within main.c itself, or otherwise specific to the
        demo being built. */
        xTaskCreate( vCheckTask, "check", STACK_SIZE, NULL, TASK_PRIORITY, NULL );
        Etc.

        Start the scheduler, this function should not return as it causes the execution
        context to change from main() to one of the created tasks. */
        vTaskStartScheduler();

        /* Should never get here! */
        return 0;
    }

Partest.c - Accessing LEDs

Each demo application includes a file called partest.c (the name is historic and since lost its meaning, but is derived from 'parallel port test'). The file contains the interface functions for setting LEDs, clearing LEDs and toggling LEDs. It is mentioned here for two reasons: First because the function of the file is not obvious from its name, and second because getting the LED outputs working is normally the first step when porting a demo from one hardware platform to another.

Demo application files

The table below lists the files that make up the demo projects along with a brief indication of the RTOS features demonstrated. The following page describes each task and co-routine within the demo project in more detail.

Two implementations are provided for many files listed below. The files contained in the Demo/Common/Minimal directory are for more RAM challenged systems such as the AVR. These files do not contain console IO. The files contained in the Demo/Common/Full directory are predominantly for the x86 demo projects and contain console IO. Other than that the functionality of the two implementations are basically the same. See the Source Code Organization section for more information on the demo project directory structure.

A few of points to note:

• Not all the Demo/Common files are used in every demonstration project. How many files are used depends on processor resources.

• The demo projects often use all the available RAM on the target processor. This means that you cannot add more tasks to the project without first removing some! This is especially true for the projects configured to run on the low end 8bit processors.

• In addition to the standard demo projects, two embedded WEB server projects are included in the download. These provide a more application orientated example.

• Each demo project also contains a file called main.c which contains the main() function. This function is responsible for creating all the demo application tasks and then starting the real time kernel.

• The standard demo project files are provided for the purpose of demonstrating the use of the real time kernel and are not intended to provide an optimized solution. This is particularly true of comtest.c.

File	Features Demonstrated
main.c	Starting/Stopping the kernel Using the trace visualisation utility Allocation of priorities
dynamic.c	Passing parameters into a task Dynamically changing priorities Suspending tasks Suspending the scheduler
BlockQ.c	Inter-task communications Blocking on queue reads Blocking on queue writes Passing parameters into a task Pre-emption Creating tasks
ComTest.c	Serial communications Using queues from an ISR Using semaphores from an ISR Context switching from an ISR Creating tasks
CRFlash.c	Creating co-routines Using the index of a co-routine Blocking on a queue from a co-routine Communication between co-routines
CRHook.c	Creating co-routines Passing data from an ISR to a co-routine Tick hook function Co-routines blocking on queues
Death.c	Dynamic creation of tasks (at run time) Deleting tasks Passing parameters to tasks
Flash.c	Delaying Passing parameters to tasks Creating tasks
Flop.c	Floating point math Time slicing Creating tasks
Integer.c	Time slicing Creating tasks
PollQ.c	Inter-task communications Manually yielding processor time Polling a queue for space to write Polling a queue for space to read Pre-emption Creating tasks
Print.c	Queue usage
Semtest.c	Binary semaphores Mutual exclusion Creating tasks

The demo application does not free all it's resources when it exits, although the kernel does. This has been done purely to minimize lines of code.

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.