FreeRTOS Kernel - Developer Guide

1 FreeRTOS KernelDeveloper GuideFreeRTOS Kernel : Developer GuideCopyright 2018 Amazon Web Services, Inc. and/or its affiliates. All rights Kernel Developer GuideAmazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any mannerthat is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks notowned by Amazon are the property of their respective owners, who may or may not be affiliated with, connected to, or sponsored Kernel Developer GuideTable of ContentsAbout the FreeRTOS Kernel .. 1 Value Proposition .. 1A Note About Terminology .. 1 Why Use a Real-time Kernel ? .. 2 FreeRTOS Kernel Features .. 3 Licensing .. 3 Included Source Files and Projects .. 4 FreeRTOS Kernel Distribution .. 5 Understanding the FreeRTOS Kernel Distribution .. 5 Building the FreeRTOS Kernel .. 5 The Official FreeRTOS Kernel Distribution.

2 5 The Top Directories in the FreeRTOS Distribution .. 6 FreeRTOS Source Files Common to All Ports .. 6 FreeRTOS Source Files Specific to a Port .. 7 Header 8 Demo 8 Creating a FreeRTOS Project .. 10 Creating a New Project from Scratch .. 10 Data Types and Coding Style Guide .. 11 Variable Names .. 12 Function Names .. 12 Formatting .. 12 Macro Names .. 12 Rationale for Excessive Type Casting .. 13 Heap Memory Management .. 14 Prerequisites .. 14 Dynamic Memory Allocation and Its Relevance to FreeRTOS .. 14 Options for Dynamic Memory Allocation .. 15 Example Memory Allocation Schemes .. 18 Setting a Start Address for the Array Used by Heap_4 .. 20vPortDefineHeapRegions() API Function .. 20 Heap-Related Utility Functions .. 23xPortGetFreeHeapSize() API Function .. 23xPortGetMinimumEverFreeHeapSize() API Function .. 24 Malloc Failed Hook Functions .. 24 Task Management .. 25 Task Functions .. 25 Top-Level Task States.

3 26 Creating Tasks .. 27xTaskCreate() API Function .. 27 Creating Tasks (Example 1) .. 28 Using the Task Parameter (Example 2) .. 31 Task Priorities .. 33 Time Measurement and the Tick Interrupt .. 33 Experimenting with Priorities (Example 3).. 35 Expanding the Not Running 37 The Blocked State .. 37 The Suspended 37iiiFreeRTOS Kernel Developer GuideThe Ready State .. 37 Completing the State Transition Diagram .. 37 Using the Blocked State to Create a Delay (Example 4) .. 38vTaskDelayUntil() API Function .. 42 Converting the Example Tasks to Use vTaskDelayUntil() (Example 5) .. 43 Combining Blocking and Non-Blocking Tasks (Example 6) .. 44 The Idle Task and the Idle Task Hook .. 46 Idle Task Hook Functions .. 47 Limitations on the Implementation of Idle Task Hook Functions .. 47 Defining an Idle Task Hook Function (Example 7) .. 47 Changing the Priority of a Task .. 49vTaskPrioritySet() API Function .. 49uxTaskPriorityGet() API Function.

4 50 Changing Task Priorities (Example 8) .. 50 Deleting a Task .. 53vTaskDelete() API Function .. 53 Deleting Tasks (Example 9) .. 54 Scheduling 56A Recap of Task States and Events .. 56 Configuring the Scheduling 57 Prioritized Preemptive Scheduling with Time Slicing .. 57 Prioritized Preemptive Scheduling (Without Time Slicing) .. 60 Cooperative Scheduling .. 61 Queue 64 Characteristics of a Queue .. 64 Data 64 Access by Multiple Tasks .. 66 Blocking on Queue Reads .. 66 Blocking on Queue Writes .. 66 Blocking on Multiple 67 Using a 67xQueueCreate() API Function .. 67xQueueSendToBack() and xQueueSendToFront() API Functions .. 68xQueueReceive() API Function .. 69uxQueueMessagesWaiting() API Function .. 71 Blocking When Receiving from a Queue (Example 10) .. 71 Receiving Data from Multiple Sources .. 75 Blocking When Sending to a Queue and Sending Structures on a Queue (Example 11) .. 75 Working with Large or Variable-Sized Data.

5 81 Queuing Pointers .. 81 Using a Queue to Send Different Types and Lengths of Data .. 83 Receiving from Multiple Queues .. 86 Queue 86xQueueCreateSet() API Function .. 86xQueueAddToSet() API Function .. 88xQueueSelectFromSet() API Function .. 88 Using a Queue Set (Example 12).. 89 More Realistic Queue Set Use Cases .. 92 Using a Queue to Create a Mailbox .. 94xQueueOverwrite() API Function .. 95xQueuePeek() API Function .. 96 Software Timer Management .. 98 Software Timer Callback Functions .. 98 Attributes and States of a Software Timer .. 98 Period of a Software Timer .. 98 One-Shot and Auto-Reload Timers .. 99 Software Timer States .. 99ivFreeRTOS Kernel Developer GuideThe Context of a Software Timer .. 100 RTOS Daemon (Timer Service) Task .. 100 Timer Command 101 Daemon Task Scheduling .. 101 Creating and Starting a Software Timer .. 104xTimerCreate() API Function .. 104xTimerStart() API Function .. 105 Creating One-Shot and Auto-Reload Timers (Example 13).

