00001 /* 00002 FreeRTOS V6.0.0 - Copyright (C) 2009 Real Time Engineers Ltd. 00003 00004 *************************************************************************** 00005 * * 00006 * If you are: * 00007 * * 00008 * + New to FreeRTOS, * 00009 * + Wanting to learn FreeRTOS or multitasking in general quickly * 00010 * + Looking for basic training, * 00011 * + Wanting to improve your FreeRTOS skills and productivity * 00012 * * 00013 * then take a look at the FreeRTOS eBook * 00014 * * 00015 * "Using the FreeRTOS Real Time Kernel - a Practical Guide" * 00016 * http://www.FreeRTOS.org/Documentation * 00017 * * 00018 * A pdf reference manual is also available. Both are usually delivered * 00019 * to your inbox within 20 minutes to two hours when purchased between 8am * 00020 * and 8pm GMT (although please allow up to 24 hours in case of * 00021 * exceptional circumstances). Thank you for your support! * 00022 * * 00023 *************************************************************************** 00024 00025 This file is part of the FreeRTOS distribution. 00026 00027 FreeRTOS is free software; you can redistribute it and/or modify it under 00028 the terms of the GNU General Public License (version 2) as published by the 00029 Free Software Foundation AND MODIFIED BY the FreeRTOS exception. 00030 ***NOTE*** The exception to the GPL is included to allow you to distribute 00031 a combined work that includes FreeRTOS without being obliged to provide the 00032 source code for proprietary components outside of the FreeRTOS kernel. 00033 FreeRTOS is distributed in the hope that it will be useful, but WITHOUT 00034 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 00035 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for 00036 more details. You should have received a copy of the GNU General Public 00037 License and the FreeRTOS license exception along with FreeRTOS; if not it 00038 can be viewed here: http://www.freertos.org/a00114.html and also obtained 00039 by writing to Richard Barry, contact details for whom are available on the 00040 FreeRTOS WEB site. 00041 00042 1 tab == 4 spaces! 00043 00044 http://www.FreeRTOS.org - Documentation, latest information, license and 00045 contact details. 00046 00047 http://www.SafeRTOS.com - A version that is certified for use in safety 00048 critical systems. 00049 00050 http://www.OpenRTOS.com - Commercial support, development, porting, 00051 licensing and training services. 00052 */ 00053 00054 /* 00055 The tasks defined on this page demonstrate the use of recursive mutexes. 00056 00057 For recursive mutex functionality the created mutex should be created using 00058 xSemaphoreCreateRecursiveMutex(), then be manipulated 00059 using the xSemaphoreTakeRecursive() and xSemaphoreGiveRecursive() API 00060 functions. 00061 00062 This demo creates three tasks all of which access the same recursive mutex: 00063 00064 prvRecursiveMutexControllingTask() has the highest priority so executes 00065 first and grabs the mutex. It then performs some recursive accesses - 00066 between each of which it sleeps for a short period to let the lower 00067 priority tasks execute. When it has completed its demo functionality 00068 it gives the mutex back before suspending itself. 00069 00070 prvRecursiveMutexBlockingTask() attempts to access the mutex by performing 00071 a blocking 'take'. The blocking task has a lower priority than the 00072 controlling task so by the time it executes the mutex has already been 00073 taken by the controlling task, causing the blocking task to block. It 00074 does not unblock until the controlling task has given the mutex back, 00075 and it does not actually run until the controlling task has suspended 00076 itself (due to the relative priorities). When it eventually does obtain 00077 the mutex all it does is give the mutex back prior to also suspending 00078 itself. At this point both the controlling task and the blocking task are 00079 suspended. 00080 00081 prvRecursiveMutexPollingTask() runs at the idle priority. It spins round 00082 a tight loop attempting to obtain the mutex with a non-blocking call. As 00083 the lowest priority task it will not successfully obtain the mutex until 00084 both the controlling and blocking tasks are suspended. Once it eventually 00085 does obtain the mutex it first unsuspends both the controlling task and 00086 blocking task prior to giving the mutex back - resulting in the polling 00087 task temporarily inheriting the controlling tasks priority. 00088 */ 00089 00090 /* Scheduler include files. */ 00091 #include "FreeRTOS.h" 00092 #include "task.h" 00093 #include "semphr.h" 00094 00095 /* Demo app include files. */ 00096 #include "recmutex.h" 00097 00098 /* Priorities assigned to the three tasks. */ 00099 #define recmuCONTROLLING_TASK_PRIORITY ( tskIDLE_PRIORITY + 2 ) 00100 #define recmuBLOCKING_TASK_PRIORITY ( tskIDLE_PRIORITY + 1 ) 00101 #define recmuPOLLING_TASK_PRIORITY ( tskIDLE_PRIORITY + 0 ) 00102 00103 /* The recursive call depth. */ 00104 #define recmuMAX_COUNT ( 10 ) 00105 00106 /* Misc. */ 00107 #define recmuSHORT_DELAY ( 20 / portTICK_RATE_MS ) 00108 #define recmuNO_DELAY ( ( portTickType ) 0 ) 00109 #define recmuTWO_TICK_DELAY ( ( portTickType ) 2 ) 00110 00111 /* The three tasks as described at the top of this file. */ 00112 static void prvRecursiveMutexControllingTask( void *pvParameters ); 00113 static void prvRecursiveMutexBlockingTask( void *pvParameters ); 00114 static void prvRecursiveMutexPollingTask( void *pvParameters ); 00115 00116 /* The mutex used by the demo. */ 00117 static xSemaphoreHandle xMutex; 00118 00119 /* Variables used to detect and latch errors. */ 00120 static volatile portBASE_TYPE xErrorOccurred = pdFALSE, xControllingIsSuspended = pdFALSE, xBlockingIsSuspended = pdFALSE; 00121 static volatile unsigned portBASE_TYPE uxControllingCycles = 0, uxBlockingCycles, uxPollingCycles = 0; 00122 00123 /* Handles of the two higher priority tasks, required so they can be resumed 00124 (unsuspended). */ 00125 static xTaskHandle xControllingTaskHandle, xBlockingTaskHandle; 00126 00127 /*-----------------------------------------------------------*/ 00128 00129 void vStartRecursiveMutexTasks( void ) 00130 { 00131 /* Just creates the mutex and the three tasks. */ 00132 00133 xMutex = xSemaphoreCreateRecursiveMutex(); 00134 00135 /* vQueueAddToRegistry() adds the mutex to the registry, if one is 00136 in use. The registry is provided as a means for kernel aware 00137 debuggers to locate mutex and has no purpose if a kernel aware debugger 00138 is not being used. The call to vQueueAddToRegistry() will be removed 00139 by the pre-processor if configQUEUE_REGISTRY_SIZE is not defined or is 00140 defined to be less than 1. */ 00141 vQueueAddToRegistry( ( xQueueHandle ) xMutex, ( signed portCHAR * ) "Recursive_Mutex" ); 00142 00143 00144 if( xMutex != NULL ) 00145 { 00146 xTaskCreate( prvRecursiveMutexControllingTask, ( signed portCHAR * ) "Rec1", configMINIMAL_STACK_SIZE, NULL, recmuCONTROLLING_TASK_PRIORITY, &xControllingTaskHandle ); 00147 xTaskCreate( prvRecursiveMutexBlockingTask, ( signed portCHAR * ) "Rec2", configMINIMAL_STACK_SIZE, NULL, recmuBLOCKING_TASK_PRIORITY, &xBlockingTaskHandle ); 00148 xTaskCreate( prvRecursiveMutexPollingTask, ( signed portCHAR * ) "Rec3", configMINIMAL_STACK_SIZE, NULL, recmuPOLLING_TASK_PRIORITY, NULL ); 00149 } 00150 } 00151 /*-----------------------------------------------------------*/ 00152 00153 static void prvRecursiveMutexControllingTask( void *pvParameters ) 00154 { 00155 unsigned portBASE_TYPE ux; 00156 00157 /* Just to remove compiler warning. */ 00158 ( void ) pvParameters; 00159 00160 for( ;; ) 00161 { 00162 /* Should not be able to 'give' the mutex, as we have not yet 'taken' 00163 it. */ 00164 if( xSemaphoreGiveRecursive( xMutex ) == pdPASS ) 00165 { 00166 xErrorOccurred = pdTRUE; 00167 } 00168 00169 for( ux = 0; ux < recmuMAX_COUNT; ux++ ) 00170 { 00171 /* We should now be able to take the mutex as many times as 00172 we like. A one tick delay is used so the polling task will 00173 inherit our priority on all but the first cycle of this task. 00174 If we did not block attempting to receive the mutex then no 00175 priority inheritance would occur. */ 00176 if( xSemaphoreTakeRecursive( xMutex, recmuTWO_TICK_DELAY ) != pdPASS ) 00177 { 00178 xErrorOccurred = pdTRUE; 00179 } 00180 00181 /* Ensure the other task attempting to access the mutex (and the 00182 other demo tasks) are able to execute. */ 00183 vTaskDelay( recmuSHORT_DELAY ); 00184 } 00185 00186 /* For each time we took the mutex, give it back. */ 00187 for( ux = 0; ux < recmuMAX_COUNT; ux++ ) 00188 { 00189 /* Ensure the other task attempting to access the mutex (and the 00190 other demo tasks) are able to execute. */ 00191 vTaskDelay( recmuSHORT_DELAY ); 00192 00193 /* We should now be able to give the mutex as many times as we 00194 took it. */ 00195 if( xSemaphoreGiveRecursive( xMutex ) != pdPASS ) 00196 { 00197 xErrorOccurred = pdTRUE; 00198 } 00199 } 00200 00201 /* Having given it back the same number of times as it was taken, we 00202 should no longer be the mutex owner, so the next give sh ould fail. */ 00203 if( xSemaphoreGiveRecursive( xMutex ) == pdPASS ) 00204 { 00205 xErrorOccurred = pdTRUE; 00206 } 00207 00208 /* Keep count of the number of cycles this task has performed so a 00209 stall can be detected. */ 00210 uxControllingCycles++; 00211 00212 /* Suspend ourselves to the blocking task can execute. */ 00213 xControllingIsSuspended = pdTRUE; 00214 vTaskSuspend( NULL ); 00215 xControllingIsSuspended = pdFALSE; 00216 } 00217 } 00218 /*-----------------------------------------------------------*/ 00219 00220 static void prvRecursiveMutexBlockingTask( void *pvParameters ) 00221 { 00222 /* Just to remove compiler warning. */ 00223 ( void ) pvParameters; 00224 00225 for( ;; ) 00226 { 00227 /* Attempt to obtain the mutex. We should block until the 00228 controlling task has given up the mutex, and not actually execute 00229 past this call until the controlling task is suspended. */ 00230 if( xSemaphoreTakeRecursive( xMutex, portMAX_DELAY ) == pdPASS ) 00231 { 00232 if( xControllingIsSuspended != pdTRUE ) 00233 { 00234 /* Did not expect to execute until the controlling task was 00235 suspended. */ 00236 xErrorOccurred = pdTRUE; 00237 } 00238 else 00239 { 00240 /* Give the mutex back before suspending ourselves to allow 00241 the polling task to obtain the mutex. */ 00242 if( xSemaphoreGiveRecursive( xMutex ) != pdPASS ) 00243 { 00244 xErrorOccurred = pdTRUE; 00245 } 00246 00247 xBlockingIsSuspended = pdTRUE; 00248 vTaskSuspend( NULL ); 00249 xBlockingIsSuspended = pdFALSE; 00250 } 00251 } 00252 else 00253 { 00254 /* We should not leave the xSemaphoreTakeRecursive() function 00255 until the mutex was obtained. */ 00256 xErrorOccurred = pdTRUE; 00257 } 00258 00259 /* The controlling and blocking tasks should be in lock step. */ 00260 if( uxControllingCycles != ( uxBlockingCycles + 1 ) ) 00261 { 00262 xErrorOccurred = pdTRUE; 00263 } 00264 00265 /* Keep count of the number of cycles this task has performed so a 00266 stall can be detected. */ 00267 uxBlockingCycles++; 00268 } 00269 } 00270 /*-----------------------------------------------------------*/ 00271 00272 static void prvRecursiveMutexPollingTask( void *pvParameters ) 00273 { 00274 /* Just to remove compiler warning. */ 00275 ( void ) pvParameters; 00276 00277 for( ;; ) 00278 { 00279 /* Keep attempting to obtain the mutex. We should only obtain it when 00280 the blocking task has suspended itself. */ 00281 if( xSemaphoreTakeRecursive( xMutex, recmuNO_DELAY ) == pdPASS ) 00282 { 00283 /* Is the blocking task suspended? */ 00284 if( xBlockingIsSuspended != pdTRUE ) 00285 { 00286 xErrorOccurred = pdTRUE; 00287 } 00288 else 00289 { 00290 /* Keep count of the number of cycles this task has performed so 00291 a stall can be detected. */ 00292 uxPollingCycles++; 00293 00294 /* We can resume the other tasks here even though they have a 00295 higher priority than the polling task. When they execute they 00296 will attempt to obtain the mutex but fail because the polling 00297 task is still the mutex holder. The polling task (this task) 00298 will then inherit the higher priority. */ 00299 vTaskResume( xBlockingTaskHandle ); 00300 vTaskResume( xControllingTaskHandle ); 00301 00302 /* Release the mutex, disinheriting the higher priority again. */ 00303 if( xSemaphoreGiveRecursive( xMutex ) != pdPASS ) 00304 { 00305 xErrorOccurred = pdTRUE; 00306 } 00307 } 00308 } 00309 00310 #if configUSE_PREEMPTION == 0 00311 { 00312 taskYIELD(); 00313 } 00314 #endif 00315 } 00316 } 00317 /*-----------------------------------------------------------*/ 00318 00319 /* This is called to check that all the created tasks are still running. */ 00320 portBASE_TYPE xAreRecursiveMutexTasksStillRunning( void ) 00321 { 00322 portBASE_TYPE xReturn; 00323 static unsigned portBASE_TYPE uxLastControllingCycles = 0, uxLastBlockingCycles = 0, uxLastPollingCycles = 0; 00324 00325 /* Is the controlling task still cycling? */ 00326 if( uxLastControllingCycles == uxControllingCycles ) 00327 { 00328 xErrorOccurred = pdTRUE; 00329 } 00330 else 00331 { 00332 uxLastControllingCycles = uxControllingCycles; 00333 } 00334 00335 /* Is the blocking task still cycling? */ 00336 if( uxLastBlockingCycles == uxBlockingCycles ) 00337 { 00338 xErrorOccurred = pdTRUE; 00339 } 00340 else 00341 { 00342 uxLastBlockingCycles = uxBlockingCycles; 00343 } 00344 00345 /* Is the polling task still cycling? */ 00346 if( uxLastPollingCycles == uxPollingCycles ) 00347 { 00348 xErrorOccurred = pdTRUE; 00349 } 00350 else 00351 { 00352 uxLastPollingCycles = uxPollingCycles; 00353 } 00354 00355 if( xErrorOccurred == pdTRUE ) 00356 { 00357 xReturn = pdFAIL; 00358 } 00359 else 00360 { 00361 xReturn = pdTRUE; 00362 } 00363 00364 return xReturn; 00365 } 00366 00367 00368 00369