Embedded Systems - Shape The World

FreeRTOS minimal Project

Keywords: Embedded systems, ARM, FreeRTOS,STM32F4

Code Link: Tutorial Source Code Github – Keil

In this tutorial we will talk about the minimum configuration an application requires to use FreeRTOS kernel. Before we jump into application configuration, lets briefly discuss FreeRTOS directory structure. FreeRTOS kernel is distributed under GPL license and can be downloaded from FreeRTOS official website, link given bellow.

FreeRTOS directory structure is very simple and straight forward. The FreeRTOS official website provides best documentation explaining FreeRTOS directory structure. Here we will just summarize it so that we can jump to application configuration directly.

On top level, the FreeRTOS source contains the following two directories apart from few links etc.
1. FreeRTOS
2. FreeRTOS-Plus

 +-FreeRTOS Source
        |
        +-FreeRTOS
        |
        +-FreeRTOS-Plus

The FreeRTOS directory contains actual FreeRTOS kernel code some demo projects and license information.

 +-FreeRTOS
        |
        +-Demo
        |
        +-License
        |
        +-Source
        |
        +.etc.

The Source directory actually contains FreeRTOS real time kernel and various processors ports as shown bellow.

 +-FreeRTOS
        |
        +-Source
            |
            +-include	--------------------> Contains FreeRTOS header files
            |
            +-portable	--------------------> FreeRTOS ports for various compilers
            |
            +-croutine.c -------------------> FreeRTOS co-routine functionality - which
            |                                 is normally only used on very memory limited 
            |                                 Systems
            |
            +-event_groups.c ---------------> FreeRTOS feature that allow events to tasks
            |                                 Communication. It Allows blocking and unblocking
            |                                 of tasks waiting for one or more events combination.
            |
            +-timers.c ---------------------> FreeRTOS Software Timer
            |
            +-list.c  ---------------------->|
            |                                |
            +-queue.c ---------------------->|------> Actual FreeRTOS Real Time Kernel
            |                                |
            +-tasks.c ---------------------->|

The core RTOS code is contained in three files, i.e. tasks.c, queue.c and list.c . Out of these three files, two files i.e. list.c and tasks.c are compulsory for any application that uses FreeRTOS real timer kernel. The third file i.e. queue.c is used when your application requires more advance features like queues, semaphores, mutex etc.

The include directory contains all the header files included by FreeRTOS source files. The portable directory contains various supported processor ports (underlying hardware dependent code) files for various compilers including Keil, IAR, GCC etc. This is FreeRTOS portable layer.

The FreeRTOS-Plus directory contains third party software packages for FreeRTOS for example Network protocols, File systems etc. This directory also contain some related demo projects. We won’t go into any details of these files.

 +-FreeRTOS-Plus
        |
        +-Demo
        |
        +-Source

Application Configuration

In order to inlcude FreeRTOS real time kernel into your application, the following files must be included into your application project.
1. Hardware/Compiler dependent port.c file and related header files.
2. FreeRTOS Kernel source files. At least two tasks.c and lists.c + related header files.
3. Memory Management policy file i.e. heap_1.c, heap_2.c … heap_5.c.
4. FreeRTOSConfig.h file.

We will explain the above using Keil MDk v5 Software with STM32F4-Discovery kit (ARM Cortex-M4 based MCU). Before going into implementation, lets introduce FreeRTOSConfig.h file.

FreeRTOSConfig.h:

FreeRTOS real time Kernel provides tremendous number of functionalities. Some times not every functionality is required by application. Thus the code that incorporate those unnecessary functionalities may result into larger footprint which indeed is a problem in resource limited hardware. Embedded systems have limited RAM and ROM memory. The FreeRTOSConfig.h file can be used to fine tune FreeRTOS Kernel as per application requirements. The FreeRTOSConfig.h file contains simple C MACROS to enable/disable certain functionality of FreeRTOS real time Kernel. The following code snippet shows a sample FreeRTOSConfig.h file.

