FreeRTOS/Common/Full/semtest.c

   1 /*
   2     FreeRTOS V6.0.5 - Copyright (C) 2010 Real Time Engineers Ltd.
   3
   4     ***************************************************************************
   5     *                                                                         *
   6     * If you are:                                                             *
   7     *                                                                         *
   8     *    + New to FreeRTOS,                                                   *
   9     *    + Wanting to learn FreeRTOS or multitasking in general quickly       *
  10     *    + Looking for basic training,                                        *
  11     *    + Wanting to improve your FreeRTOS skills and productivity           *
  12     *                                                                         *
  13     * then take a look at the FreeRTOS eBook                                  *
  14     *                                                                         *
  15     *        "Using the FreeRTOS Real Time Kernel - a Practical Guide"        *
  16     *                  http://www.FreeRTOS.org/Documentation                  *
  17     *                                                                         *
  18     * A pdf reference manual is also available.  Both are usually delivered   *
  19     * to your inbox within 20 minutes to two hours when purchased between 8am *
  20     * and 8pm GMT (although please allow up to 24 hours in case of            *
  21     * exceptional circumstances).  Thank you for your support!                *
  22     *                                                                         *
  23     ***************************************************************************
  24
  25     This file is part of the FreeRTOS distribution.
  26
  27     FreeRTOS is free software; you can redistribute it and/or modify it under
  28     the terms of the GNU General Public License (version 2) as published by the
  29     Free Software Foundation AND MODIFIED BY the FreeRTOS exception.
  30     ***NOTE*** The exception to the GPL is included to allow you to distribute
  31     a combined work that includes FreeRTOS without being obliged to provide the
  32     source code for proprietary components outside of the FreeRTOS kernel.
  33     FreeRTOS is distributed in the hope that it will be useful, but WITHOUT
  34     ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  35     FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
  36     more details. You should have received a copy of the GNU General Public
  37     License and the FreeRTOS license exception along with FreeRTOS; if not it
  38     can be viewed here: http://www.freertos.org/a00114.html and also obtained
  39     by writing to Richard Barry, contact details for whom are available on the
  40     FreeRTOS WEB site.
  41
  42     1 tab == 4 spaces!
  43
  44     http://www.FreeRTOS.org - Documentation, latest information, license and
  45     contact details.
  46
  47     http://www.SafeRTOS.com - A version that is certified for use in safety
  48     critical systems.
  49
  50     http://www.OpenRTOS.com - Commercial support, development, porting,
  51     licensing and training services.
  52 */
  53
  54 /**
  55  * Creates two sets of two tasks.  The tasks within a set share a variable, access
  56  * to which is guarded by a semaphore.
  57  *
  58  * Each task starts by attempting to obtain the semaphore.  On obtaining a
  59  * semaphore a task checks to ensure that the guarded variable has an expected
  60  * value.  It then clears the variable to zero before counting it back up to the
  61  * expected value in increments of 1.  After each increment the variable is checked
  62  * to ensure it contains the value to which it was just set. When the starting
  63  * value is again reached the task releases the semaphore giving the other task in
  64  * the set a chance to do exactly the same thing.  The starting value is high
  65  * enough to ensure that a tick is likely to occur during the incrementing loop.
  66  *
  67  * An error is flagged if at any time during the process a shared variable is
  68  * found to have a value other than that expected.  Such an occurrence would
  69  * suggest an error in the mutual exclusion mechanism by which access to the
  70  * variable is restricted.
  71  *
  72  * The first set of two tasks poll their semaphore.  The second set use blocking
  73  * calls.
  74  *
  75  * \page SemTestC semtest.c
  76  * \ingroup DemoFiles
  77  * <HR>
  78  */
  79
  80 /*
  81 Changes from V1.2.0:
  82
  83         + The tasks that operate at the idle priority now use a lower expected
  84           count than those running at a higher priority.  This prevents the low
  85           priority tasks from signaling an error because they have not been
  86           scheduled enough time for each of them to count the shared variable to
  87           the high value.
  88
  89 Changes from V2.0.0
  90
  91         + Delay periods are now specified using variables and constants of
  92           portTickType rather than unsigned long.
  93
  94 Changes from V2.1.1
  95
  96         + The stack size now uses configMINIMAL_STACK_SIZE.
  97         + String constants made file scope to decrease stack depth on 8051 port.
  98 */
  99
 100 #include <stdlib.h>
 101
 102 /* Scheduler include files. */
 103 #include "FreeRTOS.h"
 104 #include "task.h"
 105 #include "semphr.h"
 106
 107 /* Demo app include files. */
 108 #include "semtest.h"
 109 #include "print.h"
 110
 111 /* The value to which the shared variables are counted. */
 112 #define semtstBLOCKING_EXPECTED_VALUE           ( ( unsigned long ) 0xfff )
 113 #define semtstNON_BLOCKING_EXPECTED_VALUE       ( ( unsigned long ) 0xff  )
 114
 115 #define semtstSTACK_SIZE                        configMINIMAL_STACK_SIZE
 116
 117 #define semtstNUM_TASKS                         ( 4 )
 118
 119 #define semtstDELAY_FACTOR                      ( ( portTickType ) 10 )
 120
 121 /* The task function as described at the top of the file. */
 122 static void prvSemaphoreTest( void *pvParameters );
 123
 124 /* Structure used to pass parameters to each task. */
 125 typedef struct SEMAPHORE_PARAMETERS
 126 {
 127         xSemaphoreHandle xSemaphore;
 128         volatile unsigned long *pulSharedVariable;
 129         portTickType xBlockTime;
 130 } xSemaphoreParameters;
 131
 132 /* Variables used to check that all the tasks are still running without errors. */
 133 static volatile short sCheckVariables[ semtstNUM_TASKS ] = { 0 };
 134 static volatile short sNextCheckVariable = 0;
 135
 136 /* Strings to print if USE_STDIO is defined. */
 137 const char * const pcPollingSemaphoreTaskError = "Guarded shared variable in unexpected state.\r\n";
 138 const char * const pcSemaphoreTaskStart = "Guarded shared variable task started.\r\n";
 139
 140 /*-----------------------------------------------------------*/
 141
 142 void vStartSemaphoreTasks( unsigned portBASE_TYPE uxPriority )
 143 {
 144 xSemaphoreParameters *pxFirstSemaphoreParameters, *pxSecondSemaphoreParameters;
 145 const portTickType xBlockTime = ( portTickType ) 100;
 146
 147         /* Create the structure used to pass parameters to the first two tasks. */
 148         pxFirstSemaphoreParameters = ( xSemaphoreParameters * ) pvPortMalloc( sizeof( xSemaphoreParameters ) );
 149
 150         if( pxFirstSemaphoreParameters != NULL )
 151         {
 152                 /* Create the semaphore used by the first two tasks. */
 153                 vSemaphoreCreateBinary( pxFirstSemaphoreParameters->xSemaphore );
 154
 155                 if( pxFirstSemaphoreParameters->xSemaphore != NULL )
 156                 {
 157                         /* Create the variable which is to be shared by the first two tasks. */
 158                         pxFirstSemaphoreParameters->pulSharedVariable = ( unsigned long * ) pvPortMalloc( sizeof( unsigned long ) );
 159
 160                         /* Initialise the share variable to the value the tasks expect. */
 161                         *( pxFirstSemaphoreParameters->pulSharedVariable ) = semtstNON_BLOCKING_EXPECTED_VALUE;
 162
 163                         /* The first two tasks do not block on semaphore calls. */
 164                         pxFirstSemaphoreParameters->xBlockTime = ( portTickType ) 0;
 165
 166                         /* Spawn the first two tasks.  As they poll they operate at the idle priority. */
 167                         xTaskCreate( prvSemaphoreTest, "PolSEM1", semtstSTACK_SIZE, ( void * ) pxFirstSemaphoreParameters, tskIDLE_PRIORITY, ( xTaskHandle * ) NULL );
 168                         xTaskCreate( prvSemaphoreTest, "PolSEM2", semtstSTACK_SIZE, ( void * ) pxFirstSemaphoreParameters, tskIDLE_PRIORITY, ( xTaskHandle * ) NULL );
 169                 }
 170         }
 171
 172         /* Do exactly the same to create the second set of tasks, only this time
 173         provide a block time for the semaphore calls. */
 174         pxSecondSemaphoreParameters = ( xSemaphoreParameters * ) pvPortMalloc( sizeof( xSemaphoreParameters ) );
 175         if( pxSecondSemaphoreParameters != NULL )
 176         {
 177                 vSemaphoreCreateBinary( pxSecondSemaphoreParameters->xSemaphore );
 178
 179                 if( pxSecondSemaphoreParameters->xSemaphore != NULL )
 180                 {
 181                         pxSecondSemaphoreParameters->pulSharedVariable = ( unsigned long * ) pvPortMalloc( sizeof( unsigned long ) );
 182                         *( pxSecondSemaphoreParameters->pulSharedVariable ) = semtstBLOCKING_EXPECTED_VALUE;
 183                         pxSecondSemaphoreParameters->xBlockTime = xBlockTime / portTICK_RATE_MS;
 184
 185                         xTaskCreate( prvSemaphoreTest, "BlkSEM1", semtstSTACK_SIZE, ( void * ) pxSecondSemaphoreParameters, uxPriority, ( xTaskHandle * ) NULL );
 186                         xTaskCreate( prvSemaphoreTest, "BlkSEM2", semtstSTACK_SIZE, ( void * ) pxSecondSemaphoreParameters, uxPriority, ( xTaskHandle * ) NULL );
 187                 }
 188         }
 189 }
 190 /*-----------------------------------------------------------*/
 191
 192 static void prvSemaphoreTest( void *pvParameters )
 193 {
 194 xSemaphoreParameters *pxParameters;
 195 volatile unsigned long *pulSharedVariable, ulExpectedValue;
 196 unsigned long ulCounter;
 197 short sError = pdFALSE, sCheckVariableToUse;
 198
 199         /* See which check variable to use.  sNextCheckVariable is not semaphore
 200         protected! */
 201         portENTER_CRITICAL();
 202                 sCheckVariableToUse = sNextCheckVariable;
 203                 sNextCheckVariable++;
 204         portEXIT_CRITICAL();
 205
 206         /* Queue a message for printing to say the task has started. */
 207         vPrintDisplayMessage( &pcSemaphoreTaskStart );
 208
 209         /* A structure is passed in as the parameter.  This contains the shared
 210         variable being guarded. */
 211         pxParameters = ( xSemaphoreParameters * ) pvParameters;
 212         pulSharedVariable = pxParameters->pulSharedVariable;
 213
 214         /* If we are blocking we use a much higher count to ensure loads of context
 215         switches occur during the count. */
 216         if( pxParameters->xBlockTime > ( portTickType ) 0 )
 217         {
 218                 ulExpectedValue = semtstBLOCKING_EXPECTED_VALUE;
 219         }
 220         else
 221         {
 222                 ulExpectedValue = semtstNON_BLOCKING_EXPECTED_VALUE;
 223         }
 224
 225         for( ;; )
 226         {
 227                 /* Try to obtain the semaphore. */
 228                 if( xSemaphoreTake( pxParameters->xSemaphore, pxParameters->xBlockTime ) == pdPASS )
 229                 {
 230                         /* We have the semaphore and so expect any other tasks using the
 231                         shared variable to have left it in the state we expect to find
 232                         it. */
 233                         if( *pulSharedVariable != ulExpectedValue )
 234                         {
 235                                 vPrintDisplayMessage( &pcPollingSemaphoreTaskError );
 236                                 sError = pdTRUE;
 237                         }
 238
 239                         /* Clear the variable, then count it back up to the expected value
 240                         before releasing the semaphore.  Would expect a context switch or
 241                         two during this time. */
 242                         for( ulCounter = ( unsigned long ) 0; ulCounter <= ulExpectedValue; ulCounter++ )
 243                         {
 244                                 *pulSharedVariable = ulCounter;
 245                                 if( *pulSharedVariable != ulCounter )
 246                                 {
 247                                         if( sError == pdFALSE )
 248                                         {
 249                                                 vPrintDisplayMessage( &pcPollingSemaphoreTaskError );
 250                                         }
 251                                         sError = pdTRUE;
 252                                 }
 253                         }
 254
 255                         /* Release the semaphore, and if no errors have occurred increment the check
 256                         variable. */
 257                         if(     xSemaphoreGive( pxParameters->xSemaphore ) == pdFALSE )
 258                         {
 259                                 vPrintDisplayMessage( &pcPollingSemaphoreTaskError );
 260                                 sError = pdTRUE;
 261                         }
 262
 263                         if( sError == pdFALSE )
 264                         {
 265                                 if( sCheckVariableToUse < semtstNUM_TASKS )
 266                                 {
 267                                         ( sCheckVariables[ sCheckVariableToUse ] )++;
 268                                 }
 269                         }
 270
 271                         /* If we have a block time then we are running at a priority higher
 272                         than the idle priority.  This task takes a long time to complete
 273                         a cycle (deliberately so to test the guarding) so will be starving
 274                         out lower priority tasks.  Block for some time to allow give lower
 275                         priority tasks some processor time. */
 276                         vTaskDelay( pxParameters->xBlockTime * semtstDELAY_FACTOR );
 277                 }
 278                 else
 279                 {
 280                         if( pxParameters->xBlockTime == ( portTickType ) 0 )
 281                         {
 282                                 /* We have not got the semaphore yet, so no point using the
 283                                 processor.  We are not blocking when attempting to obtain the
 284                                 semaphore. */
 285                                 taskYIELD();
 286                         }
 287                 }
 288         }
 289 }
 290 /*-----------------------------------------------------------*/
 291
 292 /* This is called to check that all the created tasks are still running. */
 293 portBASE_TYPE xAreSemaphoreTasksStillRunning( void )
 294 {
 295 static short sLastCheckVariables[ semtstNUM_TASKS ] = { 0 };
 296 portBASE_TYPE xTask, xReturn = pdTRUE;
 297
 298         for( xTask = 0; xTask < semtstNUM_TASKS; xTask++ )
 299         {
 300                 if( sLastCheckVariables[ xTask ] == sCheckVariables[ xTask ] )
 301                 {
 302                         xReturn = pdFALSE;
 303                 }
 304
 305                 sLastCheckVariables[ xTask ] = sCheckVariables[ xTask ];
 306         }
 307
 308         return xReturn;
 309 }
 310
 311