FreeRTOS 官方指导 英文（Mastering_the_FreeRTOS_Real_Time_Kernel-A_Hands-On_Tutorial_Guide.pdf）

【实例截图】

【核心代码】

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 ......................................................................... 21
Data Types .................................................................................................................... 21
Variable Names ............................................................................................................. 22
Function Names............................................................................................................. 22
Formatting...................................................................................................................... 23
x
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.............................................................................55
3.5 Task Priorities ...........................................................................................................58
3.6 Time Measurement and the Tick Interrupt .................................................................60
Example 3. Experimenting with priorities........................................................................62
3.7 Expanding the ‘Not Running’ State............................................................................64
The Blocked State..........................................................................................................64
The Suspended State.....................................................................................................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................................................ 72
3.8 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
3.9 Changing the Priority of a Task ................................................................................. 79
The vTaskPrioritySet() API Function .............................................................................. 79
The uxTaskPriorityGet() API Function............................................................................ 79
Example 8. Changing task priorities............................................................................... 80
3.10 Deleting a Task ......................................................................................................... 85
The vTaskDelete() API Function .................................................................................... 85
Example 9. Deleting tasks.............................................................................................. 86
3.11 Thread Local Storage................................................................................................ 89
3.12 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
4.1 Chapter Introduction and Scope.............................................................................. 102
Scope .......................................................................................................................... 102
4.2 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
4.3 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
4.4 Receiving Data From Multiple Sources ................................................................... 119
Example 11. Blocking when sending to a queue, and sending structures on a queue.. 120
4.5 Working with Large or Variable Sized Data ............................................................. 126
Queuing Pointers ......................................................................................................... 126
Using a Queue to Send Different Types and Lengths of Data ...................................... 128
4.6 Receiving From Multiple Queues ............................................................................ 131
Queue Sets.................................................................................................................. 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
4.7 Using a Queue to Create a Mailbox.........................................................................143
The xQueueOverwrite() API Function...........................................................................144
The xQueuePeek() API Function..................................................................................145
Chapter 5 Software Timer Management.........................................................................147
5.1 Chapter Introduction and Scope..............................................................................148
Scope...........................................................................................................................148
5.2 Software Timer Callback Functions .........................................................................149
5.3 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
5.4 The Context of a Software Timer.............................................................................153
The RTOS Daemon (Timer Service) Task....................................................................153
The Timer Command Queue........................................................................................153
Daemon Task Scheduling ............................................................................................154
5.5 Creating and Starting a Software Timer...................................................................158
The xTimerCreate() API Function.................................................................................158
The xTimerStart() API Function....................................................................................159
Example 13. Creating one-shot and auto-reload timers................................................163
5.6 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
5.7 Changing the Period of a Timer...............................................................................170
The xTimerChangePeriod() API Function.....................................................................170
5.8 Resetting a Software Timer.....................................................................................174
The xTimerReset() API Function ..................................................................................174
Example 15. Resetting a software timer .......................................................................176
Chapter 6 Interrupt Management....................................................................................181
6.1 Chapter Introduction and Scope..............................................................................182
Events..........................................................................................................................182
Scope...........................................................................................................................183
6.2 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 .........................................185
The xHigherPriorityTaskWoken Parameter ..................................................................185
The portYIELD_FROM_ISR() and portEND_SWITCHING_ISR() Macros.....................187
6.3 Deferred Interrupt Processing..................................................................................189
xiii
6.4 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
6.5 Counting Semaphores ............................................................................................ 208
The xSemaphoreCreateCounting() API Function ......................................................... 210
Example 17. Using a counting semaphore to synchronize a task with an interrupt....... 211
6.6 Deferring Work to the RTOS Daemon Task ............................................................ 213
The xTimerPendFunctionCallFromISR() API Function ................................................. 214
Example 18. Centralized deferred interrupt processing................................................ 216
6.7 Using Queues within an Interrupt Service Routine .................................................. 220
The xQueueSendToFrontFromISR() and xQueueSendToBackFromISR() API
Functions ..................................................................................................................... 220
Considerations When Using a Queue From an ISR ..................................................... 222
Example 19. Sending and receiving on a queue from within an interrupt ..................... 222
6.8 Interrupt Nesting ..................................................................................................... 228
A Note to ARM Cortex-M and ARM GIC Users ............................................................ 230
Chapter 7 Resource Management ................................................................................. 233
7.1 Chapter Introduction and Scope.............................................................................. 234
Mutual Exclusion.......................................................................................................... 236
Scope .......................................................................................................................... 237
7.2 Critical Sections and Suspending the Scheduler..................................................... 238
Basic Critical Sections ................................................................................................. 238
Suspending (or Locking) the Scheduler ....................................................................... 240
The vTaskSuspendAll() API Function........................................................................... 241
The xTaskResumeAll() API Function ........................................................................... 241
7.3 Mutexes (and Binary Semaphores)......................................................................... 243
The xSemaphoreCreateMutex() API Function.............................................................. 245
Example 20. Rewriting vPrintString() to use a semaphore ........................................... 245
Priority Inversion .......................................................................................................... 249
Priority Inheritance....................................................................................................... 250
Deadlock (or Deadly Embrace) .................................................................................... 251
Recursive Mutexes ...................................................................................................... 252
Mutexes and Task Scheduling ..................................................................................... 255
7.4 Gatekeeper Tasks................................................................................................... 259
Example 21. Re-writing vPrintString() to use a gatekeeper task................................... 259
Chapter 8 Event Groups................................................................................................. 265
8.1 Chapter Introduction and Scope.............................................................................. 266
Scope .......................................................................................................................... 266
8.2 Characteristics of an Event Group........................................................................... 268
xiv
Event Groups, Event Flags and Event Bits...................................................................268
More About the EventBits_t Data Type ........................................................................269
Access by Multiple Tasks .............................................................................................269
A Practical Example of Using an Event Group .............................................................269
8.3 Event Management Using Event Groups.................................................................271
The xEventGroupCreate() API Function.......................................................................271
The xEventGroupSetBits() API Function ......................................................................271
The xEventGroupSetBitsFromISR() API Function ........................................................272
The xEventGroupWaitBits() API Function.....................................................................275
Example 22. Experimenting with event groups.............................................................279
8.4 Task Synchronization Using an Event Group ..........................................................285
The xEventGroupSync() API Function..........................................................................287
Example 23. Synchronizing tasks.................................................................................289
Chapter 9 Task Notifications...........................................................................................293
9.1 Chapter Introduction and Scope..............................................................................294
Communicating Through Intermediary Objects.............................................................294
Task Notifications—Direct to Task Communication ......................................................294
Scope...........................................................................................................................295
9.2 Task Notifications; Benefits and Limitations.............................................................296
Performance Benefits of Task Notifications ..................................................................296
RAM Footprint Benefits of Task Notifications ...............................................................296
Limitations of Task Notifications ...................................................................................296
9.3 Using Task Notifications ..........................................................................................298
Task Notification API Options.......................................................................................298
The xTaskNotifyGive() API Function ............................................................................298
The vTaskNotifyGiveFromISR() API Function ..............................................................299
The ulTaskNotifyTake() API Function...........................................................................300
Example 24. Using a task notification in place of a semaphore, method 1....................302
Example 25. Using a task notification in place of a semaphore, method 2....................305
The xTaskNotify() and xTaskNotifyFromISR() API Functions .......................................307
The xTaskNotifyWait() API Function.............................................................................310
Task Notifications Used in Peripheral Device Drivers: UART Example........................313
Task Notifications Used in Peripheral Device Drivers: ADC Example...........................320
Task Notifications Used Directly Within an Application .................................................322
Chapter 10 Low Power Support....................................................................................327
Chapter 11 Developer Support .....................................................................................328
11.1 Chapter Introduction and Scope..............................................................................329
11.2 configASSERT()......................................................................................................330
Example configASSERT() definitions ...........................................................................330
11.3 FreeRTOS Trace....................................................................................................332
11.4 Debug Related Hook (Callback) Functions..............................................................336
xv
Malloc failed hook ........................................................................................................ 336
11.5 Viewing Run-time and Task State Information......................................................... 337
Task Run-Time Statistics ............................................................................................. 337
The Run-Time Statistics Clock ..................................................................................... 337
Configuring an Application to Collect Run-Time Statistics............................................ 338
The uxTaskGetSystemState() API Function................................................................. 339
The vTaskList() Helper Function .................................................................................. 342
The vTaskGetRunTimeStats() Helper Function............................................................ 344
Generating and Displaying Run-Time Statistics, a Worked Example............................ 345
11.6 Trace Hook Macros................................................................................................. 348
Available Trace Hook Macros ...................................................................................... 348
Defining Trace Hook Macros........................................................................................ 352
FreeRTOS Aware Debugger Plug-ins .......................................................................... 353
Chapter 12 Trouble Shooting ....................................................................................... 355
12.1 Chapter Introduction and Scope.............................................................................. 356
12.2 Interrupt Priorities.................................................................................................... 357
12.3 Stack Overflow........................................................................................................ 359
The uxTaskGetStackHighWaterMark() API Function ................................................... 359
Run Time Stack Checking—Overview ......................................................................... 360
Run Time Stack Checking—Method 1 ......................................................................... 360
Run Time Stack Checking—Method 2 ......................................................................... 361
12.4 Inappropriate Use of printf() and sprintf()................................................................. 362
Printf-stdarg.c .............................................................................................................. 362
12.5 Other Common Sources of Error............................................................................. 364
Symptom: Adding a simple task to a demo causes the demo to crash ......................... 364
Symptom: Using an API function within an interrupt causes the application to crash ... 364
Symptom: Sometimes the application crashes within an interrupt service routine ........ 364
Symptom: The scheduler crashes when attempting to start the first task ..................... 365
Symptom: Interrupts are unexpectedly left disabled, or critical sections do not nest
correctly ....................................................................................................................... 365
Symptom: The application crashes even before the scheduler is started ..................... 365
Symptom: Calling API functions while the scheduler is suspended, or from inside a
critical section, causes the application to crash............................................................ 366
INDEX .................................................................................................................................. 368
xvi
List of Figures
Figure 1. Top level directories within the FreeRTOS distribution ............................................12
Figure 2. Core FreeRTOS source files within the FreeRTOS directory tree............................13
Figure 3. Port specific source files within the FreeRTOS directory tree ..................................14
Figure 4. The demo directory hierarchy..................................................................................17
Figure 5. RAM being allocated from the heap_1 array each time a task is created ................30
Figure 6. RAM being allocated and freed from the heap_2 array as tasks are created
and deleted...........................................................................................................31
Figure 7. RAM being allocated and freed from the heap_4 array ...........................................33
Figure 8 Memory Map.............................................................................................................37
Figure 9. Top level task states and transitions........................................................................47
Figure 10. The output produced when Example 1 is executed ...............................................53
Figure 11. The actual execution pattern of the two Example 1 tasks ......................................54
Figure 12. The execution sequence expanded to show the tick interrupt executing ...............61
Figure 13. Running both tasks at different priorities ...............................................................63
Figure 14. The execution pattern when one task has a higher priority than the other .............63
Figure 15. Full task state machine..........................................................................................66
Figure 16. The output produced when Example 4 is executed ...............................................68
Figure 17. The execution sequence when the tasks use vTaskDelay() in place of the
NULL loop.............................................................................................................69
Figure 18. Bold lines indicate the state transitions performed by the tasks in Example 4 ......70
Figure 19. The output produced when Example 6 is executed ...............................................74
Figure 20. The execution pattern of Example 6......................................................................74
Figure 21. The output produced when Example 7 is executed ...............................................78
Figure 22. The sequence of task execution when running Example 8 ....................................83
Figure 23. The output produced when Example 8 is executed ...............................................84
Figure 24. The output produced when Example 9 is executed ...............................................87
Figure 25. The execution sequence for example 9.................................................................88
Figure 26. Execution pattern highlighting task prioritization and pre-emption in a
hypothetical application in which each task has been assigned a unique
priority...................................................................................................................92
Figure 27 Execution pattern highlighting task prioritization and time slicing in a
hypothetical application in which two tasks run at the same priority ......................94
Figure 28 The execution pattern for the same scenario as shown in Figure 27, but this
time with configIDLE_SHOULD_YIELD set to 1....................................................95
Figure 29 Execution pattern that demonstrates how tasks of equal priority can receive
hugely different amounts of processing time when time slicing is not used ...........96
Figure 30 Execution pattern demonstrating the behavior of the co-operative scheduler..........98
Figure 31. An example sequence of writes to, and reads from a queue ...............................104
Figure 32. The output produced when Example 10 is executed ...........................................118
Figure 33. The sequence of execution produced by Example 10 .........................................118
Figure 34. An example scenario where structures are sent on a queue ...............................119
Figure 35 The output produced by Example 11.....................................................................123
xvii
Figure 36. The sequence of execution produced by Example 11 ......................................... 124
Figure 37 The output produced when Example 12 is executed............................................. 141
Figure 38 The difference in behavior between one-shot and auto-reload software timers..... 150
Figure 39 Auto-reload software timer states and transitions.................................................. 152
Figure 40 One-shot software timer states and transitions ..................................................... 152
Figure 41 The timer command queue being used by a software timer API function to
communicate with the RTOS daemon task ......................................................... 154
Figure 42 The execution pattern when the priority of a task calling xTimerStart() is above
the priority of the daemon task............................................................................ 154
Figure 43 The execution pattern when the priority of a task calling xTimerStart() is below
the priority of the daemon task............................................................................ 156
Figure 44 The output produced when Example 13 is executed............................................. 165
Figure 45 The output produced when Example 14 is executed............................................. 169
Figure 46 Starting and resetting a software timer that has a period of 6 ticks........................ 174
Figure 47 The output produced when Example 15 is executed............................................. 179
Figure 48 Completing interrupt processing in a high priority task .......................................... 190
Figure 49. Using a binary semaphore to implement deferred interrupt processing ............... 191
Figure 50. Using a binary semaphore to synchronize a task with an interrupt ...................... 193
Figure 51. The output produced when Example 16 is executed........................................... 201
Figure 52. The sequence of execution when Example 16 is executed ................................. 202
Figure 53. The scenario when one interrupt occurs before the task has finished
processing the first event.................................................................................... 204
Figure 54 The scenario when two interrupts occur before the task has finished
processing the first event.................................................................................... 205
Figure 55. Using a counting semaphore to ‘count’ events .................................................... 209
Figure 56. The output produced when Example 17 is executed........................................... 212
Figure 57. The output produced when Example 18 is executed........................................... 218
Figure 58 The sequence of execution when Example 18 is executed ................................... 219
Figure 59. The output produced when Example 19 is executed........................................... 226
Figure 60. The sequence of execution produced by Example 19 ......................................... 227
Figure 61. Constants affecting interrupt nesting behavior .................................................... 230
Figure 62 How a priority of binary 101 is stored by a Cortex-M microcontroller that
implements four priority bits................................................................................ 231
Figure 63. Mutual exclusion implemented using a mutex ..................................................... 244
Figure 64. The output produced when Example 20 is executed........................................... 248
Figure 65. A possible sequence of execution for Example 20 .............................................. 249
Figure 66. A worst case priority inversion scenario .............................................................. 250
Figure 67. Priority inheritance minimizing the effect of priority inversion .............................. 251
Figure 68 A possible sequence of execution when tasks that have the same priority use
the same mutex.................................................................................................. 255
Figure 69 A sequence of execution that could occur if two instances of the task shown by
Listing 125 are created at the same priority ........................................................ 257
Figure 70. The output produced when Example 21 is executed........................................... 264
Figure 71 Event flag to bit number mapping in a variable of type EventBits_t ....................... 268
xviii
Figure 72 An event group in which only bits 1, 4 and 7 are set, and all the other event
flags are clear, making the event group’s value 0x92..........................................268
Figure 73 The output produced when Example 22 is executed with xWaitForAllBits set to
pdFALSE ............................................................................................................283
Figure 74 The output produced when Example 22 is executed with xWaitForAllBits set to
pdTRUE..............................................................................................................284
Figure 75 The output produced when Example 23 is executed .............................................292
Figure 76 A communication object being used to send an event from one task to another....294
Figure 77 A task notification used to send an event directly from one task to another...........295
Figure 78. The output produced when Example 16 is executed ...........................................304
Figure 79. The sequence of execution when Example 24 is executed .................................305
Figure 80. The output produced when Example 25 is executed ...........................................307
Figure 81 The communication paths from the application tasks to the cloud server, and
back again ..........................................................................................................323
Figure 82 FreeRTOS Trace includes more than 20 interconnected views ............................332
Figure 83 FreeRTOS Trace main trace view - one of more than 20 interconnected trace
views ..................................................................................................................333
Figure 84 FreeRTOS Trace CPU load view - one of more than 20 interconnected trace
views ..................................................................................................................334
Figure 85 FreeRTOS Trace response time view - one of more than 20 interconnected
trace views..........................................................................................................334
Figure 86 FreeRTOS Trace user event plot view - one of more than 20 interconnected
trace views..........................................................................................................335
Figure 87 FreeRTOS Trace kernel object history view - one of more than 20
interconnected trace views..................................................................................335
Figure 88 Example output generated by vTaskList() .............................................................344
Figure 89 Example output generated by vTaskGetRunTimeStats().......................................345
Figure 90 FreeRTOS ThreadSpy Eclipse plug-in from Code Confidence Ltd. .......................353
xix
List of Code Listings
Listing 1. The template for a new main() function................................................................... 18
Listing 2. Using GCC syntax to declare the array that will be used by heap_4, and place
the array in a memory section named .my_heap .................................................. 35
Listing 3. Using IAR syntax to declare the array that will be used by heap_4, and place
the array at the absolute address 0x20000000 ..................................................... 35
Listing 4. The vPortDefineHeapRegions() API function prototype .......................................... 36
Listing 5. The HeapRegion_t structure................................................................................... 36
Listing 6. An array of HeapRegion_t structures that together describe the 3 regions of
RAM in their entirety ............................................................................................. 38
Listing 7. An array of HeapRegion_t structures that describe all of RAM2, all of RAM3,
but only part of RAM1........................................................................................... 39
Listing 8. The xPortGetFreeHeapSize() API function prototype.............................................. 41
Listing 9. The xPortGetMinimumEverFreeHeapSize() API function prototype ........................ 41
Listing 10. The malloc failed hook function name and prototype. ........................................... 42
Listing 11. The task function prototype................................................................................... 46
Listing 12. The structure of a typical task function.................................................................. 46
Listing 13. The xTaskCreate() API function prototype ............................................................ 48
Listing 14. Implementation of the first task used in Example 1 ............................................... 52
Listing 15. Implementation of the second task used in Example 1 ......................................... 52
Listing 16. Starting the Example 1 tasks ................................................................................ 53
Listing 17. Creating a task from within another task after the scheduler has started .............. 55
Listing 18. The single task function used to create two tasks in Example 2............................ 56
Listing 19. The main() function for Example 2. ....................................................................... 57
Listing 20. Using the pdMS_TO_TICKS() macro to convert 200 milliseconds into an
equivalent time in tick periods............................................................................... 61
Listing 21. Creating two tasks at different priorities ................................................................ 62
Listing 22. The vTaskDelay() API function prototype.............................................................. 67
Listing 23. The source code for the example task after the null loop delay has been
replaced by a call to vTaskDelay()........................................................................ 68
Listing 24. vTaskDelayUntil() API function prototype.............................................................. 71
Listing 25. The implementation of the example task using vTaskDelayUntil() ........................ 72
Listing 26. The continuous processing task used in Example 6.............................................. 73
Listing 27. The periodic task used in Example 6 .................................................................... 73
Listing 28. The idle task hook function name and prototype................................................... 76
Listing 29. A very simple Idle hook function ........................................................................... 77
Listing 30. The source code for the example task now prints out the ulIdleCycleCount
value..................................................................................................................... 77
Listing 31. The vTaskPrioritySet() API function prototype ...................................................... 79
Listing 32. The uxTaskPriorityGet() API function prototype .................................................... 79
Listing 33. The implementation of Task 1 in Example 8 ......................................................... 81
Listing 34. The implementation of Task 2 in Example 8 ......................................................... 82
Listing 35. The implementation of main() for Example 8......................................................... 83
xx
Listing 36. The vTaskDelete() API function prototype.............................................................85
Listing 37. The implementation of main() for Example 9.........................................................86
Listing 38. The implementation of Task 1 for Example 9 ........................................................87
Listing 39. The implementation of Task 2 for Example 9 ........................................................87
Listing 40. The xQueueCreate() API function prototype .......................................................108
Listing 41. The xQueueSendToFront() API function prototype .............................................109
Listing 42. The xQueueSendToBack() API function prototype..............................................109
Listing 43. The xQueueReceive() API function prototype .....................................................112
Listing 44. The uxQueueMessagesWaiting() API function prototype ....................................113
Listing 45. Implementation of the sending task used in Example 10.....................................115
Listing 46. Implementation of the receiver task for Example 10............................................116
Listing 47. The implementation of main() in Example 10 ......................................................117
Listing 48. The definition of the structure that is to be passed on a queue, plus the
declaration of two variables for use by the example............................................120
Listing 49. The implementation of the sending task for Example 11 .....................................121
Listing 50. The definition of the receiving task for Example 11 .............................................122
Listing 51. The implementation of main() for Example 11.....................................................123
Listing 52. Creating a queue that holds pointers...................................................................127
Listing 53. Using a queue to send a pointer to a buffer.........................................................127
Listing 54. Using a queue to receive a pointer to a buffer.....................................................127
Listing 55. The structure used to send events to the TCP/IP stack task in
FreeRTOS TCP.................................................................................................128
Listing 56. Pseudo code showing how an IPStackEvent_t structure is used to send data
received from the network to the TCP/IP task .....................................................129
Listing 57. Pseudo code showing how an IPStackEvent_t structure is used to send the
handle of a socket that is accepting a connection to the TCP/IP task..................129
Listing 58. Pseudo code showing how an IPStackEvent_t structure is used to send a
network down event to the TCP/IP task ..............................................................130
Listing 59. Pseudo code showing how an IPStackEvent_t structure is used to send a
network down to the TCP/IP task ........................................................................130
Listing 60. The xQueueCreateSet() API function prototype ..................................................132
Listing 61. The xQueueAddToSet() API function prototype ..................................................134
Listing 62. The xQueueSelectFromSet() API function prototype...........................................135
Listing 63. Implementation of main() for Example 12............................................................138
Listing 64. The sending tasks used in Example 12...............................................................139
Listing 65. The receive task used in Example 12..................................................................140
Listing 66. Using a queue set that contains queues and semaphores ..................................142
Listing 67. A queue being created for use as a mailbox .......................................................144
Listing 68. The xQueueOverwrite() API function prototype...................................................144
Listing 69. Using the xQueueOverwrite() API function..........................................................145
Listing 70. The xQueuePeek() API function prototype..........................................................146
Listing 71. Using the xQueuePeek() API function.................................................................146
Listing 72. The software timer callback function prototype ...................................................149
Listing 73. The xTimerCreate() API function prototype .........................................................158
xxi
Listing 74. The xTimerStart() API function prototype............................................................ 160
Listing 75. Creating and starting the timers used in Example 13 .......................................... 163
Listing 76. The callback function used by the one-shot timer in Example 13........................ 164
Listing 77. The callback function used by the auto-reload timer in Example 13.................... 164
Listing 78. The vTimerSetTimerID() API function prototype ................................................. 166
Listing 79. The pvTimerGetTimerID() API function prototype ............................................... 166
Listing 80. Creating the timers used in Example 14 ............................................................. 167
Listing 81. The timer callback function used in Example 14 ................................................. 168
Listing 82. The xTimerChangePeriod() API function prototype............................................. 170
Listing 83. Using xTimerChangePeriod() ............................................................................. 173
Listing 84. The xTimerReset() API function prototype .......................................................... 175
Listing 85. The callback function for the one-shot timer used in Example 15........................ 177
Listing 86. The task used to reset the software timer in Example 15.................................... 178
Listing 87. The portEND_SWITCHING_ISR() macros.......................................................... 188
Listing 88. The portYIELD_FROM_ISR() macros................................................................. 188
Listing 89. The xSemaphoreCreateBinary() API function prototype ..................................... 194
Listing 90. The xSemaphoreTake() API function prototype .................................................. 195
Listing 91. The xSemaphoreGiveFromISR() API function prototype..................................... 196
Listing 92. Implementation of the task that periodically generates a software interrupt in
Example 16 ........................................................................................................ 198
Listing 93. The implementation of the task to which the interrupt processing is deferred
(the task that synchronizes with the interrupt) in Example 16.............................. 199
Listing 94. The ISR for the software interrupt used in Example 16 ....................................... 200
Listing 95. The implementation of main() for Example 16..................................................... 201
Listing 96. The recommended structure of a deferred interrupt processing task, using a
UART receive handler as an example ................................................................ 207
Listing 97. The xSemaphoreCreateCounting() API function prototype ................................. 210
Listing 98. The call to xSemaphoreCreateCounting() used to create the counting
semaphore in Example 17 .................................................................................. 211
Listing 99. The implementation of the interrupt service routine used by Example 17............ 212
Listing 100. The xTimerPendFunctionCallFromISR() API function prototype ....................... 214
Listing 101. The prototype to which a function passed in the xFunctionToPend
parameter of xTimerPendFunctionCallFromISR() must conform......................... 214
Listing 102. The software interrupt handler used in Example 18 .......................................... 217
Listing 103. The function that performs the processing necessitated by the interrupt in
Example 18. ....................................................................................................... 217
Listing 104. The implementation of main() for Example 18................................................... 218
Listing 105. The xQueueSendToFrontFromISR() API function prototype ............................. 220
Listing 106. The xQueueSendToBackFromISR() API function prototype ............................. 220
Listing 107. The implementation of the task that writes to the queue in Example 19............ 223
Listing 108. The implementation of the interrupt service routine used by Example 19.......... 224
Listing 109. The task that prints out the strings received from the interrupt service
routine in Example 19......................................................................................... 225
Listing 110. The main() function for Example 19 .................................................................. 226
Listing 111. An example read, modify, write sequence ........................................................ 234
xxii
Listing 112. An example of a reentrant function....................................................................236
Listing 113. An example of a function that is not reentrant ...................................................236
Listing 114. Using a critical section to guard access to a register.........................................238
Listing 115. A possible implementation of vPrintString().......................................................239
Listing 116. Using a critical section in an interrupt service routine........................................240
Listing 117. The vTaskSuspendAll() API function prototype .................................................241
Listing 118. The xTaskResumeAll() API function prototype..................................................241
Listing 119. The implementation of vPrintString().................................................................242
Listing 120. The xSemaphoreCreateMutex() API function prototype ....................................245
Listing 121. The implementation of prvNewPrintString().......................................................246
Listing 122. The implementation of prvPrintTask() for Example 20.......................................247
Listing 123. The implementation of main() for Example 20...................................................248
Listing 124. Creating and using a recursive mutex ...............................................................254
Listing 125. A task that uses a mutex in a tight loop.............................................................256
Listing 126. Ensuring tasks that use a mutex in a loop receive a more equal amount of
processing time, while also ensuring processing time is not wasted by
switching between tasks too rapidly ....................................................................258
Listing 127. The name and prototype for a tick hook function...............................................260
Listing 128. The gatekeeper task .........................................................................................260
Listing 129. The print task implementation for Example 21 ..................................................261
Listing 130. The tick hook implementation............................................................................262
Listing 131. The implementation of main() for Example 21...................................................263
Listing 132. The xEventGroupCreate() API function prototype .............................................271
Listing 133. The xEventGroupSetBits() API function prototype.............................................272
Listing 134. The xEventGroupSetBitsFromISR() API function prototype...............................273
Listing 135. The xEventGroupWaitBits() API function prototype...........................................275
Listing 136. Event bit definitions used in Example 22...........................................................279
Listing 137. The task that sets two bits in the event group in Example 22 ............................280
Listing 138. The ISR that sets bit 2 in the event group in Example 22 ..................................281
Listing 139. The task that blocks to wait for event bits to become set in Example 22 ...........282
Listing 140. Creating the event group and tasks in Example 22 ...........................................283
Listing 141. Pseudo code for two tasks that synchronize with each other to ensure a
shared TCP socket is no longer in use by either task before the socket is
closed .................................................................................................................286
Listing 142. The xEventGroupSync() API function prototype................................................288
Listing 143. The implementation of the task used in Example 23 .........................................290
Listing 144. The main() function used in Example 23 ...........................................................291
Listing 145. The xTaskNotifyGive() API function prototype...................................................298
Listing 146. The vTaskNotifyGiveFromISR() API function prototype.....................................299
Listing 147. The ulTaskNotifyTake() API function prototype .................................................300
Listing 148. The implementation of the task to which the interrupt processing is deferred
(the task that synchronizes with the interrupt) in Example 24..............................303
Listing 149. The implementation of the interrupt service routine used in Example 24...........304
xxiii
Listing 150. The implementation of the task to which the interrupt processing is deferred
(the task that synchronizes with the interrupt) in Example 25.............................. 306
Listing 151. The implementation of the interrupt service routine used in Example 25........... 306
Listing 152. Prototypes for the xTaskNotify() and xTaskNotifyFromISR() API functions ....... 308
Listing 153. The xTaskNotifyWait() API function prototype................................................... 310
Listing 154. Pseudo code demonstrating how a binary semaphore can be used in a
driver library transmit function............................................................................. 315
Listing 155. Pseudo code demonstrating how a task notification can be used in a driver
library transmit function....................................................................................... 317
Listing 156. Pseudo code demonstrating how a task notification can be used in a driver
library receive function........................................................................................ 319
Listing 157. Pseudo code demonstrating how a task notification can be used to pass a
value to a task .................................................................................................... 321
Listing 158. The structure and data type sent on a queue to the server task........................ 323
Listing 159. The Implementation of the Cloud Read API Function ....................................... 324
Listing 160. The Server Task Processing a Read Request .................................................. 324
Listing 161. The Implementation of the Cloud Write API Function........................................ 325
Listing 162. The Server Task Processing a Send Request .................................................. 326
Listing 163 Using the standard C assert() macro to check pxMyPointer is not NULL ............ 330
Listing 164 A simple configASSERT() definition useful when executing under the control
of a debugger ..................................................................................................... 331
Listing 165 A configASSERT() definition that records the source code line that failed an
assertion............................................................................................................. 331
Listing 166. The uxTaskGetSystemState() API function prototype ....................................... 339
Listing 167. The TaskStatus_t structure............................................................................... 341
Listing 168. The vTaskList() API function prototype ............................................................. 343
Listing 169. The vTaskGetRunTimeStats() API function prototype....................................... 344
Listing 170. 16-bit timer overflow interrupt handler used to count timer overflows ................ 346
Listing 171. Macros added to FreeRTOSConfig.h to enable the collection of run-time
statistics.............................................................................................................. 346
Listing 172. The task that prints out the collected run-time statistics .................................... 347
Listing 173. The uxTaskGetStackHighWaterMark() API function prototype.......................... 359
Listing 174. The stack overflow hook function prototype ...................................................... 360
List of Tables
Table 1. FreeRTOS source files to include in the project ....................................................... 20
Table 2. Port specific data types used by FreeRTOS............................................................. 21
Table 3. Macro prefixes ......................................................................................................... 23
Table 4. Common macro definitions....................................................................................... 23
Table 5. vPortDefineHeapRegions() parameters.................................................................... 37
Table 6. xPortGetFreeHeapSize() return value ...................................................................... 41
Table 7. xPortGetMinimumEverFreeHeapSize() return value................................................. 42
Table 8. xTaskCreate() parameters and return value............................................................. 48
Table 9. vTaskDelay() parameters......................................................................................... 67
xxiv
Table 10. vTaskDelayUntil() parameters ................................................................................71
Table 11. vTaskPrioritySet() parameters................................................................................79
Table 12. uxTaskPriorityGet() parameters and return value ...................................................80
Table 13. vTaskDelete() parameters ......................................................................................85
Table 14. The FreeRTOSConfig.h settings that configure the kernel to use Prioritized
Pre-emptive Scheduling with Time Slicing ............................................................91
Table 15. An explanation of the terms used to describe the scheduling policy .......................92
Table 16. The FreeRTOSConfig.h settings that configure the kernel to use Prioritized
Pre-emptive Scheduling without Time Slicing........................................................96
Table 17. The FreeRTOSConfig.h settings that configure the kernel to use co-operative
scheduling ............................................................................................................98
Table 18. xQueueCreate() parameters and return value ......................................................108
Table 19. xQueueSendToFront() and xQueueSendToBack() function parameters and
return value.........................................................................................................109
Table 20. xQueueReceive() function parameters and return values .....................................112
Table 21. uxQueueMessagesWaiting() function parameters and return value......................114
Table 22. Key to Figure 36...................................................................................................124
Table 23. xQueueCreateSet() parameters and return value .................................................133
Table 24. xQueueAddToSet() parameters and return value .................................................134
Table 25. xQueueSelectFromSet() parameters and return value .........................................136
Table 26. xQueueOverwrite() parameters and return value..................................................145
Table 27. xTimerCreate() parameters and return value........................................................158
Table 28. xTimerStart() parameters and return value ...........................................................160
Table 29. vTimerSetTimerID() parameters ...........................................................................166
Table 30. pvTimerGetTimerID() parameters and return value ..............................................167
Table 31. xTimerChangePeriod() parameters and return value............................................171
Table 32. xTimerReset() parameters and return value .........................................................175
Table 33. xSemaphoreCreateBinary() Return Value ............................................................194
Table 34. xSemaphoreTake() parameters and return value .................................................195
Table 35. xSemaphoreGiveFromISR() parameters and return value....................................197
Table 36. xSemaphoreCreateCounting() parameters and return value ................................210
Table 37. xTimerPendFunctionCallFromISR() parameters and return value ........................214
Table 38. xQueueSendToFrontFromISR() and xQueueSendToBackFromISR()
parameters and return values .............................................................................220
Table 39. Constants that control interrupt nesting ................................................................228
Table 40. xTaskResumeAll() return value ............................................................................241
Table 41. xSemaphoreCreateMutex() return value...............................................................245
Table 42, xEventGroupCreate() return value........................................................................271
Table 43, xEventGroupSetBits() parameters and return value .............................................272
Table 44, xEventGroupSetBitsFromISR() parameters and return value ...............................273
Table 45, The Effect of the uxBitsToWaitFor and xWaitForAllBits Parameters .....................275
Table 46, xEventGroupWaitBits() parameters and return value............................................277
Table 47, xEventGroupSync() parameters and return value.................................................288
Table 48. xTaskNotifyGive() parameters and return value ...................................................299
xxv
Table 49. vTaskNotifyGiveFromISR() parameters and return value ..................................... 299
Table 50. ulTaskNotifyTake() parameters and return value.................................................. 301
Table 51. xTaskNotify() parameters and return value .......................................................... 308
Table 52. Valid xTaskNotify() eNotifyAction Parameter Values, and Their Resultant
Effect on the Receiving Task’s Notification Value ............................................... 309
Table 53. xTaskNotifyWait() parameters and return value ................................................... 310
Table 54. Macros used in the collection of run-time statistics............................................... 338
Table 55, uxTaskGetSystemState() parameters and return value........................................ 340
Table 56. TaskStatus_t structure members.......................................................................... 341
Table 57. vTaskList() parameters ........................................................................................ 343
Table 58. vTaskGetRunTimeStats() parameters.................................................................. 344
Table 59. A selection of the most commonly used trace hook macros ................................. 348
Table 60. uxTaskGetStackHighWaterMark() parameters and return value........................... 359
xxvi
List of Notation
ADC Analog to Digital Converter
API Application Programming Interface
DMA Direct Memory Access
FAQ Frequently Asked Question
FIFO First In First Out
HMI Human Machine Interface
IDE Integrated Development Environment
IRQ Interrupt Request
ISR Interrupt Service Routine
LCD Liquid Crystal Display
MCU Microcontroller
RMS Rate Monotonic Scheduling
RTOS Real-time Operating System
SIL Safety Integrity Level
SPI Serial Peripheral Interface
TCB Task Control Block
UART Universal Asynchronous Receiver/Transmitter