2 * FreeRTOS Kernel V10.2.1
\r
3 * Copyright (C) 2017 Amazon.com, Inc. or its affiliates. All Rights Reserved.
\r
5 * Permission is hereby granted, free of charge, to any person obtaining a copy of
\r
6 * this software and associated documentation files (the "Software"), to deal in
\r
7 * the Software without restriction, including without limitation the rights to
\r
8 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
\r
9 * the Software, and to permit persons to whom the Software is furnished to do so,
\r
10 * subject to the following conditions:
\r
12 * The above copyright notice and this permission notice shall be included in all
\r
13 * copies or substantial portions of the Software.
\r
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
\r
16 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
\r
17 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
\r
18 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
\r
19 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
\r
20 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
\r
22 * http://www.FreeRTOS.org
\r
23 * http://aws.amazon.com/freertos
\r
25 * 1 tab == 4 spaces!
\r
28 /* Kernel includes. */
\r
29 #include "FreeRTOS.h"
\r
32 /* Standard includes. */
\r
35 /* IoT SDK includes. */
\r
36 #include "iot_taskpool.h"
\r
38 /* The priority at which that tasks in the task pool (the worker tasks) get
\r
40 #define tpTASK_POOL_WORKER_PRIORITY 1
\r
43 * Prototypes for the functions that demonstrate the task pool API.
\r
45 static void prvExample_BasicSingleJob( void );
\r
46 static void prvExample_DeferredSingleJob( void );
\r
47 static void prvExample_BasicRecyclableJob( void );
\r
48 static void prvExample_ReuseRecyclableJobFromLowPriorityTask( void );
\r
49 static void prvExample_ReuseRecyclableJobFromHighPriorityTask( void );
\r
51 /* Prototypes of the callback functions used in the examples. */
\r
52 static void prvSimpleTaskNotifyCallback( IotTaskPool_t pTaskPool, IotTaskPoolJob_t pJob, void *pUserContext );
\r
55 * Prototypes for the standard FreeRTOS application hook (callback) functions
\r
56 * implemented within this file. See http://www.freertos.org/a00016.html .
\r
58 void vApplicationMallocFailedHook( void );
\r
59 void vApplicationIdleHook( void );
\r
60 void vApplicationStackOverflowHook( TaskHandle_t pxTask, char *pcTaskName );
\r
61 void vApplicationTickHook( void );
\r
62 void vApplicationGetIdleTaskMemory( StaticTask_t **ppxIdleTaskTCBBuffer, StackType_t **ppxIdleTaskStackBuffer, uint32_t *pulIdleTaskStackSize );
\r
63 void vApplicationGetTimerTaskMemory( StaticTask_t **ppxTimerTaskTCBBuffer, StackType_t **ppxTimerTaskStackBuffer, uint32_t *pulTimerTaskStackSize );
\r
66 * The task used to demonstrate the task pool API.
\r
68 static void prvTaskPoolDemoTask( void *pvParameters );
\r
70 static const IotTaskPoolInfo_t xTaskPoolParameters = {
\r
71 /* Minimum number of threads in a task pool. */
\r
73 /* Maximum number of threads in a task pool. */
\r
75 /* Stack size for every task pool thread - in words, not bytes. */
\r
76 configMINIMAL_STACK_SIZE,
\r
77 /* Priority for every task pool thread. */
\r
78 tpTASK_POOL_WORKER_PRIORITY,
\r
81 /*-----------------------------------------------------------*/
\r
85 /* This example uses a single application task, which in turn is used to
\r
86 create and send jobs to task pool tasks. */
\r
87 xTaskCreate( prvTaskPoolDemoTask, /* Function that implements the task. */
\r
88 "PoolDemo", /* Text name for the task - only used for debugging. */
\r
89 configMINIMAL_STACK_SIZE, /* Size of stack (in words, not bytes) to allocate for the task. */
\r
90 NULL, /* Task parameter - not used in this case. */
\r
91 tskIDLE_PRIORITY, /* Task priority, must be between 0 and configMAX_PRIORITIES - 1. */
\r
92 NULL ); /* Used to pass out a handle to the created tsak - not used in this case. */
\r
94 vTaskStartScheduler();
\r
96 /* Should not reach here as vTaskStartScheduler() will only return if there
\r
97 was insufficient FreeRTOS heap memory to create the Idle or Timer
\r
101 /*-----------------------------------------------------------*/
\r
103 static void prvTaskPoolDemoTask( void *pvParameters )
\r
105 IotTaskPoolError_t xResult;
\r
108 /* Remove compiler warnings about unused parameters. */
\r
109 ( void ) pvParameters;
\r
111 /* The task pool must be created before it can be used. */
\r
112 xResult = IotTaskPool_CreateSystemTaskPool( &xTaskPoolParameters );
\r
113 configASSERT( xResult == IOT_TASKPOOL_SUCCESS );
\r
115 /* Attempting to create the task pool again should then appear to succeed
\r
116 (in case it is initialised by more than one library), but have no effect. */
\r
117 xResult = IotTaskPool_CreateSystemTaskPool( &xTaskPoolParameters );
\r
118 configASSERT( xResult == IOT_TASKPOOL_SUCCESS );
\r
122 /* Demonstrate the most basic use case where a non persistent job is
\r
123 created and scheduled to run immediately. The task pool worker tasks
\r
124 (in which the job callback function executes) have a priority above the
\r
125 priority of this task so the job's callback executes as soon as it is
\r
127 prvExample_BasicSingleJob();
\r
129 /* Demonstrate a job being scheduled to run at some time in the
\r
130 future, and how a job scheduled to run in the future can be cancelled if
\r
131 it has not yet started executing. */
\r
132 prvExample_DeferredSingleJob();
\r
134 /* Demonstrate the most basic use of a recyclable job. This is similar
\r
135 to prvExample_BasicSingleJob() but using a recyclable job. Creating a
\r
136 recyclable job will re-use a previously created and now spare job from
\r
137 the task pool's job cache if one is available, or otherwise dynamically
\r
138 create a new job if a spare job is not available in the cache but space
\r
139 remains in the cache. */
\r
140 prvExample_BasicRecyclableJob();
\r
142 /* Demonstrate multiple recyclable jobs being created, used, and then
\r
143 re-used. In this the task pool worker tasks (in which the job callback
\r
144 functions execute) have a priority above the priority of this task so
\r
145 the job's callback functions execute as soon as they are scheduled. */
\r
146 prvExample_ReuseRecyclableJobFromLowPriorityTask();
\r
148 /* Again demonstrate multiple recyclable jobs being used, but this time
\r
149 the priority of the task pool worker tasks (in which the job callback
\r
150 functions execute) are lower than the priority of this task so the job's
\r
151 callback functions don't execute until this task enteres the blocked
\r
153 prvExample_ReuseRecyclableJobFromHighPriorityTask();
\r
156 if( ( ulLoops % 10UL ) == 0 )
\r
158 printf( "Performed %u successful iterations.\r\n", ulLoops );
\r
163 /*-----------------------------------------------------------*/
\r
165 static void prvSimpleTaskNotifyCallback( IotTaskPool_t pTaskPool, IotTaskPoolJob_t pJob, void *pUserContext )
\r
167 TaskHandle_t xTaskToNotify = ( TaskHandle_t ) pUserContext;
\r
169 /* Remove warnings about unused parameters. */
\r
170 ( void ) pTaskPool;
\r
173 /* Notify the task that created this job. */
\r
174 xTaskNotifyGive( xTaskToNotify );
\r
176 /*-----------------------------------------------------------*/
\r
178 static void prvExample_BasicSingleJob( void )
\r
180 IotTaskPoolJobStorage_t xJobStorage;
\r
181 IotTaskPoolJob_t xJob;
\r
182 IotTaskPoolError_t xResult;
\r
184 const uint32_t ulNoFlags = 0UL;
\r
185 const TickType_t xNoDelay = ( TickType_t ) 0;
\r
186 size_t xFreeHeapBeforeCreatingJob = xPortGetFreeHeapSize();
\r
187 IotTaskPoolJobStatus_t xJobStatus;
\r
189 /* Don't expect any notifications to be pending yet. */
\r
190 configASSERT( ulTaskNotifyTake( pdTRUE, 0 ) == 0 );
\r
192 /* Create and schedule a job using the handle of this task as the job's
\r
193 context and the function that sends a notification to the task handle as
\r
194 the jobs callback function. The job is created using storage allocated on
\r
195 the stack of this function - so no memory is allocated. */
\r
196 xResult = IotTaskPool_CreateJob( prvSimpleTaskNotifyCallback, /* Callback function. */
\r
197 ( void * ) xTaskGetCurrentTaskHandle(), /* Job context. */
\r
200 configASSERT( xResult == IOT_TASKPOOL_SUCCESS );
\r
202 /* The job has been created but not scheduled so is now ready. */
\r
203 IotTaskPool_GetStatus( NULL, xJob, &xJobStatus );
\r
204 configASSERT( xJobStatus == IOT_TASKPOOL_STATUS_READY );
\r
206 /* This is not a persistent (recyclable) job and its storage is on the
\r
207 stack of this function, so the amount of heap space available should not
\r
208 have chanced since entering this function. */
\r
209 configASSERT( xFreeHeapBeforeCreatingJob == xPortGetFreeHeapSize() );
\r
211 /* In the full task pool implementation the first parameter is used to
\r
212 pass the handle of the task pool to schedule. The lean task pool
\r
213 implementation used in this demo only supports a single task pool, which
\r
214 is created internally within the library, so the first parameter is NULL. */
\r
215 xResult = IotTaskPool_Schedule( NULL, xJob, ulNoFlags );
\r
216 configASSERT( xResult == IOT_TASKPOOL_SUCCESS );
\r
218 /* Look for the notification coming from the job's callback function. The
\r
219 priority of the task pool worker task that executes the callback is higher
\r
220 than the priority of this task so a block time is not needed - the task pool
\r
221 worker task pre-empts this task and sends the notification (from the job's
\r
222 callback) as soon as the job is scheduled. */
\r
223 ulReturn = ulTaskNotifyTake( pdTRUE, xNoDelay );
\r
224 configASSERT( ulReturn );
\r
226 /* The job's callback has executed so the job has now completed. */
\r
227 IotTaskPool_GetStatus( NULL, xJob, &xJobStatus );
\r
228 configASSERT( xJobStatus == IOT_TASKPOOL_STATUS_COMPLETED );
\r
230 /*-----------------------------------------------------------*/
\r
232 static void prvExample_DeferredSingleJob( void )
\r
234 IotTaskPoolJobStorage_t xJobStorage;
\r
235 IotTaskPoolJob_t xJob;
\r
236 IotTaskPoolError_t xResult;
\r
238 const uint32_t ulShortDelay_ms = 100UL;
\r
239 const TickType_t xNoDelay = ( TickType_t ) 0, xAllowableMargin = ( TickType_t ) 5; /* Large margin for Windows port, which is not real time. */
\r
240 TickType_t xTimeBefore, xElapsedTime, xShortDelay_ticks;
\r
241 size_t xFreeHeapBeforeCreatingJob = xPortGetFreeHeapSize();
\r
242 IotTaskPoolJobStatus_t xJobStatus;
\r
244 /* Don't expect any notifications to be pending yet. */
\r
245 configASSERT( ulTaskNotifyTake( pdTRUE, 0 ) == 0 );
\r
247 /* Create a job using the handle of this task as the job's context and the
\r
248 function that sends a notification to the task handle as the jobs callback
\r
249 function. The job is created using storage allocated on the stack of this
\r
250 function - so no memory is allocated. */
\r
251 xResult = IotTaskPool_CreateJob( prvSimpleTaskNotifyCallback, /* Callback function. */
\r
252 ( void * ) xTaskGetCurrentTaskHandle(), /* Job context. */
\r
255 configASSERT( xResult == IOT_TASKPOOL_SUCCESS );
\r
257 /* The job has been created but not scheduled so is now ready. */
\r
258 IotTaskPool_GetStatus( NULL, xJob, &xJobStatus );
\r
259 configASSERT( xJobStatus == IOT_TASKPOOL_STATUS_READY );
\r
261 /* This is not a persistent (recyclable) job and its storage is on the
\r
262 stack of this function, so the amount of heap space available should not
\r
263 have chanced since entering this function. */
\r
264 configASSERT( xFreeHeapBeforeCreatingJob == xPortGetFreeHeapSize() );
\r
266 /* Schedule the job to run its callback in xShortDelay_ms milliseconds time.
\r
267 In the full task pool implementation the first parameter is used to pass the
\r
268 handle of the task pool to schedule. The lean task pool implementation used
\r
269 in this demo only supports a single task pool, which is created internally
\r
270 within the library, so the first parameter is NULL. */
\r
271 xResult = IotTaskPool_ScheduleDeferred( NULL, xJob, ulShortDelay_ms );
\r
272 configASSERT( xResult == IOT_TASKPOOL_SUCCESS );
\r
274 /* The scheduled job should not have executed yet, so don't expect any
\r
275 notifications and expect the job's status to be 'deferred'. */
\r
276 ulReturn = ulTaskNotifyTake( pdTRUE, xNoDelay );
\r
277 configASSERT( ulReturn == 0 );
\r
278 IotTaskPool_GetStatus( NULL, xJob, &xJobStatus );
\r
279 configASSERT( xJobStatus == IOT_TASKPOOL_STATUS_DEFERRED );
\r
281 /* As the job has not yet been executed it can be stopped. */
\r
282 xResult = IotTaskPool_TryCancel( NULL, xJob, &xJobStatus );
\r
283 configASSERT( xResult == IOT_TASKPOOL_SUCCESS );
\r
284 IotTaskPool_GetStatus( NULL, xJob, &xJobStatus );
\r
285 configASSERT( xJobStatus == IOT_TASKPOOL_STATUS_CANCELED );
\r
287 /* Schedule the job again, and this time wait until its callback is
\r
288 executed (the callback function sends a notification to this task) to see
\r
289 that it executes at the right time. */
\r
290 xTimeBefore = xTaskGetTickCount();
\r
291 xResult = IotTaskPool_ScheduleDeferred( NULL, xJob, ulShortDelay_ms );
\r
292 configASSERT( xResult == IOT_TASKPOOL_SUCCESS );
\r
294 /* Wait twice the deferred execution time to ensure the callback is executed
\r
295 before the call below times out. */
\r
296 ulReturn = ulTaskNotifyTake( pdTRUE, pdMS_TO_TICKS( ulShortDelay_ms * 2UL ) );
\r
297 xElapsedTime = xTaskGetTickCount() - xTimeBefore;
\r
299 /* A single notification should not have been received... */
\r
300 configASSERT( ulReturn == 1 );
\r
302 /* ...and the time since scheduling the job should be greater than or
\r
303 equal to the deferred execution time - which is converted to ticks for
\r
305 xShortDelay_ticks = pdMS_TO_TICKS( ulShortDelay_ms );
\r
306 configASSERT( ( xElapsedTime >= xShortDelay_ticks ) && ( xElapsedTime < ( xShortDelay_ticks + xAllowableMargin ) ) );
\r
308 /*-----------------------------------------------------------*/
\r
310 static void prvExample_BasicRecyclableJob( void )
\r
312 IotTaskPoolJob_t xJob;
\r
313 IotTaskPoolError_t xResult;
\r
315 const uint32_t ulNoFlags = 0UL;
\r
316 const TickType_t xNoDelay = ( TickType_t ) 0;
\r
317 size_t xFreeHeapBeforeCreatingJob = xPortGetFreeHeapSize();
\r
319 /* Don't expect any notifications to be pending yet. */
\r
320 configASSERT( ulTaskNotifyTake( pdTRUE, 0 ) == 0 );
\r
322 /* Create and schedule a job using the handle of this task as the job's
\r
323 context and the function that sends a notification to the task handle as
\r
324 the jobs callback function. The job is created as a recyclable job and in
\r
325 this case the memory used to hold the job status is allocated inside the
\r
326 create function. As the job is persistent it can be used multiple times,
\r
327 as demonstrated in other examples within this demo. In the full task pool
\r
328 implementation the first parameter is used to pass the handle of the task
\r
329 pool this recyclable job is to be associated with. In the lean
\r
330 implementation of the task pool used by this demo there is only one task
\r
331 pool (the system task pool created within the task pool library) so the
\r
332 first parameter is NULL. */
\r
333 xResult = IotTaskPool_CreateRecyclableJob( NULL,
\r
334 prvSimpleTaskNotifyCallback,
\r
335 (void * ) xTaskGetCurrentTaskHandle(),
\r
337 configASSERT( xResult == IOT_TASKPOOL_SUCCESS );
\r
339 /* This recyclable job is persistent, and in this case created dynamically,
\r
340 so expect there to be less heap space then when entering the function. */
\r
341 configASSERT( xPortGetFreeHeapSize() < xFreeHeapBeforeCreatingJob );
\r
343 /* In the full task pool implementation the first parameter is used to
\r
344 pass the handle of the task pool to schedule. The lean task pool
\r
345 implementation used in this demo only supports a single task pool, which
\r
346 is created internally within the library, so the first parameter is NULL. */
\r
347 xResult = IotTaskPool_Schedule( NULL, xJob, ulNoFlags );
\r
348 configASSERT( xResult == IOT_TASKPOOL_SUCCESS );
\r
350 /* Look for the notification coming from the job's callback function. The
\r
351 priority of the task pool worker task that executes the callback is higher
\r
352 than the priority of this task so a block time is not needed - the task pool
\r
353 worker task pre-empts this task and sends the notification (from the job's
\r
354 callback) as soon as the job is scheduled. */
\r
355 ulReturn = ulTaskNotifyTake( pdTRUE, xNoDelay );
\r
356 configASSERT( ulReturn );
\r
358 /* Clean up recyclable job. In the full implementation of the task pool
\r
359 the first parameter is used to pass a handle to the task pool the job is
\r
360 associated with. In the lean implementation of the task pool used by this
\r
361 demo there is only one task pool (the system task pool created in the
\r
362 task pool library itself) so the first parameter is NULL. */
\r
363 IotTaskPool_DestroyRecyclableJob( NULL, xJob );
\r
365 /* Once the job has been deleted the memory used to hold the job is
\r
366 returned, so the available heap should be exactly as when entering this
\r
368 configASSERT( xPortGetFreeHeapSize() == xFreeHeapBeforeCreatingJob );
\r
370 /*-----------------------------------------------------------*/
\r
372 static void prvExample_ReuseRecyclableJobFromLowPriorityTask( void )
\r
374 IotTaskPoolError_t xResult;
\r
375 uint32_t x, xIndex, ulNotificationValue;
\r
376 const uint32_t ulJobsToCreate = 5UL, ulNoFlags = 0UL;
\r
377 IotTaskPoolJob_t xJobs[ ulJobsToCreate ];
\r
378 size_t xFreeHeapBeforeCreatingJob = xPortGetFreeHeapSize();
\r
379 IotTaskPoolJobStatus_t xJobStatus;
\r
381 /* Don't expect any notifications to be pending yet. */
\r
382 configASSERT( ulTaskNotifyTake( pdTRUE, 0 ) == 0 );
\r
384 /* Create ulJobsToCreate jobs using the handle of this task as the job's
\r
385 context and the function that sends a notification to the task handle as
\r
386 the jobs callback function. The jobs are created as a recyclable job and
\r
387 in this case the memory to store the job information is allocated within
\r
388 the create function as at this time there are no recyclable jobs in the
\r
389 task pool jobs cache. As the jobs are persistent they can be used multiple
\r
390 times. In the full task pool implementation the first parameter is used to
\r
391 pass the handle of the task pool this recyclable job is to be associated
\r
392 with. In the lean implementation of the task pool used by this demo there
\r
393 is only one task pool (the system task pool created within the task pool
\r
394 library) so the first parameter is NULL. */
\r
395 for( x = 0; x < ulJobsToCreate; x++ )
\r
397 xResult = IotTaskPool_CreateRecyclableJob( NULL,
\r
398 prvSimpleTaskNotifyCallback,
\r
399 (void * ) xTaskGetCurrentTaskHandle(),
\r
401 configASSERT( xResult == IOT_TASKPOOL_SUCCESS );
\r
403 /* The job has been created but not scheduled so is now ready. */
\r
404 IotTaskPool_GetStatus( NULL, xJobs[ x ], &xJobStatus );
\r
405 configASSERT( xJobStatus == IOT_TASKPOOL_STATUS_READY );
\r
408 /* Demonstrate that the jobs can be recycled by performing twice the number
\r
409 of iterations of scheduling jobs than there actually are created jobs. This
\r
410 works because the task pool task priorities are above the priority of this
\r
411 task, so the tasks that run the jobs pre-empt this task as soon as a job is
\r
413 for( x = 0; x < ( ulJobsToCreate * 2UL ); x++ )
\r
415 /* Make sure array index does not go out of bounds. */
\r
416 xIndex = x % ulJobsToCreate;
\r
418 xResult = IotTaskPool_Schedule( NULL, xJobs[ xIndex ], ulNoFlags );
\r
419 configASSERT( xResult == IOT_TASKPOOL_SUCCESS );
\r
421 /* The priority of the task pool task(s) is higher than the priority
\r
422 of this task, so the job's callback function should have already
\r
423 executed, sending a notification to this task, and incrementing this
\r
424 task's notification value. */
\r
425 xTaskNotifyWait( 0UL, /* Don't clear any bits on entry. */
\r
426 0UL, /* Don't clear any bits on exit. */
\r
427 &ulNotificationValue, /* Obtain the notification value. */
\r
428 0UL ); /* No block time, return immediately. */
\r
429 configASSERT( ulNotificationValue == ( x + 1 ) );
\r
431 /* The job's callback has executed so the job is now completed. */
\r
432 IotTaskPool_GetStatus( NULL, xJobs[ xIndex ], &xJobStatus );
\r
433 configASSERT( xJobStatus == IOT_TASKPOOL_STATUS_COMPLETED );
\r
435 /* To leave the list of jobs empty we can stop re-creating jobs half
\r
436 way through iterations of this loop. */
\r
437 if( x < ulJobsToCreate )
\r
439 /* Recycle the job so it can be used again. In the full task pool
\r
440 implementation the first parameter is used to pass the handle of the
\r
441 task pool this job will be associated with. In this lean task pool
\r
442 implementation only the system task pool exists (the task pool created
\r
443 internally to the task pool library) so the first parameter is just
\r
444 passed as NULL. *//*_RB_ Why not recycle it automatically? */
\r
445 IotTaskPool_RecycleJob( NULL, xJobs[ xIndex ] );
\r
446 xResult = IotTaskPool_CreateRecyclableJob( NULL,
\r
447 prvSimpleTaskNotifyCallback,
\r
448 (void * ) xTaskGetCurrentTaskHandle(),
\r
449 &( xJobs[ xIndex ] ) );
\r
453 /* Clear all the notification value bits again. */
\r
454 xTaskNotifyWait( portMAX_DELAY, /* Clear all bits on entry - portMAX_DELAY is used as it is a portable way of having all bits set. */
\r
455 0UL, /* Don't clear any bits on exit. */
\r
456 NULL, /* Don't need the notification value this time. */
\r
457 0UL ); /* No block time, return immediately. */
\r
458 configASSERT( ulTaskNotifyTake( pdTRUE, 0 ) == 0 );
\r
460 /* Clean up all the recyclable job. In the full implementation of the task
\r
461 pool the first parameter is used to pass a handle to the task pool the job
\r
462 is associated with. In the lean implementation of the task pool used by
\r
463 this demo there is only one task pool (the system task pool created in the
\r
464 task pool library itself) so the first parameter is NULL. */
\r
465 for( x = 0; x < ulJobsToCreate; x++ )
\r
467 xResult = IotTaskPool_DestroyRecyclableJob( NULL, xJobs[ x ] );
\r
468 configASSERT( xResult == IOT_TASKPOOL_SUCCESS );
\r
470 /* Attempting to destroy the same job twice will fail. */
\r
471 //_RB_ vPortFree() asserts because it attempts to free memory again. xResult = IotTaskPool_DestroyRecyclableJob( NULL, xJobs[ x ] );
\r
472 // configASSERT( xResult != IOT_TASKPOOL_SUCCESS );
\r
475 /* Once the job has been deleted the memory used to hold the job is
\r
476 returned, so the available heap should be exactly as when entering this
\r
478 configASSERT( xPortGetFreeHeapSize() == xFreeHeapBeforeCreatingJob );
\r
480 /*-----------------------------------------------------------*/
\r
482 static void prvExample_ReuseRecyclableJobFromHighPriorityTask( void )
\r
484 IotTaskPoolError_t xResult;
\r
485 uint32_t x, ulNotificationValue;
\r
486 const uint32_t ulJobsToCreate = 5UL;
\r
487 const uint32_t ulNoFlags = 0UL;
\r
488 IotTaskPoolJob_t xJobs[ ulJobsToCreate ];
\r
489 IotTaskPoolJobStorage_t xJobStorage[ ulJobsToCreate ];
\r
490 size_t xFreeHeapBeforeCreatingJob = xPortGetFreeHeapSize();
\r
491 TickType_t xShortDelay = pdMS_TO_TICKS( 150 );
\r
492 IotTaskPoolJobStatus_t xJobStatus;
\r
494 /* Don't expect any notifications to be pending yet. */
\r
495 configASSERT( ulTaskNotifyTake( pdTRUE, 0 ) == 0 );
\r
497 /* prvExample_ReuseRecyclableJobFromLowPriorityTask() executes in a task
\r
498 that has a lower [task] priority than the task pool's worker tasks.
\r
499 Therefore a talk pool worker preempts the task that calls
\r
500 prvExample_ReuseRecyclableJobFromHighPriorityTask() as soon as the job is
\r
501 scheduled. prvExample_ReuseRecyclableJobFromHighPriorityTask() reverses the
\r
502 priorities - prvExample_ReuseRecyclableJobFromHighPriorityTask() raises its
\r
503 priority to above the task pool's worker tasks, so the worker tasks do not
\r
504 execute until the calling task enters the blocked state. First raise the
\r
505 priority - passing NULL means raise the priority of the calling task. */
\r
506 vTaskPrioritySet( NULL, tpTASK_POOL_WORKER_PRIORITY + 1 );
\r
508 /* Create ulJobsToCreate jobs using the handle of this task as the job's
\r
509 context and the function that sends a notification to the task handle as
\r
510 the jobs callback function. */
\r
511 for( x = 0; x < ulJobsToCreate; x++ )
\r
513 xResult = IotTaskPool_CreateJob( prvSimpleTaskNotifyCallback, /* Callback function. */
\r
514 ( void * ) xTaskGetCurrentTaskHandle(), /* Job context. */
\r
515 &( xJobStorage[ x ] ),
\r
517 configASSERT( xResult == IOT_TASKPOOL_SUCCESS );
\r
519 /* This is not a persistent (recyclable) job and its storage is on the
\r
520 stack of this function, so the amount of heap space available should not
\r
521 have chanced since entering this function. */
\r
522 configASSERT( xFreeHeapBeforeCreatingJob == xPortGetFreeHeapSize() );
\r
525 for( x = 0; x < ulJobsToCreate; x++ )
\r
527 /* Schedule the next job. */
\r
528 xResult = IotTaskPool_Schedule( NULL, xJobs[ x ], ulNoFlags );
\r
529 configASSERT( xResult == IOT_TASKPOOL_SUCCESS );
\r
531 /* Although scheduled, the job's callback has not executed, so the job
\r
532 reports itself as scheduled. */
\r
533 IotTaskPool_GetStatus( NULL, xJobs[ x ], &xJobStatus );
\r
534 configASSERT( xJobStatus == IOT_TASKPOOL_STATUS_SCHEDULED );
\r
536 /* The priority of the task pool task(s) is lower than the priority
\r
537 of this task, so the job's callback function should not have executed
\r
538 yes, so don't expect the notification value for this task to have
\r
540 xTaskNotifyWait( 0UL, /* Don't clear any bits on entry. */
\r
541 0UL, /* Don't clear any bits on exit. */
\r
542 &ulNotificationValue, /* Obtain the notification value. */
\r
543 0UL ); /* No block time, return immediately. */
\r
544 configASSERT( ulNotificationValue == 0 );
\r
547 /* At this point there are ulJobsToCreate scheduled, but none have executed
\r
548 their callbacks because the priority of this task is higher than the
\r
549 priority of the task pool worker threads. When this task blocks to wait for
\r
550 a notification a worker thread will be able to executes - but as soon as its
\r
551 callback function sends a notification to this task this task will
\r
552 preempt it (because it has a higher priority) so this task only expects to
\r
553 receive one notification at a time. */
\r
554 for( x = 0; x < ulJobsToCreate; x++ )
\r
556 xTaskNotifyWait( 0UL, /* Don't clear any bits on entry. */
\r
557 0UL, /* Don't clear any bits on exit. */
\r
558 &ulNotificationValue, /* Obtain the notification value. */
\r
559 xShortDelay ); /* Short delay to allow a task pool worker to execute. */
\r
560 configASSERT( ulNotificationValue == ( x + 1 ) );
\r
563 /* All the scheduled jobs have now executed, so waiting for another
\r
564 notification should timeout without the notification value changing. */
\r
565 xTaskNotifyWait( 0UL, /* Don't clear any bits on entry. */
\r
566 0UL, /* Don't clear any bits on exit. */
\r
567 &ulNotificationValue, /* Obtain the notification value. */
\r
568 xShortDelay ); /* Short delay to allow a task pool worker to execute. */
\r
569 configASSERT( ulNotificationValue == x );
\r
571 /* Reset the priority of this task and clear the notifications ready for the
\r
573 vTaskPrioritySet( NULL, tskIDLE_PRIORITY );
\r
574 xTaskNotifyWait( portMAX_DELAY, /* Clear all bits on entry - portMAX_DELAY is used as it is a portable way of having all bits set. */
\r
575 0UL, /* Don't clear any bits on exit. */
\r
576 NULL, /* Don't need the notification value this time. */
\r
577 0UL ); /* No block time, return immediately. */
\r
579 /*-----------------------------------------------------------*/
\r
581 void vApplicationMallocFailedHook( void )
\r
583 /* vApplicationMallocFailedHook() will only be called if
\r
584 configUSE_MALLOC_FAILED_HOOK is set to 1 in FreeRTOSConfig.h. It is a hook
\r
585 function that will get called if a call to pvPortMalloc() fails.
\r
586 pvPortMalloc() is called internally by the kernel whenever a task, queue,
\r
587 timer or semaphore is created. It is also called by various parts of the
\r
588 demo application. If heap_1.c, heap_2.c or heap_4.c is being used, then the
\r
589 size of the heap available to pvPortMalloc() is defined by
\r
590 configTOTAL_HEAP_SIZE in FreeRTOSConfig.h, and the xPortGetFreeHeapSize()
\r
591 API function can be used to query the size of free heap space that remains
\r
592 (although it does not provide information on how the remaining heap might be
\r
593 fragmented). See http://www.freertos.org/a00111.html for more
\r
595 vAssertCalled( __LINE__, __FILE__ );
\r
597 /*-----------------------------------------------------------*/
\r
599 void vApplicationIdleHook( void )
\r
601 /* vApplicationIdleHook() will only be called if configUSE_IDLE_HOOK is set
\r
602 to 1 in FreeRTOSConfig.h. It will be called on each iteration of the idle
\r
603 task. It is essential that code added to this hook function never attempts
\r
604 to block in any way (for example, call xQueueReceive() with a block time
\r
605 specified, or call vTaskDelay()). If application tasks make use of the
\r
606 vTaskDelete() API function to delete themselves then it is also important
\r
607 that vApplicationIdleHook() is permitted to return to its calling function,
\r
608 because it is the responsibility of the idle task to clean up memory
\r
609 allocated by the kernel to any task that has since deleted itself. */
\r
611 /*-----------------------------------------------------------*/
\r
613 void vApplicationStackOverflowHook( TaskHandle_t pxTask, char *pcTaskName )
\r
615 ( void ) pcTaskName;
\r
618 /* Run time stack overflow checking is performed if
\r
619 configCHECK_FOR_STACK_OVERFLOW is defined to 1 or 2. This hook
\r
620 function is called if a stack overflow is detected. This function is
\r
621 provided as an example only as stack overflow checking does not function
\r
622 when running the FreeRTOS Windows port. */
\r
623 vAssertCalled( __LINE__, __FILE__ );
\r
625 /*-----------------------------------------------------------*/
\r
627 void vApplicationTickHook( void )
\r
629 /* This function will be called by each tick interrupt if
\r
630 configUSE_TICK_HOOK is set to 1 in FreeRTOSConfig.h. User code can be
\r
631 added here, but the tick hook is called from an interrupt context, so
\r
632 code must not attempt to block, and only the interrupt safe FreeRTOS API
\r
633 functions can be used (those that end in FromISR()). */
\r
635 /*-----------------------------------------------------------*/
\r
637 void vApplicationDaemonTaskStartupHook( void )
\r
639 /* This function will be called once only, when the daemon task starts to
\r
640 execute (sometimes called the timer task). This is useful if the
\r
641 application includes initialisation code that would benefit from executing
\r
642 after the scheduler has been started. */
\r
644 /*-----------------------------------------------------------*/
\r
646 void vAssertCalled( unsigned long ulLine, const char * const pcFileName )
\r
648 volatile uint32_t ulSetToNonZeroInDebuggerToContinue = 0;
\r
650 /* Called if an assertion passed to configASSERT() fails. See
\r
651 http://www.freertos.org/a00110.html#configASSERT for more information. */
\r
653 /* Parameters are not used. */
\r
655 ( void ) pcFileName;
\r
658 taskENTER_CRITICAL();
\r
660 printf( "Assert hit on line %lu of %s\r\n", ulLine, pcFileName );
\r
663 /* You can step out of this function to debug the assertion by using
\r
664 the debugger to set ulSetToNonZeroInDebuggerToContinue to a non-zero
\r
666 while( ulSetToNonZeroInDebuggerToContinue == 0 )
\r
668 __asm volatile( "NOP" );
\r
669 __asm volatile( "NOP" );
\r
672 taskEXIT_CRITICAL();
\r
674 /*-----------------------------------------------------------*/
\r
676 /* configUSE_STATIC_ALLOCATION is set to 1, so the application must provide an
\r
677 implementation of vApplicationGetIdleTaskMemory() to provide the memory that is
\r
678 used by the Idle task. */
\r
679 void vApplicationGetIdleTaskMemory( StaticTask_t **ppxIdleTaskTCBBuffer, StackType_t **ppxIdleTaskStackBuffer, uint32_t *pulIdleTaskStackSize )
\r
681 /* If the buffers to be provided to the Idle task are declared inside this
\r
682 function then they must be declared static - otherwise they will be allocated on
\r
683 the stack and so not exists after this function exits. */
\r
684 static StaticTask_t xIdleTaskTCB;
\r
685 static StackType_t uxIdleTaskStack[ configMINIMAL_STACK_SIZE ];
\r
687 /* Pass out a pointer to the StaticTask_t structure in which the Idle task's
\r
688 state will be stored. */
\r
689 *ppxIdleTaskTCBBuffer = &xIdleTaskTCB;
\r
691 /* Pass out the array that will be used as the Idle task's stack. */
\r
692 *ppxIdleTaskStackBuffer = uxIdleTaskStack;
\r
694 /* Pass out the size of the array pointed to by *ppxIdleTaskStackBuffer.
\r
695 Note that, as the array is necessarily of type StackType_t,
\r
696 configMINIMAL_STACK_SIZE is specified in words, not bytes. */
\r
697 *pulIdleTaskStackSize = configMINIMAL_STACK_SIZE;
\r
699 /*-----------------------------------------------------------*/
\r
701 /* configUSE_STATIC_ALLOCATION and configUSE_TIMERS are both set to 1, so the
\r
702 application must provide an implementation of vApplicationGetTimerTaskMemory()
\r
703 to provide the memory that is used by the Timer service task. */
\r
704 void vApplicationGetTimerTaskMemory( StaticTask_t **ppxTimerTaskTCBBuffer, StackType_t **ppxTimerTaskStackBuffer, uint32_t *pulTimerTaskStackSize )
\r
706 /* If the buffers to be provided to the Timer task are declared inside this
\r
707 function then they must be declared static - otherwise they will be allocated on
\r
708 the stack and so not exists after this function exits. */
\r
709 static StaticTask_t xTimerTaskTCB;
\r
710 static StackType_t uxTimerTaskStack[ configTIMER_TASK_STACK_DEPTH ];
\r
712 /* Pass out a pointer to the StaticTask_t structure in which the Timer
\r
713 task's state will be stored. */
\r
714 *ppxTimerTaskTCBBuffer = &xTimerTaskTCB;
\r
716 /* Pass out the array that will be used as the Timer task's stack. */
\r
717 *ppxTimerTaskStackBuffer = uxTimerTaskStack;
\r
719 /* Pass out the size of the array pointed to by *ppxTimerTaskStackBuffer.
\r
720 Note that, as the array is necessarily of type StackType_t,
\r
721 configMINIMAL_STACK_SIZE is specified in words, not bytes. */
\r
722 *pulTimerTaskStackSize = configTIMER_TASK_STACK_DEPTH;
\r
projects / freertos / blob