#define configUSE_PREEMPTION            1
#define configUSE_IDLE_HOOK             0
#define configUSE_TICK_HOOK             1
#define configCPU_CLOCK_HZ              ( SystemCoreClock )
#define configTICK_RATE_HZ              ( ( TickType_t ) 1000 )
#define configMAX_PRIORITIES            ( 5 )
#define configMINIMAL_STACK_SIZE        ( ( unsigned short ) 60 )
#define configTOTAL_HEAP_SIZE           ( ( size_t ) ( 6500 ) )
#define configMAX_TASK_NAME_LEN         ( 5 )
#define configUSE_TRACE_FACILITY        1
#define configUSE_16_BIT_TICKS          0
#define configIDLE_SHOULD_YIELD         1
#define configUSE_MUTEXES               1
#define configQUEUE_REGISTRY_SIZE       8
#define configCHECK_FOR_STACK_OVERFLOW  2
#define configUSE_RECURSIVE_MUTEXES     1
#define configUSE_MALLOC_FAILED_HOOK    1
#define configUSE_APPLICATION_TASK_TAG  0
#define configUSE_COUNTING_SEMAPHORES   1
#define configGENERATE_RUN_TIME_STATS   0

/* Co-routine definitions. */
#define configUSE_CO_ROUTINES           0
#define configMAX_CO_ROUTINE_PRIORITIES ( 2 )
.
.
.

Note: The FreeRTOSConfig.h file is not provided as part of FreeRTOS source code. It is left to user implementation. The best option is to copy FreeRTOSConfig.h file from one of the related demo project and tune it in accordance to application requirements.

Steps:

1. Create a blank project for your target hardware using your favourite compiler. In my case, I am using STM32F407VG (STM32F4-Discovery board) as my target hardware and Keil MDK5 compiler. This is step is pretty much straight forward.

2. Next step is to include FreeRTOS Kernel files. From FreeRTOS Source directory, add the following two files (for minimal project) to your project.
1. tasks.c
2. list.c

3. As FreeRTOS files needs respective header files so all you have to do is to either:
1. Add manually each header file like FreeRTOS.h, tasks.h, list.h. [Less desirable approach]
2. Add header files directory path to compiler include search path. [Highly desirable approach]

In Keil, the search path can be added via Options for Target >> C/C++ >> Include Paths – Figure-1.

Figure-1: Including Search paths in Keil

Click the little button on right side of “include path” edit box (Figure-1) and enter (copy-past from your computer) the following two paths to the newly open box.

  1. include directory inside FreeRTOS->Source->include (This directory contains task.h, queue.h, list.h etc.) see here labeled “Contains FreeRTOS header files”.
  2. Path to partable folder for your compiler containing port.c and portmacro.h – see the following step-4.

4. Next step is to add hardware/target and Compiler dependent files to project. In our case as we are using STM32F407VG microcontroller which is ARM Cortex-M4 based processor. So from FreeRTOS Source portable directory go to RVDS (FreeRTOS ports for Keil ARM Compiler), and from ARM_CM4F directory add port.c file to the project. Also add this path to include search path as explained in step-3.

5. Next add one of the memory management files from FreeRTOS >> portable >> MemMang >> heap_x.c. Where x = 1,2,3,4,5. The selection depends on nature of application but for most cases, heap_2.c will fit. For more details visit the official webpage here.

6. The final step is to turn ON/OFF various FreeRTOS functionalities and fine tune it via FreeRTOSConfig.h file. Instead of creating your own from scratch, use one from the relevant demo project. For this minimal project we will copy this file from STM32 demo project CORTEX_M0_STM32F0518_IAR. Copy FreeRTOSConfig.h into project directory and also make sure you add its directory path to include paths as shown in step-3.

7. Thats pretty much everything you need to integrate FreeRTOS kernel into your application. Now start Building your application.

Note: For learning purpose you can just use one of the demo projects and start playing around with various FreeRTOS functionalities.

References:

STM32F4-Discovery BoardDownload
STM32F407xx DatasheetDownload

[1] – Reference manual-RM0090

[2] – FreeRTOS official Website

Filed Under: FreeRTOS
Tags: , ,

316 thoughts on “FreeRTOS minimal Project”

Leave a Reply

Your email address will not be published. Required fields are marked *

Welcome to EcoderLenz

Embedded systems are where the software meets the physical world. As we put tiny computers into all sorts of systems (door locks, airplanes, pacemakers), how we implement the software is truly, terrifyingly important. Writing software for these things is more difficult than computer software because the systems have so few resources. Designing an efficient software on top of such limited resources is indeed a challanging task.
The purpose of these tutorial is to accelerate your learning process and give you solid understanding of embedded system basics.
Sounds Interesting? Share it

Copyright © 2020