Quality RTOS & Embedded Software

KERNEL
WHAT'S NEW
December 2021 Releases:
Extended Maintenance Plan (EMP):
FreeRTOS 202111.00 Release:
FreeRTOS LTS libraries:
Symmetric Multi-Processing:

FreeRTOS Demo Applications

Port documentation pages are grouped by device manufacturer. Expand the list of supported devices, then click the manufacturer of interest to be taken to a list of demo documentation pages.

Introduction

The RTOS source code download includes a pre-configured demonstration project for each RTOS port. The demo targets the evaluation board used for that port's development. At the time of its creation, each preconfigured project built directly as downloaded without any warnings or errors, although subsequent tooling changes may mean that is no longer the case. There is also a separate page that describes how to create a hardware independent demo project.

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. Once you have the demo application running, incrementally remove the demo functions and source files and replace them with your own application code. Note: it is best to set configUSE_TICK_HOOK to 0 in FreeRTOSConfig.h when removing demo functions. Stopping execution of the tick hook may make some demos fail, but will prevent an example tick hook function attempting to interact with a demo that has been removed from the project (which could otherwise result in a crash).

 

Locating a demo application

Each demo project has a documentation page that details the location of the project within the FreeRTOS download, as well as other demo specific important and time saving information (such as how to set up the hardware, and how to build the project).

All the RTOS kernel only demos (demos that do not demonstrate any other libraries) are in subdirectories of the FreeRTOS/Demo directory. The name of the subdirectory identifies the target device and the compiler used to build the project it contains. Please see the FreeRTOS source code organization page for a full explanation of the FreeRTOS directory structure, and the quick start guide for further practical information.

 

The structure of a demo application

Most demo applications use a #define in the project's main.c file to select between building a basic "blinky" style project and building a comprehensive test and demo project.


Simple "blinky" demo configuration

Blinky demo projects are contained in a single source file and implement a subset of the functionality described on the hardware independent demo functions page.

As a minimum the Blinky project will demonstrate how to use a FreeRTOS queue to pass a value between two tasks - toggling an LED or printing output each time the value is received. Many blinky projects also demonstrate a single software timer that uses the same queue.


Comprehensive test/demo configuration

Comprehensive demo projects create all or a subset of the "common demo tasks" - so called because the tasks are common to all comprehensive demos. The number of tasks created depends on the resources available on the target hardware (microcontroller or microprocessor) - the amount of RAM available for task stacks being the limiting factor.

The older common demo tasks only contain demonstrations of how to use the RTOS features. Newer common demo tasks contain integration tests - making their implementation more complex.

Comprehensive demo applications create a 'check' task, or more rarely, a 'check' function called from the tick hook. Each common demo task contains self monitoring code, and it is the job of the check task to periodically (normally every three or five seconds, depending on the demo) query each task to first ensure the task is still executing, and second determine if the task detected any errors. The check task then reports the system status by either toggling an LED or printing out a message. If the check task toggles an LED then the toggle rate will be the task's original period (three or five seconds, depending on the demo) if no errors are present, and increase to toggle many times a second if an error is reported by any task.

Note: The self monitoring code in common demo tasks may report errors purely because the tasks are competing with each other for processing time. That is avoided by tuning the task priorities relative to each other.

The pseudocode below shows the structure of a comprehensive demo.

/* main_full() is called from main() if the #define in main.c is set to create
the comprehensive demo, rather than simple blinky demo. */
int main_full( void )
{
   /* Setup the microcontroller hardware for the demo. */
   prvSetupHardware();

   /* Create the common demo application tasks, for example: */
   vStartInterruptQueueTasks();
   vStartMessageBufferAMPTasks()
   vCreatePollQTasks();
   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 RTOS 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;
}


Notes:

  • The demo projects often use all the available RAM on the target processor, requiring some tasks to be removed before any more can be added.

  • The majority of projects building the standard demo tasks only demonstrate and test the kernel. There are separate projects that demonstrate additional libraries such as the TCP/IP stack, or FreeRTOS core libraries.

  • The standard demo project files are provided for the purpose of demonstrating the use of and testing the RTOS kernel. They are not intended to provide examples of optimised solutions. This is particularly true of comtest.c (which uses an example UART driver), which is generally written with the intent of stressing (and therefore testing) the RTOS kernel implementation rather than providing an example of an optimal integration (normally a UART interface would use a stream buffer rather than a queue).


Legacy information

Partest.c, accessing LEDs

Older demo applications 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 because the function of the file is not obvious from its name.


"Full" vs "Minimal" demo application files

There are two directories that contain source files that implement common demo tasks. Files located in the FreeRTOS/Demo/Common/Full directory assume a hosted environment and are only used by demos that run on top of old DOS systems (which is also why the Partest.c filename is cryptic - it could only use short filenames in 8.3 format). All the other demo projects build the common demo source files from the FreeRTOS/Demo/Common/Minimal directory, none of which assume a hosted environment.


Common demo task functionality

There is old documentation that outlines the behaviour of the original common demo tasks. Recent common demo tasks are designed more for integration testing than purely for demonstration. That means they can be complex, and so are not documented outside of the source files themselves.







 

 

Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.