2 * FreeRTOS Kernel V10.2.1
\r
3 * Copyright (C) 2019 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
30 * Demonstrates and tests mutexes being used from an interrupt.
\r
36 /* Scheduler include files. */
\r
37 #include "FreeRTOS.h"
\r
41 /* Demo program include files. */
\r
42 #include "IntSemTest.h"
\r
44 /*-----------------------------------------------------------*/
\r
46 /* The priorities of the test tasks. */
\r
47 #define intsemMASTER_PRIORITY ( tskIDLE_PRIORITY )
\r
48 #define intsemSLAVE_PRIORITY ( tskIDLE_PRIORITY + 1 )
\r
50 /* The rate at which the tick hook will give the mutex. */
\r
51 #define intsemINTERRUPT_MUTEX_GIVE_PERIOD_MS ( 100 )
\r
53 /* A block time of 0 means 'don't block'. */
\r
54 #define intsemNO_BLOCK 0
\r
56 /* The maximum count value for the counting semaphore given from an
\r
58 #define intsemMAX_COUNT 3
\r
60 /*-----------------------------------------------------------*/
\r
63 * The master is a task that receives a mutex that is given from an interrupt -
\r
64 * although generally mutexes should not be used given in interrupts (and
\r
65 * definitely never taken in an interrupt) there are some circumstances when it
\r
68 * The slave task is just used by the master task to force priority inheritance
\r
69 * on a mutex that is shared between the master and the slave - which is a
\r
70 * separate mutex to that given by the interrupt.
\r
72 static void vInterruptMutexSlaveTask( void *pvParameters );
\r
73 static void vInterruptMutexMasterTask( void *pvParameters );
\r
76 * A test whereby the master takes the shared and interrupt mutexes in that
\r
77 * order, then gives them back in the same order, ensuring the priority
\r
78 * inheritance is behaving as expected at each step.
\r
80 static void prvTakeAndGiveInTheSameOrder( void );
\r
83 * A test whereby the master takes the shared and interrupt mutexes in that
\r
84 * order, then gives them back in the opposite order to which they were taken,
\r
85 * ensuring the priority inheritance is behaving as expected at each step.
\r
87 static void prvTakeAndGiveInTheOppositeOrder( void );
\r
90 * A simple task that interacts with an interrupt using a counting semaphore,
\r
91 * primarily for code coverage purposes.
\r
93 static void vInterruptCountingSemaphoreTask( void *pvParameters );
\r
95 /*-----------------------------------------------------------*/
\r
97 /* Flag that will be latched to pdTRUE should any unexpected behaviour be
\r
98 detected in any of the tasks. */
\r
99 static volatile BaseType_t xErrorDetected = pdFALSE;
\r
101 /* Counters that are incremented on each cycle of a test. This is used to
\r
102 detect a stalled task - a test that is no longer running. */
\r
103 static volatile uint32_t ulMasterLoops = 0, ulCountingSemaphoreLoops = 0;
\r
105 /* Handles of the test tasks that must be accessed from other test tasks. */
\r
106 static TaskHandle_t xSlaveHandle;
\r
108 /* A mutex which is given from an interrupt - although generally mutexes should
\r
109 not be used given in interrupts (and definitely never taken in an interrupt)
\r
110 there are some circumstances when it may be desirable. */
\r
111 static SemaphoreHandle_t xISRMutex = NULL;
\r
113 /* A counting semaphore which is given from an interrupt. */
\r
114 static SemaphoreHandle_t xISRCountingSemaphore = NULL;
\r
116 /* A mutex which is shared between the master and slave tasks - the master
\r
117 does both sharing of this mutex with the slave and receiving a mutex from the
\r
119 static SemaphoreHandle_t xMasterSlaveMutex = NULL;
\r
121 /* Flag that allows the master task to control when the interrupt gives or does
\r
122 not give the mutex. There is no mutual exclusion on this variable, but this is
\r
123 only test code and it should be fine in the 32=bit test environment. */
\r
124 static BaseType_t xOkToGiveMutex = pdFALSE, xOkToGiveCountingSemaphore = pdFALSE;
\r
126 /* Used to coordinate timing between tasks and the interrupt. */
\r
127 const TickType_t xInterruptGivePeriod = pdMS_TO_TICKS( intsemINTERRUPT_MUTEX_GIVE_PERIOD_MS );
\r
129 /*-----------------------------------------------------------*/
\r
131 void vStartInterruptSemaphoreTasks( void )
\r
133 /* Create the semaphores that are given from an interrupt. */
\r
134 xISRMutex = xSemaphoreCreateMutex();
\r
135 configASSERT( xISRMutex );
\r
136 xISRCountingSemaphore = xSemaphoreCreateCounting( intsemMAX_COUNT, 0 );
\r
137 configASSERT( xISRCountingSemaphore );
\r
139 /* Create the mutex that is shared between the master and slave tasks (the
\r
140 master receives a mutex from an interrupt and shares a mutex with the
\r
142 xMasterSlaveMutex = xSemaphoreCreateMutex();
\r
143 configASSERT( xMasterSlaveMutex );
\r
145 /* Create the tasks that share mutexes between then and with interrupts. */
\r
146 xTaskCreate( vInterruptMutexSlaveTask, "IntMuS", configMINIMAL_STACK_SIZE, NULL, intsemSLAVE_PRIORITY, &xSlaveHandle );
\r
147 xTaskCreate( vInterruptMutexMasterTask, "IntMuM", configMINIMAL_STACK_SIZE, NULL, intsemMASTER_PRIORITY, NULL );
\r
149 /* Create the task that blocks on the counting semaphore. */
\r
150 xTaskCreate( vInterruptCountingSemaphoreTask, "IntCnt", configMINIMAL_STACK_SIZE, NULL, tskIDLE_PRIORITY, NULL );
\r
152 /*-----------------------------------------------------------*/
\r
154 static void vInterruptMutexMasterTask( void *pvParameters )
\r
156 /* Just to avoid compiler warnings. */
\r
157 ( void ) pvParameters;
\r
161 prvTakeAndGiveInTheSameOrder();
\r
163 /* Ensure not to starve out other tests. */
\r
165 vTaskDelay( intsemINTERRUPT_MUTEX_GIVE_PERIOD_MS );
\r
167 prvTakeAndGiveInTheOppositeOrder();
\r
169 /* Ensure not to starve out other tests. */
\r
171 vTaskDelay( intsemINTERRUPT_MUTEX_GIVE_PERIOD_MS );
\r
174 /*-----------------------------------------------------------*/
\r
176 static void prvTakeAndGiveInTheSameOrder( void )
\r
178 /* Ensure the slave is suspended, and that this task is running at the
\r
179 lower priority as expected as the start conditions. */
\r
180 #if( INCLUDE_eTaskGetState == 1 )
\r
182 configASSERT( eTaskGetState( xSlaveHandle ) == eSuspended );
\r
184 #endif /* INCLUDE_eTaskGetState */
\r
186 if( uxTaskPriorityGet( NULL ) != intsemMASTER_PRIORITY )
\r
188 xErrorDetected = pdTRUE;
\r
191 /* Take the semaphore that is shared with the slave. */
\r
192 if( xSemaphoreTake( xMasterSlaveMutex, intsemNO_BLOCK ) != pdPASS )
\r
194 xErrorDetected = pdTRUE;
\r
197 /* This task now has the mutex. Unsuspend the slave so it too
\r
198 attempts to take the mutex. */
\r
199 vTaskResume( xSlaveHandle );
\r
201 /* The slave has the higher priority so should now have executed and
\r
202 blocked on the semaphore. */
\r
203 #if( INCLUDE_eTaskGetState == 1 )
\r
205 configASSERT( eTaskGetState( xSlaveHandle ) == eBlocked );
\r
207 #endif /* INCLUDE_eTaskGetState */
\r
209 /* This task should now have inherited the priority of the slave
\r
211 if( uxTaskPriorityGet( NULL ) != intsemSLAVE_PRIORITY )
\r
213 xErrorDetected = pdTRUE;
\r
216 /* Now wait a little longer than the time between ISR gives to also
\r
217 obtain the ISR mutex. */
\r
218 xOkToGiveMutex = pdTRUE;
\r
219 if( xSemaphoreTake( xISRMutex, ( xInterruptGivePeriod * 2 ) ) != pdPASS )
\r
221 xErrorDetected = pdTRUE;
\r
223 xOkToGiveMutex = pdFALSE;
\r
225 /* Attempting to take again immediately should fail as the mutex is
\r
227 if( xSemaphoreTake( xISRMutex, intsemNO_BLOCK ) != pdFAIL )
\r
229 xErrorDetected = pdTRUE;
\r
232 /* Should still be at the priority of the slave task. */
\r
233 if( uxTaskPriorityGet( NULL ) != intsemSLAVE_PRIORITY )
\r
235 xErrorDetected = pdTRUE;
\r
238 /* Give back the ISR semaphore to ensure the priority is not
\r
239 disinherited as the shared mutex (which the higher priority task is
\r
240 attempting to obtain) is still held. */
\r
241 if( xSemaphoreGive( xISRMutex ) != pdPASS )
\r
243 xErrorDetected = pdTRUE;
\r
246 if( uxTaskPriorityGet( NULL ) != intsemSLAVE_PRIORITY )
\r
248 xErrorDetected = pdTRUE;
\r
251 /* Finally give back the shared mutex. This time the higher priority
\r
252 task should run before this task runs again - so this task should have
\r
253 disinherited the priority and the higher priority task should be in the
\r
254 suspended state again. */
\r
255 if( xSemaphoreGive( xMasterSlaveMutex ) != pdPASS )
\r
257 xErrorDetected = pdTRUE;
\r
260 if( uxTaskPriorityGet( NULL ) != intsemMASTER_PRIORITY )
\r
262 xErrorDetected = pdTRUE;
\r
265 #if( INCLUDE_eTaskGetState == 1 )
\r
267 configASSERT( eTaskGetState( xSlaveHandle ) == eSuspended );
\r
269 #endif /* INCLUDE_eTaskGetState */
\r
271 /* Reset the mutex ready for the next round. */
\r
272 xQueueReset( xISRMutex );
\r
274 /*-----------------------------------------------------------*/
\r
276 static void prvTakeAndGiveInTheOppositeOrder( void )
\r
278 /* Ensure the slave is suspended, and that this task is running at the
\r
279 lower priority as expected as the start conditions. */
\r
280 #if( INCLUDE_eTaskGetState == 1 )
\r
282 configASSERT( eTaskGetState( xSlaveHandle ) == eSuspended );
\r
284 #endif /* INCLUDE_eTaskGetState */
\r
286 if( uxTaskPriorityGet( NULL ) != intsemMASTER_PRIORITY )
\r
288 xErrorDetected = pdTRUE;
\r
291 /* Take the semaphore that is shared with the slave. */
\r
292 if( xSemaphoreTake( xMasterSlaveMutex, intsemNO_BLOCK ) != pdPASS )
\r
294 xErrorDetected = pdTRUE;
\r
297 /* This task now has the mutex. Unsuspend the slave so it too
\r
298 attempts to take the mutex. */
\r
299 vTaskResume( xSlaveHandle );
\r
301 /* The slave has the higher priority so should now have executed and
\r
302 blocked on the semaphore. */
\r
303 #if( INCLUDE_eTaskGetState == 1 )
\r
305 configASSERT( eTaskGetState( xSlaveHandle ) == eBlocked );
\r
307 #endif /* INCLUDE_eTaskGetState */
\r
309 /* This task should now have inherited the priority of the slave
\r
311 if( uxTaskPriorityGet( NULL ) != intsemSLAVE_PRIORITY )
\r
313 xErrorDetected = pdTRUE;
\r
316 /* Now wait a little longer than the time between ISR gives to also
\r
317 obtain the ISR mutex. */
\r
318 xOkToGiveMutex = pdTRUE;
\r
319 if( xSemaphoreTake( xISRMutex, ( xInterruptGivePeriod * 2 ) ) != pdPASS )
\r
321 xErrorDetected = pdTRUE;
\r
323 xOkToGiveMutex = pdFALSE;
\r
325 /* Attempting to take again immediately should fail as the mutex is
\r
327 if( xSemaphoreTake( xISRMutex, intsemNO_BLOCK ) != pdFAIL )
\r
329 xErrorDetected = pdTRUE;
\r
332 /* Should still be at the priority of the slave task. */
\r
333 if( uxTaskPriorityGet( NULL ) != intsemSLAVE_PRIORITY )
\r
335 xErrorDetected = pdTRUE;
\r
338 /* Give back the shared semaphore to ensure the priority is not disinherited
\r
339 as the ISR mutex is still held. The higher priority slave task should run
\r
340 before this task runs again. */
\r
341 if( xSemaphoreGive( xMasterSlaveMutex ) != pdPASS )
\r
343 xErrorDetected = pdTRUE;
\r
346 /* Should still be at the priority of the slave task as this task still
\r
347 holds one semaphore (this is a simplification in the priority inheritance
\r
349 if( uxTaskPriorityGet( NULL ) != intsemSLAVE_PRIORITY )
\r
351 xErrorDetected = pdTRUE;
\r
354 /* Give back the ISR semaphore, which should result in the priority being
\r
355 disinherited as it was the last mutex held. */
\r
356 if( xSemaphoreGive( xISRMutex ) != pdPASS )
\r
358 xErrorDetected = pdTRUE;
\r
361 if( uxTaskPriorityGet( NULL ) != intsemMASTER_PRIORITY )
\r
363 xErrorDetected = pdTRUE;
\r
366 /* Reset the mutex ready for the next round. */
\r
367 xQueueReset( xISRMutex );
\r
369 /*-----------------------------------------------------------*/
\r
371 static void vInterruptMutexSlaveTask( void *pvParameters )
\r
373 /* Just to avoid compiler warnings. */
\r
374 ( void ) pvParameters;
\r
378 /* This task starts by suspending itself so when it executes can be
\r
379 controlled by the master task. */
\r
380 vTaskSuspend( NULL );
\r
382 /* This task will execute when the master task already holds the mutex.
\r
383 Attempting to take the mutex will place this task in the Blocked
\r
385 if( xSemaphoreTake( xMasterSlaveMutex, portMAX_DELAY ) != pdPASS )
\r
387 xErrorDetected = pdTRUE;
\r
390 if( xSemaphoreGive( xMasterSlaveMutex ) != pdPASS )
\r
392 xErrorDetected = pdTRUE;
\r
396 /*-----------------------------------------------------------*/
\r
398 static void vInterruptCountingSemaphoreTask( void *pvParameters )
\r
401 const TickType_t xDelay = pdMS_TO_TICKS( intsemINTERRUPT_MUTEX_GIVE_PERIOD_MS ) * ( intsemMAX_COUNT + 1 );
\r
403 ( void ) pvParameters;
\r
407 /* Expect to start with the counting semaphore empty. */
\r
408 if( uxQueueMessagesWaiting( ( QueueHandle_t ) xISRCountingSemaphore ) != 0 )
\r
410 xErrorDetected = pdTRUE;
\r
413 /* Wait until it is expected that the interrupt will have filled the
\r
414 counting semaphore. */
\r
415 xOkToGiveCountingSemaphore = pdTRUE;
\r
416 vTaskDelay( xDelay );
\r
417 xOkToGiveCountingSemaphore = pdFALSE;
\r
419 /* Now it is expected that the counting semaphore is full. */
\r
420 if( uxQueueMessagesWaiting( ( QueueHandle_t ) xISRCountingSemaphore ) != intsemMAX_COUNT )
\r
422 xErrorDetected = pdTRUE;
\r
425 if( uxQueueSpacesAvailable( ( QueueHandle_t ) xISRCountingSemaphore ) != 0 )
\r
427 xErrorDetected = pdTRUE;
\r
430 ulCountingSemaphoreLoops++;
\r
432 /* Expect to be able to take the counting semaphore intsemMAX_COUNT
\r
433 times. A block time of 0 is used as the semaphore should already be
\r
436 while( xSemaphoreTake( xISRCountingSemaphore, 0 ) == pdPASS )
\r
441 if( xCount != intsemMAX_COUNT )
\r
443 xErrorDetected = pdTRUE;
\r
446 /* Now raise the priority of this task so it runs immediately that the
\r
447 semaphore is given from the interrupt. */
\r
448 vTaskPrioritySet( NULL, configMAX_PRIORITIES - 1 );
\r
450 /* Block to wait for the semaphore to be given from the interrupt. */
\r
451 xOkToGiveCountingSemaphore = pdTRUE;
\r
452 xSemaphoreTake( xISRCountingSemaphore, portMAX_DELAY );
\r
453 xSemaphoreTake( xISRCountingSemaphore, portMAX_DELAY );
\r
454 xOkToGiveCountingSemaphore = pdFALSE;
\r
456 /* Reset the priority so as not to disturbe other tests too much. */
\r
457 vTaskPrioritySet( NULL, tskIDLE_PRIORITY );
\r
459 ulCountingSemaphoreLoops++;
\r
462 /*-----------------------------------------------------------*/
\r
464 void vInterruptSemaphorePeriodicTest( void )
\r
466 static TickType_t xLastGiveTime = 0;
\r
467 BaseType_t xHigherPriorityTaskWoken = pdFALSE;
\r
468 TickType_t xTimeNow;
\r
470 /* No mutual exclusion on xOkToGiveMutex, but this is only test code (and
\r
471 only executed on a 32-bit architecture) so ignore that in this case. */
\r
472 xTimeNow = xTaskGetTickCountFromISR();
\r
473 if( ( ( TickType_t ) ( xTimeNow - xLastGiveTime ) ) >= pdMS_TO_TICKS( intsemINTERRUPT_MUTEX_GIVE_PERIOD_MS ) )
\r
475 configASSERT( xISRMutex );
\r
476 if( xOkToGiveMutex != pdFALSE )
\r
478 /* Null is used as the second parameter in this give, and non-NULL
\r
479 in the other gives for code coverage reasons. */
\r
480 xSemaphoreGiveFromISR( xISRMutex, NULL );
\r
482 /* Second give attempt should fail. */
\r
483 configASSERT( xSemaphoreGiveFromISR( xISRMutex, &xHigherPriorityTaskWoken ) == pdFAIL );
\r
486 if( xOkToGiveCountingSemaphore != pdFALSE )
\r
488 xSemaphoreGiveFromISR( xISRCountingSemaphore, &xHigherPriorityTaskWoken );
\r
490 xLastGiveTime = xTimeNow;
\r
493 /* Remove compiler warnings about the value being set but not used. */
\r
494 ( void ) xHigherPriorityTaskWoken;
\r
496 /*-----------------------------------------------------------*/
\r
498 /* This is called to check that all the created tasks are still running. */
\r
499 BaseType_t xAreInterruptSemaphoreTasksStillRunning( void )
\r
501 static uint32_t ulLastMasterLoopCounter = 0, ulLastCountingSemaphoreLoops = 0;
\r
503 /* If the demo tasks are running then it is expected that the loop counters
\r
504 will have changed since this function was last called. */
\r
505 if( ulLastMasterLoopCounter == ulMasterLoops )
\r
507 xErrorDetected = pdTRUE;
\r
510 ulLastMasterLoopCounter = ulMasterLoops;
\r
512 if( ulLastCountingSemaphoreLoops == ulCountingSemaphoreLoops )
\r
514 xErrorDetected = pdTRUE;
\r
517 ulLastCountingSemaphoreLoops = ulCountingSemaphoreLoops++;
\r
519 /* Errors detected in the task itself will have latched xErrorDetected
\r
522 return ( BaseType_t ) !xErrorDetected;
\r