Mastering the FreeRTOS Real Time Kernel

1 I Mastering the FreeRTOS Real Time Kernel This is the 161204 copy which does not yet cover FreeRTOS , FreeRTOS , or low power tick-less operation. Check regularly for additional documentation and updates to this book. See for information on FreeRTOS See for information on FreeRTOS Applications created using FreeRTOS 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 to provide feedback, comments and corrections. Thank you. ii iii iv Mastering the FreeRTOS Real Time Kernel A Hands-On Tutorial guide Richard Barry v Pre-release 161204 Edition.

2 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. FreeRTOS , 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. vi vii To Caroline, India and Max. viii ix 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 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 Chapter Introduction and Scope .. 10 Scope .. 10 Understanding the FreeRTOS Distribution .. 11 Definition: FreeRTOS Port .. 11 Building FreeRTOS .. 11 .. 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 Demo Applications .. 16 Creating a FreeRTOS Project .. 18 Adapting One of the Supplied Demo Projects .. 18 Creating a New Project from Scratch .. 19 Data Types and Coding Style guide .

4 20 Data Types .. 21 Variable Names .. 22 Function Names .. 22 23 x Macro Names .. 23 Rationale for Excessive Type Casting .. 24 Chapter 2 Heap Memory Management .. 25 Chapter Introduction and Scope .. 26 Prerequisites .. 26 Dynamic Memory Allocation and its Relevance to FreeRTOS .. 26 Options for Dynamic Memory Allocation .. 27 Scope .. 28 Example Memory Allocation Schemes .. 29 From FreeRTOS 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 Heap Related Utility Functions .. 41 The xPortGetFreeHeapSize() API Function .. 41 The xPortGetMinimumEverFreeHeapSize() API Function.

5 41 Malloc Failed Hook Functions .. 42 Chapter 3 Task Management .. 44 Chapter Introduction and Scope .. 45 Scope .. 45 Task Functions .. 46 Top Level Task States .. 47 Creating Tasks .. 48 The xTaskCreate() API Function .. 48 Example 1. Creating tasks .. 51 Example 2. Using the task parameter .. 55 Task Priorities .. 58 Time Measurement and the Tick Interrupt .. 60 Example 3. Experimenting with priorities .. 62 Expanding the Not Running State .. 64 The Blocked State .. 64 The Suspended 65 The Ready State .. 65 Completing the State Transition Diagram .. 65 Example 4. Using the Blocked state to create a delay .. 66 The vTaskDelayUntil() API Function .. 70 Example 5. Converting the example tasks to use vTaskDelayUntil() .. 71 xi Example 6. Combining blocking and non-blocking tasks.

6 72 The Idle Task and the Idle Task Hook .. 75 Idle Task Hook Functions .. 75 Limitations on the Implementation of Idle Task Hook Functions .. 76 Example 7. Defining an idle task hook function .. 76 Changing the Priority of a Task .. 79 The vTaskPrioritySet() API Function .. 79 The uxTaskPriorityGet() API Function .. 79 Example 8. Changing task priorities .. 80 Deleting a Task .. 85 The vTaskDelete() API Function .. 85 Example 9. Deleting tasks .. 86 Thread Local Storage .. 89 Scheduling Algorithms .. 90 A Recap of Task States and Events .. 90 Configuring the Scheduling Algorithm .. 90 Prioritized Pre-emptive Scheduling with Time Slicing .. 91 Prioritized Pre-emptive Scheduling (without Time Slicing) .. 95 Co-operative Scheduling .. 97 Chapter 4 Queue Management .. 101 Chapter Introduction and Scope.

7 102 Scope .. 102 Characteristics of a Queue .. 103 Data Storage .. 103 Access by Multiple Tasks .. 106 Blocking on Queue Reads .. 106 Blocking on Queue Writes .. 106 Blocking on Multiple Queues .. 107 Using a Queue .. 108 The xQueueCreate() API Function .. 108 The xQueueSendToBack() and xQueueSendToFront() API Functions .. 109 The xQueueReceive() API Function .. 111 The uxQueueMessagesWaiting() API Function .. 113 Example 10. Blocking when receiving from a queue .. 114 Receiving Data From Multiple Sources .. 119 Example 11. Blocking when sending to a queue, and sending structures on a queue .. 120 Working with Large or Variable Sized Data .. 126 Queuing Pointers .. 126 Using a Queue to Send Different Types and Lengths of Data .. 128 Receiving From Multiple Queues .. 131 Queue Sets.

8 131 The xQueueCreateSet() API Function .. 132 The xQueueAddToSet() API Function .. 134 xii The xQueueSelectFromSet() API Function .. 135 Example 12. Using a Queue Set .. 137 More Realistic Queue Set Use Cases .. 141 Using a Queue to Create a Mailbox .. 143 The xQueueOverwrite() API Function .. 144 The xQueuePeek() API Function .. 145 Chapter 5 Software Timer Management .. 147 Chapter Introduction and Scope .. 148 Scope .. 148 Software Timer Callback Functions .. 149 Attributes and States of a Software Timer .. 150 Period of a Software Timer .. 150 One-shot and Auto-reload Timers .. 150 Software Timer States .. 151 The Context of a Software Timer .. 153 The RTOS Daemon (Timer Service) Task .. 153 The Timer Command Queue .. 153 Daemon Task Scheduling .. 154 Creating and Starting a Software Timer.

9 158 The xTimerCreate() API Function .. 158 The xTimerStart() API Function .. 159 Example 13. Creating one-shot and auto-reload timers .. 163 The Timer ID .. 166 The vTimerSetTimerID() API Function .. 166 The pvTimerGetTimerID() API Function .. 166 Example 14. Using the callback function parameter and the software timer ID .. 167 Changing the Period of a Timer .. 170 The xTimerChangePeriod() API Function .. 170 Resetting a Software Timer .. 174 The xTimerReset() API Function .. 174 Example 15. Resetting a software timer .. 176 Chapter 6 Interrupt Management .. 181 Chapter Introduction and Scope .. 182 Events .. 182 Scope .. 183 Using the FreeRTOS API from an ISR .. 184 The Interrupt Safe API .. 184 The Benefits of Using a Separate Interrupt Safe API .. 184 The Disadvantages of Using a Separate Interrupt Safe API.

10 185 The xHigherPriorityTaskWoken Parameter .. 185 The portYIELD_FROM_ISR() and portEND_SWITCHING_ISR() Macros .. 187 Deferred Interrupt Processing .. 189 xiii Binary Semaphores Used for Synchronization .. 191 The xSemaphoreCreateBinary() API Function .. 194 The xSemaphoreTake() API Function .. 194 The xSemaphoreGiveFromISR() API Function .. 196 Example 16. Using a binary semaphore to synchronize a task with an interrupt .. 198 Improving the Implementation of the Task Used in Example 16 .. 202 Counting Semaphores .. 208 The xSemaphoreCreateCounting() API Function .. 210 Example 17. Using a counting semaphore to synchronize a task with an interrupt .. 211 Deferring Work to the RTOS Daemon Task .. 213 The xTimerPendFunctionCallFromISR() API Function .. 214 Example 18. Centralized deferred interrupt processing.