Mastering the FreeRTOS™ Real Time Kernel This is the 161204 copy which does not yet cover FreeRTOS V9.0.0, FreeRTOS V10.0.0, or low power tick-less operation. Check http://www.FreeRTOS.org regularly for additional documentation and updates to this book. See http://www.FreeRTOS.org/FreeRTOS-V9.html for information on FreeRTOS V9.x.x. See https://www.freertos.org/FreeRTOS-V10.html for information on FreeRTOS V10.x.x. Applications created using FreeRTOS V9.x.x onwards can allocate all kernel objects statically at compile time, removing the need to include a heap memory manager. This text is being provided for free. In return we ask that you use the business contact email link on http://www.FreeRTOS.org/contact to provide feedback, comments and corrections. Thank you. i ii iii Mastering the FreeRTOS™ Real Time Kernel A Hands-On Tutorial Guide Richard Barry iv Pre-release 161204 Edition. All text, source code, and diagrams are the exclusive property of Real Time Engineers Ltd. unless otherwise noted inline. © Real Time Engineers Ltd. 2016. All rights reserved. http://www.FreeRTOS.org http://www.FreeRTOS.org/plus http://www.FreeRTOS.org/labs FreeRTOS™, FreeRTOS.org™ and the FreeRTOS logo are trademarks of Real Time Engineers Ltd. OPENRTOS® and SAFERTOS® are trademarks of WITTENSTEIN Aerospace and Simulation Ltd. All other brands or product names are the property of their respective holders. v vi To Caroline, India and Max. vii viii Contents Contents .................................................................................................................................. ix List of Figures ......................................................................................................................... xvi List of Code Listings ............................................................................................................... xix List of Tables ........................................................................................................................ xxiii List of Notation ...................................................................................................................... xxvi Preface .................................................................................................................................. 1 Multitasking in Small Embedded Systems ............................................................................ 2 About FreeRTOS ............................................................................................................. 2 Value Proposition ............................................................................................................. 3 A Note About Terminology ............................................................................................... 3 Why Use a Real-time Kernel? .......................................................................................... 3 FreeRTOS Features ........................................................................................................ 5 Licensing, and The FreeRTOS, OpenRTOS, and SafeRTOS Family ............................... 6 Included Source Files and Projects ...................................................................................... 7 Obtaining the Examples that Accompany this Book ......................................................... 7 Chapter 1 The FreeRTOS Distribution ............................................................................... 9 1.1 Chapter Introduction and Scope ................................................................................ 10 Scope ............................................................................................................................ 10 1.2 Understanding the FreeRTOS Distribution ................................................................ 11 Definition: FreeRTOS Port ............................................................................................. 11 Building FreeRTOS ........................................................................................................ 11 FreeRTOSConfig.h ........................................................................................................ 11 The Official FreeRTOS Distribution ................................................................................ 12 The Top Directories in the FreeRTOS Distribution ......................................................... 12 FreeRTOS Source Files Common to All Ports ............................................................... 12 FreeRTOS Source Files Specific to a Port ..................................................................... 14 Header Files .................................................................................................................. 15 1.3 Demo Applications .................................................................................................... 16 1.4 Creating a FreeRTOS Project ................................................................................... 18 Adapting One of the Supplied Demo Projects ................................................................ 18 Creating a New Project from Scratch ............................................................................. 19 1.5 Data Types and Coding Style Guide ......................................................................... 20 Data Types .................................................................................................................... 21 Variable Names ............................................................................................................. 22 Function Names ............................................................................................................. 22 Formatting...................................................................................................................... 23 ix Macro Names ................................................................................................................. 23 Rationale for Excessive Type Casting ............................................................................ 24 Chapter 2 Heap Memory Management ............................................................................. 25 2.1 Chapter Introduction and Scope ................................................................................ 26 Prerequisites .................................................................................................................. 26 Dynamic Memory Allocation and its Relevance to FreeRTOS ........................................ 26 Options for Dynamic Memory Allocation ......................................................................... 27 Scope ............................................................................................................................. 28 2.2 Example Memory Allocation Schemes ...................................................................... 29 From FreeRTOS V9.0.0 FreeRTOS applications can be completely statically allocated, removing the need to include a heap memory manager ................................. 29 Heap_1 .......................................................................................................................... 29 Heap_2 .......................................................................................................................... 30 Heap_3 .......................................................................................................................... 32 Heap_4 .......................................................................................................................... 32 Setting a Start Address for the Array Used By Heap_4 .................................................. 34 Heap_5 .......................................................................................................................... 35 The vPortDefineHeapRegions() API Function ................................................................ 36 2.3 Heap Related Utility Functions .................................................................................. 41 The xPortGetFreeHeapSize() API Function .................................................................... 41 The xPortGetMinimumEverFreeHeapSize() API Function .............................................. 41 Malloc Failed Hook Functions ........................................................................................ 42 Chapter 3 Task Management ........................................................................................... 44 3.1 Chapter Introduction and Scope ................................................................................ 45 Scope ............................................................................................................................. 45 3.2 Task Functions .......................................................................................................... 46 3.3 Top Level Task States ............................................................................................... 47 3.4 Creating Tasks .......................................................................................................... 48 The xTaskCreate() API Function .................................................................................... 48 Example 1. Creating tasks ............................................................................................. 51 Example 2. Using the task parameter ............................................................................