FreeRTOS Real Time Operating System, Modified from Kenji Arai's initial port. See freertos.org for full documentation.

Fork of FreeRTOS_on_mbed_v1 by Kenji Arai

Embed: (wiki syntax)

« Back to documentation index

Show/hide line numbers recmutex.c Source File

recmutex.c

00001 /*
00002     FreeRTOS V6.0.3 - Copyright (C) 2010 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