6 106 Timer 109vTimerSetTimerID() API Function .. 109pvTimerGetTimerID() API Function .. 109 Using the Callback Function Parameter and the Software Timer ID (Example 14) .. 110 Changing the Period of a Timer .. 112xTimerChangePeriod() API Function .. 112 Resetting a Software Timer .. 115xTimerReset() API Function .. 116 Resetting a Software Timer (Example 15) .. 117 Interrupt 120 The Interrupt-Safe API .. 120 Advantages of Using a Separate Interrupt-Safe API .. 121 Disadvantages of Using a Separate Interrupt-Safe API .. 121xHigherPriorityTaskWoken Parameter .. 121portYIELD_FROM_ISR() and portEND_SWITCHING_ISR() Macros .. 123 Deferred Interrupt Processing .. 123 Binary Semaphores Used for Synchronization .. 124xSemaphoreCreateBinary() API Function .. 127xSemaphoreTake() API Function .. 127xSemaphoreGiveFromISR() API Function .. 128 Using a Binary Semaphore to Synchronize a Task with an Interrupt (Example 16) .. 129 Improving the Implementation of the Task Used in Example 16.

7 133 Counting Semaphores .. 137xSemaphoreCreateCounting() API Function .. 139 Using a Counting Semaphore to Synchronize a Task with an Interrupt (Example 17) .. 140 Deferring Work to the RTOS Daemon Task .. 141xTimerPendFunctionCallFromISR() API Function .. 142 Centralized Deferred Interrupt Processing (Example 18) .. 143 Using Queues Within an Interrupt Service Routine .. 145xQueueSendToFrontFromISR() and xQueueSendToBackFromISR() API Functions .. 146 Considerations When Using a Queue from an ISR .. 147 Sending and Receiving on a Queue from Within an Interrupt (Example 19) .. 147 Interrupt 151 ARM Cortex-M and ARM GIC Users .. 153 Resource Management .. 155 Mutual Exclusion .. 157 Critical Sections and Suspending the Scheduler .. 157 Basic Critical Sections .. 157 Suspending (or Locking) the Scheduler .. 159vTaskSuspendAll() API Function .. 160xTaskResumeAll() API Function .. 160 Mutexes (and Binary Semaphores).

8 161xSemaphoreCreateMutex() API Function .. 161 Rewriting vPrintString() to Use a Semaphore (Example 20) .. 162 Priority Inversion .. 165 Priority Inheritance .. 165 Deadlock (or Deadly Embrace) .. 166 Recursive Mutexes .. 167 Mutexes and Task Scheduling .. 168vFreeRTOS Kernel Developer GuideGatekeeper Tasks .. 171 Rewriting vPrintString() to Use a Gatekeeper Task (Example 21) .. 172 Event Groups .. 176 Characteristics of an Event Group .. 176 Event Groups, Event Flags, and Event Bits .. 176 More About the EventBits_t Data Type .. 177 Access by Multiple Tasks .. 66A Practical Example of the Use of an Event Group .. 177 Event Management Using Event Groups .. 178xEventGroupCreate() API Function .. 178xEventGroupSetBits() API Function .. 178xEventGroupSetBitsFromISR() API Function .. 179xEventGroupWaitBits() API Function .. 180 Experimenting with Event Groups (Example 22) .. 183 Task Synchronization Using an Event Group.

9 187xEventGroupSync() API Function .. 190 Synchronizing Tasks (Example 23) .. 191 Task Notifications .. 195 Communicating Through Intermediary Objects .. 195 Task Notifications: Direct-to-Task Communication .. 195 Benefits and Limitations of Task Notifications .. 196 Limitations of Task Notifications .. 196 Using Task Notifications .. 197 Task Notification API Options .. 197xTaskNotifyGive() API Function .. 197vTaskNotifyGiveFromISR() API Function .. 198ulTaskNotifyTake() API Function .. 199 Method 1 for Using a Task Notification in Place of a Semaphore (Example 24) .. 200 Method 2 for Using a Task Notification in Place of a Semaphore (Example 25) .. 203xTaskNotify() and xTaskNotifyFromISR() API Functions .. 205xTaskNotifyWait() API Function .. 206 Task Notifications Used in Peripheral Device Drivers: UART Example .. 208 Task Notifications Used in Peripheral Device Drivers: ADC Example .. 214 Task Notifications Used Directly Within an Application.

10 216 Developer Support .. 221configASSERT() .. 221 Example configASSERT() Definitions .. 221 Tracealyzer .. 222 Debug-Related Hook (Callback) Functions .. 225 Viewing Runtime and Task State Information .. 225 Task Runtime Statistics .. 225 The Runtime Statistics 225 Configuring an Application to Collect Runtime Statistics .. 226uxTaskGetSystemState() API Function .. 227vTaskList() Helper Function .. 229vTaskGetRunTimeStats() Helper Function .. 230 Generating and Displaying Runtime Statistics, a Worked Example .. 231 Trace Hook Macros .. 233 Available Trace Hook Macros .. 234 Defining Trace Hook Macros .. 235 FreeRTOS -Aware Debugger Plugins .. 236 Troubleshooting .. 238 Chapter Introduction and Scope .. 238 Interrupt 238 Stack Overflow .. 239uxTaskGetStackHighWaterMark() API Function .. 239 Overview of Runtime Stack Checking .. 239viFreeRTOS Kernel Developer GuideMethod 1 for Runtime Stack 240 Method 2 for Runtime Stack 240 Inappropriate Use of printf() and sprintf().