/* * FreeRTOS V202212.00 * Copyright (C) 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved. * * Permission is hereby granted, free of charge, to any person obtaining a copy of * this software and associated documentation files (the "Software"), to deal in * the Software without restriction, including without limitation the rights to * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of * the Software, and to permit persons to whom the Software is furnished to do so, * subject to the following conditions: * * The above copyright notice and this permission notice shall be included in all * copies or substantial portions of the Software. * * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. * * https://www.FreeRTOS.org * https://github.com/FreeRTOS * */ /* * The tasks defined on this page demonstrate the use of recursive mutexes. * * For recursive mutex functionality the created mutex should be created using * xSemaphoreCreateRecursiveMutex(), then be manipulated * using the xSemaphoreTakeRecursive() and xSemaphoreGiveRecursive() API * functions. * * This demo creates three tasks all of which access the same recursive mutex: * * prvRecursiveMutexControllingTask() has the highest priority so executes * first and grabs the mutex. It then performs some recursive accesses - * between each of which it sleeps for a short period to let the lower * priority tasks execute. When it has completed its demo functionality * it gives the mutex back before suspending itself. * * prvRecursiveMutexBlockingTask() attempts to access the mutex by performing * a blocking 'take'. The blocking task has a lower priority than the * controlling task so by the time it executes the mutex has already been * taken by the controlling task, causing the blocking task to block. It * does not unblock until the controlling task has given the mutex back, * and it does not actually run until the controlling task has suspended * itself (due to the relative priorities). When it eventually does obtain * the mutex all it does is give the mutex back prior to also suspending * itself. At this point both the controlling task and the blocking task are * suspended. * * prvRecursiveMutexPollingTask() runs at the idle priority. It spins round * a tight loop attempting to obtain the mutex with a non-blocking call. As * the lowest priority task it will not successfully obtain the mutex until * both the controlling and blocking tasks are suspended. Once it eventually * does obtain the mutex it first unsuspends both the controlling task and * blocking task prior to giving the mutex back - resulting in the polling * task temporarily inheriting the controlling tasks priority. */ /* Scheduler include files. */ #include "FreeRTOS.h" #include "task.h" #include "semphr.h" /* Demo app include files. */ #include "recmutex.h" /* Priorities assigned to the three tasks. recmuCONTROLLING_TASK_PRIORITY can * be overridden by a definition in FreeRTOSConfig.h. */ #ifndef recmuCONTROLLING_TASK_PRIORITY #define recmuCONTROLLING_TASK_PRIORITY ( tskIDLE_PRIORITY + 2 ) #endif #define recmuBLOCKING_TASK_PRIORITY ( tskIDLE_PRIORITY + 1 ) #define recmuPOLLING_TASK_PRIORITY ( tskIDLE_PRIORITY + 0 ) /* The recursive call depth. */ #define recmuMAX_COUNT ( 10 ) /* Misc. */ #define recmuSHORT_DELAY ( pdMS_TO_TICKS( 20 ) ) #define recmuNO_DELAY ( ( TickType_t ) 0 ) #define recmu15ms_DELAY ( pdMS_TO_TICKS( 15 ) ) #ifndef recmuRECURSIVE_MUTEX_TEST_TASK_STACK_SIZE #define recmuRECURSIVE_MUTEX_TEST_TASK_STACK_SIZE configMINIMAL_STACK_SIZE #endif /* The three tasks as described at the top of this file. */ static void prvRecursiveMutexControllingTask( void * pvParameters ); static void prvRecursiveMutexBlockingTask( void * pvParameters ); static void prvRecursiveMutexPollingTask( void * pvParameters ); /* The mutex used by the demo. */ static SemaphoreHandle_t xMutex; /* Variables used to detect and latch errors. */ static volatile BaseType_t xErrorOccurred = pdFALSE, xControllingIsSuspended = pdFALSE, xBlockingIsSuspended = pdFALSE; static volatile UBaseType_t uxControllingCycles = 0, uxBlockingCycles = 0, uxPollingCycles = 0; /* Handles of the two higher priority tasks, required so they can be resumed * (unsuspended). */ static TaskHandle_t xControllingTaskHandle, xBlockingTaskHandle; /*-----------------------------------------------------------*/ void vStartRecursiveMutexTasks( void ) { /* Just creates the mutex and the three tasks. */ xMutex = xSemaphoreCreateRecursiveMutex(); if( xMutex != NULL ) { /* vQueueAddToRegistry() adds the mutex to the registry, if one is * in use. The registry is provided as a means for kernel aware * debuggers to locate mutex and has no purpose if a kernel aware debugger * is not being used. The call to vQueueAddToRegistry() will be removed * by the pre-processor if configQUEUE_REGISTRY_SIZE is not defined or is * defined to be less than 1. */ vQueueAddToRegistry( ( QueueHandle_t ) xMutex, "Recursive_Mutex" ); xTaskCreate( prvRecursiveMutexControllingTask, "Rec1", recmuRECURSIVE_MUTEX_TEST_TASK_STACK_SIZE, NULL, recmuCONTROLLING_TASK_PRIORITY, &xControllingTaskHandle ); xTaskCreate( prvRecursiveMutexBlockingTask, "Rec2", recmuRECURSIVE_MUTEX_TEST_TASK_STACK_SIZE, NULL, recmuBLOCKING_TASK_PRIORITY, &xBlockingTaskHandle ); xTaskCreate( prvRecursiveMutexPollingTask, "Rec3", recmuRECURSIVE_MUTEX_TEST_TASK_STACK_SIZE, NULL, recmuPOLLING_TASK_PRIORITY, NULL ); } } /*-----------------------------------------------------------*/ static void prvRecursiveMutexControllingTask( void * pvParameters ) { UBaseType_t ux; /* Just to remove compiler warning. */ ( void ) pvParameters; for( ; ; ) { /* Should not be able to 'give' the mutex, as we have not yet 'taken' * it. The first time through, the mutex will not have been used yet, * subsequent times through, at this point the mutex will be held by the * polling task. */ if( xSemaphoreGiveRecursive( xMutex ) == pdPASS ) { xErrorOccurred = __LINE__; } for( ux = 0; ux < recmuMAX_COUNT; ux++ ) { /* We should now be able to take the mutex as many times as * we like. * * The first time through the mutex will be immediately available, on * subsequent times through the mutex will be held by the polling task * at this point and this Take will cause the polling task to inherit * the priority of this task. In this case the block time must be * long enough to ensure the polling task will execute again before the * block time expires. If the block time does expire then the error * flag will be set here. */ if( xSemaphoreTakeRecursive( xMutex, recmu15ms_DELAY ) != pdPASS ) { xErrorOccurred = __LINE__; } /* Ensure the other task attempting to access the mutex (and the * other demo tasks) are able to execute to ensure they either block * (where a block time is specified) or return an error (where no * block time is specified) as the mutex is held by this task. */ vTaskDelay( recmuSHORT_DELAY ); } /* For each time we took the mutex, give it back. */ for( ux = 0; ux < recmuMAX_COUNT; ux++ ) { /* Ensure the other task attempting to access the mutex (and the * other demo tasks) are able to execute. */ vTaskDelay( recmuSHORT_DELAY ); /* We should now be able to give the mutex as many times as we * took it. When the mutex is available again the Blocking task * should be unblocked but not run because it has a lower priority * than this task. The polling task should also not run at this point * as it too has a lower priority than this task. */ if( xSemaphoreGiveRecursive( xMutex ) != pdPASS ) { xErrorOccurred = __LINE__; } #if ( configUSE_PREEMPTION == 0 ) taskYIELD(); #endif } /* Having given it back the same number of times as it was taken, we * should no longer be the mutex owner, so the next give should fail. */ if( xSemaphoreGiveRecursive( xMutex ) == pdPASS ) { xErrorOccurred = __LINE__; } /* Keep count of the number of cycles this task has performed so a * stall can be detected. */ uxControllingCycles++; /* Suspend ourselves so the blocking task can execute. */ xControllingIsSuspended = pdTRUE; vTaskSuspend( NULL ); xControllingIsSuspended = pdFALSE; } } /*-----------------------------------------------------------*/ static void prvRecursiveMutexBlockingTask( void * pvParameters ) { /* Just to remove compiler warning. */ ( void ) pvParameters; for( ; ; ) { /* This task will run while the controlling task is blocked, and the * controlling task will block only once it has the mutex - therefore * this call should block until the controlling task has given up the * mutex, and not actually execute past this call until the controlling * task is suspended. portMAX_DELAY - 1 is used instead of portMAX_DELAY * to ensure the task's state is reported as Blocked and not Suspended in * a later call to configASSERT() (within the polling task). */ if( xSemaphoreTakeRecursive( xMutex, ( portMAX_DELAY - 1 ) ) == pdPASS ) { if( xControllingIsSuspended != pdTRUE ) { /* Did not expect to execute until the controlling task was * suspended. */ xErrorOccurred = __LINE__; } else { /* Give the mutex back before suspending ourselves to allow * the polling task to obtain the mutex. */ if( xSemaphoreGiveRecursive( xMutex ) != pdPASS ) { xErrorOccurred = __LINE__; } xBlockingIsSuspended = pdTRUE; vTaskSuspend( NULL ); xBlockingIsSuspended = pdFALSE; } } else { /* We should not leave the xSemaphoreTakeRecursive() function * until the mutex was obtained. */ xErrorOccurred = __LINE__; } /* The controlling and blocking tasks should be in lock step. */ if( uxControllingCycles != ( UBaseType_t ) ( uxBlockingCycles + 1 ) ) { xErrorOccurred = __LINE__; } /* Keep count of the number of cycles this task has performed so a * stall can be detected. */ uxBlockingCycles++; } } /*-----------------------------------------------------------*/ static void prvRecursiveMutexPollingTask( void * pvParameters ) { /* Just to remove compiler warning. */ ( void ) pvParameters; for( ; ; ) { /* Keep attempting to obtain the mutex. It should only be obtained when * the blocking task has suspended itself, which in turn should only * happen when the controlling task is also suspended. */ if( xSemaphoreTakeRecursive( xMutex, recmuNO_DELAY ) == pdPASS ) { #if ( INCLUDE_eTaskGetState == 1 ) { configASSERT( eTaskGetState( xControllingTaskHandle ) == eSuspended ); configASSERT( eTaskGetState( xBlockingTaskHandle ) == eSuspended ); } #endif /* INCLUDE_eTaskGetState */ /* Is the blocking task suspended? */ if( ( xBlockingIsSuspended != pdTRUE ) || ( xControllingIsSuspended != pdTRUE ) ) { xErrorOccurred = __LINE__; } else { /* Keep count of the number of cycles this task has performed * so a stall can be detected. */ uxPollingCycles++; /* We can resume the other tasks here even though they have a * higher priority than the polling task. When they execute they * will attempt to obtain the mutex but fail because the polling * task is still the mutex holder. The polling task (this task) * will then inherit the higher priority. The Blocking task will * block indefinitely when it attempts to obtain the mutex, the * Controlling task will only block for a fixed period and an * error will be latched if the polling task has not returned the * mutex by the time this fixed period has expired. */ vTaskResume( xBlockingTaskHandle ); #if ( configUSE_PREEMPTION == 0 ) taskYIELD(); #endif vTaskResume( xControllingTaskHandle ); #if ( configUSE_PREEMPTION == 0 ) taskYIELD(); #endif /* The other two tasks should now have executed and no longer * be suspended. */ if( ( xBlockingIsSuspended == pdTRUE ) || ( xControllingIsSuspended == pdTRUE ) ) { xErrorOccurred = __LINE__; } #if ( INCLUDE_uxTaskPriorityGet == 1 ) { /* Check priority inherited. */ configASSERT( uxTaskPriorityGet( NULL ) == recmuCONTROLLING_TASK_PRIORITY ); } #endif /* INCLUDE_uxTaskPriorityGet */ #if ( INCLUDE_eTaskGetState == 1 ) { configASSERT( eTaskGetState( xControllingTaskHandle ) == eBlocked ); configASSERT( eTaskGetState( xBlockingTaskHandle ) == eBlocked ); } #endif /* INCLUDE_eTaskGetState */ /* Release the mutex, disinheriting the higher priority again. */ if( xSemaphoreGiveRecursive( xMutex ) != pdPASS ) { xErrorOccurred = __LINE__; } #if ( INCLUDE_uxTaskPriorityGet == 1 ) { /* Check priority disinherited. */ configASSERT( uxTaskPriorityGet( NULL ) == recmuPOLLING_TASK_PRIORITY ); } #endif /* INCLUDE_uxTaskPriorityGet */ } } #if configUSE_PREEMPTION == 0 { taskYIELD(); } #endif } } /*-----------------------------------------------------------*/ /* This is called to check that all the created tasks are still running. */ BaseType_t xAreRecursiveMutexTasksStillRunning( void ) { BaseType_t xReturn; static UBaseType_t uxLastControllingCycles = 0, uxLastBlockingCycles = 0, uxLastPollingCycles = 0; /* Is the controlling task still cycling? */ if( uxLastControllingCycles == uxControllingCycles ) { xErrorOccurred = __LINE__; } else { uxLastControllingCycles = uxControllingCycles; } /* Is the blocking task still cycling? */ if( uxLastBlockingCycles == uxBlockingCycles ) { xErrorOccurred = __LINE__; } else { uxLastBlockingCycles = uxBlockingCycles; } /* Is the polling task still cycling? */ if( uxLastPollingCycles == uxPollingCycles ) { xErrorOccurred = __LINE__; } else { uxLastPollingCycles = uxPollingCycles; } if( xErrorOccurred != pdFALSE ) { xReturn = pdFAIL; } else { xReturn = pdPASS; } return xReturn; }