git.sur5r.net Git - freertos/blob - FreeRTOS/Source/include/semphr.h

   1 /*\r
   2     FreeRTOS V7.4.1 - Copyright (C) 2013 Real Time Engineers Ltd.\r
   3 \r
   4     FEATURES AND PORTS ARE ADDED TO FREERTOS ALL THE TIME.  PLEASE VISIT\r
   5     http://www.FreeRTOS.org TO ENSURE YOU ARE USING THE LATEST VERSION.\r
   6 \r
   7     ***************************************************************************\r
   8      *                                                                       *\r
   9      *    FreeRTOS tutorial books are available in pdf and paperback.        *\r
  10      *    Complete, revised, and edited pdf reference manuals are also       *\r
  11      *    available.                                                         *\r
  12      *                                                                       *\r
  13      *    Purchasing FreeRTOS documentation will not only help you, by       *\r
  14      *    ensuring you get running as quickly as possible and with an        *\r
  15      *    in-depth knowledge of how to use FreeRTOS, it will also help       *\r
  16      *    the FreeRTOS project to continue with its mission of providing     *\r
  17      *    professional grade, cross platform, de facto standard solutions    *\r
  18      *    for microcontrollers - completely free of charge!                  *\r
  19      *                                                                       *\r
  20      *    >>> See http://www.FreeRTOS.org/Documentation for details. <<<     *\r
  21      *                                                                       *\r
  22      *    Thank you for using FreeRTOS, and thank you for your support!      *\r
  23      *                                                                       *\r
  24     ***************************************************************************\r
  25 \r
  26 \r
  27     This file is part of the FreeRTOS distribution.\r
  28 \r
  29     FreeRTOS is free software; you can redistribute it and/or modify it under\r
  30     the terms of the GNU General Public License (version 2) as published by the\r
  31     Free Software Foundation AND MODIFIED BY the FreeRTOS exception.\r
  32 \r
  33     >>>>>>NOTE<<<<<< The modification to the GPL is included to allow you to\r
  34     distribute a combined work that includes FreeRTOS without being obliged to\r
  35     provide the source code for proprietary components outside of the FreeRTOS\r
  36     kernel.\r
  37 \r
  38     FreeRTOS is distributed in the hope that it will be useful, but WITHOUT ANY\r
  39     WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS\r
  40     FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more\r
  41     details. You should have received a copy of the GNU General Public License\r
  42     and the FreeRTOS license exception along with FreeRTOS; if not it can be\r
  43     viewed here: http://www.freertos.org/a00114.html and also obtained by\r
  44     writing to Real Time Engineers Ltd., contact details for whom are available\r
  45     on the FreeRTOS WEB site.\r
  46 \r
  47     1 tab == 4 spaces!\r
  48 \r
  49     ***************************************************************************\r
  50      *                                                                       *\r
  51      *    Having a problem?  Start by reading the FAQ "My application does   *\r
  52      *    not run, what could be wrong?"                                     *\r
  53      *                                                                       *\r
  54      *    http://www.FreeRTOS.org/FAQHelp.html                               *\r
  55      *                                                                       *\r
  56     ***************************************************************************\r
  57 \r
  58 \r
  59     http://www.FreeRTOS.org - Documentation, books, training, latest versions, \r
  60     license and Real Time Engineers Ltd. contact details.\r
  61 \r
  62     http://www.FreeRTOS.org/plus - A selection of FreeRTOS ecosystem products,\r
  63     including FreeRTOS+Trace - an indispensable productivity tool, and our new\r
  64     fully thread aware and reentrant UDP/IP stack.\r
  65 \r
  66     http://www.OpenRTOS.com - Real Time Engineers ltd license FreeRTOS to High \r
  67     Integrity Systems, who sell the code with commercial support, \r
  68     indemnification and middleware, under the OpenRTOS brand.\r
  69     \r
  70     http://www.SafeRTOS.com - High Integrity Systems also provide a safety \r
  71     engineered and independently SIL3 certified version for use in safety and \r
  72     mission critical applications that require provable dependability.\r
  73 */\r
  74 \r
  75 #ifndef SEMAPHORE_H\r
  76 #define SEMAPHORE_H\r
  77 \r
  78 #ifndef INC_FREERTOS_H\r
  79         #error "include FreeRTOS.h" must appear in source files before "include semphr.h"\r
  80 #endif\r
  81 \r
  82 #include "queue.h"\r
  83 \r
  84 typedef xQueueHandle xSemaphoreHandle;\r
  85 \r
  86 #define semBINARY_SEMAPHORE_QUEUE_LENGTH        ( ( unsigned char ) 1U )\r
  87 #define semSEMAPHORE_QUEUE_ITEM_LENGTH          ( ( unsigned char ) 0U )\r
  88 #define semGIVE_BLOCK_TIME                                      ( ( portTickType ) 0U )\r
  89 \r
  90 \r
  91 /**\r
  92  * semphr. h\r
  93  * <pre>vSemaphoreCreateBinary( xSemaphoreHandle xSemaphore )</pre>\r
  94  *\r
  95  * <i>Macro</i> that implements a semaphore by using the existing queue mechanism.\r
  96  * The queue length is 1 as this is a binary semaphore.  The data size is 0\r
  97  * as we don't want to actually store any data - we just want to know if the\r
  98  * queue is empty or full.\r
  99  *\r
 100  * This type of semaphore can be used for pure synchronisation between tasks or\r
 101  * between an interrupt and a task.  The semaphore need not be given back once\r
 102  * obtained, so one task/interrupt can continuously 'give' the semaphore while\r
 103  * another continuously 'takes' the semaphore.  For this reason this type of\r
 104  * semaphore does not use a priority inheritance mechanism.  For an alternative\r
 105  * that does use priority inheritance see xSemaphoreCreateMutex().\r
 106  *\r
 107  * @param xSemaphore Handle to the created semaphore.  Should be of type xSemaphoreHandle.\r
 108  *\r
 109  * Example usage:\r
 110  <pre>\r
 111  xSemaphoreHandle xSemaphore;\r
 112 \r
 113  void vATask( void * pvParameters )\r
 114  {\r
 115     // Semaphore cannot be used before a call to vSemaphoreCreateBinary ().\r
 116     // This is a macro so pass the variable in directly.\r
 117     vSemaphoreCreateBinary( xSemaphore );\r
 118 \r
 119     if( xSemaphore != NULL )\r
 120     {\r
 121         // The semaphore was created successfully.\r
 122         // The semaphore can now be used.  \r
 123     }\r
 124  }\r
 125  </pre>\r
 126  * \defgroup vSemaphoreCreateBinary vSemaphoreCreateBinary\r
 127  * \ingroup Semaphores\r
 128  */\r
 129 #define vSemaphoreCreateBinary( xSemaphore )                                                                                                                                                                                                    \\r
 130         {                                                                                                                                                                                                                                                                                       \\r
 131                 ( xSemaphore ) = xQueueGenericCreate( ( unsigned portBASE_TYPE ) 1, semSEMAPHORE_QUEUE_ITEM_LENGTH, queueQUEUE_TYPE_BINARY_SEMAPHORE ); \\r
 132                 if( ( xSemaphore ) != NULL )                                                                                                                                                                                                                    \\r
 133                 {                                                                                                                                                                                                                                                                               \\r
 134                         xSemaphoreGive( ( xSemaphore ) );                                                                                                                                                                                                       \\r
 135                 }                                                                                                                                                                                                                                                                               \\r
 136         }\r
 137 \r
 138 /**\r
 139  * semphr. h\r
 140  * <pre>xSemaphoreTake( \r
 141  *                   xSemaphoreHandle xSemaphore, \r
 142  *                   portTickType xBlockTime \r
 143  *               )</pre>\r
 144  *\r
 145  * <i>Macro</i> to obtain a semaphore.  The semaphore must have previously been\r
 146  * created with a call to vSemaphoreCreateBinary(), xSemaphoreCreateMutex() or\r
 147  * xSemaphoreCreateCounting().\r
 148  *\r
 149  * @param xSemaphore A handle to the semaphore being taken - obtained when\r
 150  * the semaphore was created.\r
 151  *\r
 152  * @param xBlockTime The time in ticks to wait for the semaphore to become\r
 153  * available.  The macro portTICK_RATE_MS can be used to convert this to a\r
 154  * real time.  A block time of zero can be used to poll the semaphore.  A block\r
 155  * time of portMAX_DELAY can be used to block indefinitely (provided\r
 156  * INCLUDE_vTaskSuspend is set to 1 in FreeRTOSConfig.h).\r
 157  *\r
 158  * @return pdTRUE if the semaphore was obtained.  pdFALSE\r
 159  * if xBlockTime expired without the semaphore becoming available.\r
 160  *\r
 161  * Example usage:\r
 162  <pre>\r
 163  xSemaphoreHandle xSemaphore = NULL;\r
 164 \r
 165  // A task that creates a semaphore.\r
 166  void vATask( void * pvParameters )\r
 167  {\r
 168     // Create the semaphore to guard a shared resource.\r
 169     vSemaphoreCreateBinary( xSemaphore );\r
 170  }\r
 171 \r
 172  // A task that uses the semaphore.\r
 173  void vAnotherTask( void * pvParameters )\r
 174  {\r
 175     // ... Do other things.\r
 176 \r
 177     if( xSemaphore != NULL )\r
 178     {\r
 179         // See if we can obtain the semaphore.  If the semaphore is not available\r
 180         // wait 10 ticks to see if it becomes free.     \r
 181         if( xSemaphoreTake( xSemaphore, ( portTickType ) 10 ) == pdTRUE )\r
 182         {\r
 183             // We were able to obtain the semaphore and can now access the\r
 184             // shared resource.\r
 185 \r
 186             // ...\r
 187 \r
 188             // We have finished accessing the shared resource.  Release the \r
 189             // semaphore.\r
 190             xSemaphoreGive( xSemaphore );\r
 191         }\r
 192         else\r
 193         {\r
 194             // We could not obtain the semaphore and can therefore not access\r
 195             // the shared resource safely.\r
 196         }\r
 197     }\r
 198  }\r
 199  </pre>\r
 200  * \defgroup xSemaphoreTake xSemaphoreTake\r
 201  * \ingroup Semaphores\r
 202  */\r
 203 #define xSemaphoreTake( xSemaphore, xBlockTime )                xQueueGenericReceive( ( xQueueHandle ) ( xSemaphore ), NULL, ( xBlockTime ), pdFALSE )\r
 204 \r
 205 /**\r
 206  * semphr. h\r
 207  * xSemaphoreTakeRecursive( \r
 208  *                          xSemaphoreHandle xMutex, \r
 209  *                          portTickType xBlockTime \r
 210  *                        )\r
 211  *\r
 212  * <i>Macro</i> to recursively obtain, or 'take', a mutex type semaphore.  \r
 213  * The mutex must have previously been created using a call to \r
 214  * xSemaphoreCreateRecursiveMutex();\r
 215  * \r
 216  * configUSE_RECURSIVE_MUTEXES must be set to 1 in FreeRTOSConfig.h for this\r
 217  * macro to be available.\r
 218  * \r
 219  * This macro must not be used on mutexes created using xSemaphoreCreateMutex().\r
 220  *\r
 221  * A mutex used recursively can be 'taken' repeatedly by the owner. The mutex \r
 222  * doesn't become available again until the owner has called \r
 223  * xSemaphoreGiveRecursive() for each successful 'take' request.  For example, \r
 224  * if a task successfully 'takes' the same mutex 5 times then the mutex will \r
 225  * not be available to any other task until it has also  'given' the mutex back\r
 226  * exactly five times.\r
 227  *\r
 228  * @param xMutex A handle to the mutex being obtained.  This is the\r
 229  * handle returned by xSemaphoreCreateRecursiveMutex();\r
 230  *\r
 231  * @param xBlockTime The time in ticks to wait for the semaphore to become\r
 232  * available.  The macro portTICK_RATE_MS can be used to convert this to a\r
 233  * real time.  A block time of zero can be used to poll the semaphore.  If\r
 234  * the task already owns the semaphore then xSemaphoreTakeRecursive() will\r
 235  * return immediately no matter what the value of xBlockTime. \r
 236  *\r
 237  * @return pdTRUE if the semaphore was obtained.  pdFALSE if xBlockTime\r
 238  * expired without the semaphore becoming available.\r
 239  *\r
 240  * Example usage:\r
 241  <pre>\r
 242  xSemaphoreHandle xMutex = NULL;\r
 243 \r
 244  // A task that creates a mutex.\r
 245  void vATask( void * pvParameters )\r
 246  {\r
 247     // Create the mutex to guard a shared resource.\r
 248     xMutex = xSemaphoreCreateRecursiveMutex();\r
 249  }\r
 250 \r
 251  // A task that uses the mutex.\r
 252  void vAnotherTask( void * pvParameters )\r
 253  {\r
 254     // ... Do other things.\r
 255 \r
 256     if( xMutex != NULL )\r
 257     {\r
 258         // See if we can obtain the mutex.  If the mutex is not available\r
 259         // wait 10 ticks to see if it becomes free.     \r
 260         if( xSemaphoreTakeRecursive( xSemaphore, ( portTickType ) 10 ) == pdTRUE )\r
 261         {\r
 262             // We were able to obtain the mutex and can now access the\r
 263             // shared resource.\r
 264 \r
 265             // ...\r
 266             // For some reason due to the nature of the code further calls to \r
 267                         // xSemaphoreTakeRecursive() are made on the same mutex.  In real\r
 268                         // code these would not be just sequential calls as this would make\r
 269                         // no sense.  Instead the calls are likely to be buried inside\r
 270                         // a more complex call structure.\r
 271             xSemaphoreTakeRecursive( xMutex, ( portTickType ) 10 );\r
 272             xSemaphoreTakeRecursive( xMutex, ( portTickType ) 10 );\r
 273 \r
 274             // The mutex has now been 'taken' three times, so will not be \r
 275                         // available to another task until it has also been given back\r
 276                         // three times.  Again it is unlikely that real code would have\r
 277                         // these calls sequentially, but instead buried in a more complex\r
 278                         // call structure.  This is just for illustrative purposes.\r
 279             xSemaphoreGiveRecursive( xMutex );\r
 280                         xSemaphoreGiveRecursive( xMutex );\r
 281                         xSemaphoreGiveRecursive( xMutex );\r
 282 \r
 283                         // Now the mutex can be taken by other tasks.\r
 284         }\r
 285         else\r
 286         {\r
 287             // We could not obtain the mutex and can therefore not access\r
 288             // the shared resource safely.\r
 289         }\r
 290     }\r
 291  }\r
 292  </pre>\r
 293  * \defgroup xSemaphoreTakeRecursive xSemaphoreTakeRecursive\r
 294  * \ingroup Semaphores\r
 295  */\r
 296 #define xSemaphoreTakeRecursive( xMutex, xBlockTime )   xQueueTakeMutexRecursive( ( xMutex ), ( xBlockTime ) )\r
 297 \r
 298 \r
 299 /* \r
 300  * xSemaphoreAltTake() is an alternative version of xSemaphoreTake().\r
 301  *\r
 302  * The source code that implements the alternative (Alt) API is much \r
 303  * simpler      because it executes everything from within a critical section.  \r
 304  * This is      the approach taken by many other RTOSes, but FreeRTOS.org has the \r
 305  * preferred fully featured API too.  The fully featured API has more \r
 306  * complex      code that takes longer to execute, but makes much less use of \r
 307  * critical sections.  Therefore the alternative API sacrifices interrupt \r
 308  * responsiveness to gain execution speed, whereas the fully featured API\r
 309  * sacrifices execution speed to ensure better interrupt responsiveness.\r
 310  */\r
 311 #define xSemaphoreAltTake( xSemaphore, xBlockTime )             xQueueAltGenericReceive( ( xQueueHandle ) ( xSemaphore ), NULL, ( xBlockTime ), pdFALSE )\r
 312 \r
 313 /**\r
 314  * semphr. h\r
 315  * <pre>xSemaphoreGive( xSemaphoreHandle xSemaphore )</pre>\r
 316  *\r
 317  * <i>Macro</i> to release a semaphore.  The semaphore must have previously been\r
 318  * created with a call to vSemaphoreCreateBinary(), xSemaphoreCreateMutex() or\r
 319  * xSemaphoreCreateCounting(). and obtained using sSemaphoreTake().\r
 320  *\r
 321  * This macro must not be used from an ISR.  See xSemaphoreGiveFromISR () for\r
 322  * an alternative which can be used from an ISR.\r
 323  *\r
 324  * This macro must also not be used on semaphores created using \r
 325  * xSemaphoreCreateRecursiveMutex().\r
 326  *\r
 327  * @param xSemaphore A handle to the semaphore being released.  This is the\r
 328  * handle returned when the semaphore was created.\r
 329  *\r
 330  * @return pdTRUE if the semaphore was released.  pdFALSE if an error occurred.\r
 331  * Semaphores are implemented using queues.  An error can occur if there is\r
 332  * no space on the queue to post a message - indicating that the \r
 333  * semaphore was not first obtained correctly.\r
 334  *\r
 335  * Example usage:\r
 336  <pre>\r
 337  xSemaphoreHandle xSemaphore = NULL;\r
 338 \r
 339  void vATask( void * pvParameters )\r
 340  {\r
 341     // Create the semaphore to guard a shared resource.\r
 342     vSemaphoreCreateBinary( xSemaphore );\r
 343 \r
 344     if( xSemaphore != NULL )\r
 345     {\r
 346         if( xSemaphoreGive( xSemaphore ) != pdTRUE )\r
 347         {\r
 348             // We would expect this call to fail because we cannot give\r
 349             // a semaphore without first "taking" it!\r
 350         }\r
 351 \r
 352         // Obtain the semaphore - don't block if the semaphore is not\r
 353         // immediately available.\r
 354         if( xSemaphoreTake( xSemaphore, ( portTickType ) 0 ) )\r
 355         {\r
 356             // We now have the semaphore and can access the shared resource.\r
 357 \r
 358             // ...\r
 359 \r
 360             // We have finished accessing the shared resource so can free the\r
 361             // semaphore.\r
 362             if( xSemaphoreGive( xSemaphore ) != pdTRUE )\r
 363             {\r
 364                 // We would not expect this call to fail because we must have\r
 365                 // obtained the semaphore to get here.\r
 366             }\r
 367         }\r
 368     }\r
 369  }\r
 370  </pre>\r
 371  * \defgroup xSemaphoreGive xSemaphoreGive\r
 372  * \ingroup Semaphores\r
 373  */\r
 374 #define xSemaphoreGive( xSemaphore )            xQueueGenericSend( ( xQueueHandle ) ( xSemaphore ), NULL, semGIVE_BLOCK_TIME, queueSEND_TO_BACK )\r
 375 \r
 376 /**\r
 377  * semphr. h\r
 378  * <pre>xSemaphoreGiveRecursive( xSemaphoreHandle xMutex )</pre>\r
 379  *\r
 380  * <i>Macro</i> to recursively release, or 'give', a mutex type semaphore.\r
 381  * The mutex must have previously been created using a call to \r
 382  * xSemaphoreCreateRecursiveMutex();\r
 383  * \r
 384  * configUSE_RECURSIVE_MUTEXES must be set to 1 in FreeRTOSConfig.h for this\r
 385  * macro to be available.\r
 386  *\r
 387  * This macro must not be used on mutexes created using xSemaphoreCreateMutex().\r
 388  * \r
 389  * A mutex used recursively can be 'taken' repeatedly by the owner. The mutex \r
 390  * doesn't become available again until the owner has called \r
 391  * xSemaphoreGiveRecursive() for each successful 'take' request.  For example, \r
 392  * if a task successfully 'takes' the same mutex 5 times then the mutex will \r
 393  * not be available to any other task until it has also  'given' the mutex back\r
 394  * exactly five times.\r
 395  *\r
 396  * @param xMutex A handle to the mutex being released, or 'given'.  This is the\r
 397  * handle returned by xSemaphoreCreateMutex();\r
 398  *\r
 399  * @return pdTRUE if the semaphore was given.\r
 400  *\r
 401  * Example usage:\r
 402  <pre>\r
 403  xSemaphoreHandle xMutex = NULL;\r
 404 \r
 405  // A task that creates a mutex.\r
 406  void vATask( void * pvParameters )\r
 407  {\r
 408     // Create the mutex to guard a shared resource.\r
 409     xMutex = xSemaphoreCreateRecursiveMutex();\r
 410  }\r
 411 \r
 412  // A task that uses the mutex.\r
 413  void vAnotherTask( void * pvParameters )\r
 414  {\r
 415     // ... Do other things.\r
 416 \r
 417     if( xMutex != NULL )\r
 418     {\r
 419         // See if we can obtain the mutex.  If the mutex is not available\r
 420         // wait 10 ticks to see if it becomes free.     \r
 421         if( xSemaphoreTakeRecursive( xMutex, ( portTickType ) 10 ) == pdTRUE )\r
 422         {\r
 423             // We were able to obtain the mutex and can now access the\r
 424             // shared resource.\r
 425 \r
 426             // ...\r
 427             // For some reason due to the nature of the code further calls to \r
 428                         // xSemaphoreTakeRecursive() are made on the same mutex.  In real\r
 429                         // code these would not be just sequential calls as this would make\r
 430                         // no sense.  Instead the calls are likely to be buried inside\r
 431                         // a more complex call structure.\r
 432             xSemaphoreTakeRecursive( xMutex, ( portTickType ) 10 );\r
 433             xSemaphoreTakeRecursive( xMutex, ( portTickType ) 10 );\r
 434 \r
 435             // The mutex has now been 'taken' three times, so will not be \r
 436                         // available to another task until it has also been given back\r
 437                         // three times.  Again it is unlikely that real code would have\r
 438                         // these calls sequentially, it would be more likely that the calls\r
 439                         // to xSemaphoreGiveRecursive() would be called as a call stack\r
 440                         // unwound.  This is just for demonstrative purposes.\r
 441             xSemaphoreGiveRecursive( xMutex );\r
 442                         xSemaphoreGiveRecursive( xMutex );\r
 443                         xSemaphoreGiveRecursive( xMutex );\r
 444 \r
 445                         // Now the mutex can be taken by other tasks.\r
 446         }\r
 447         else\r
 448         {\r
 449             // We could not obtain the mutex and can therefore not access\r
 450             // the shared resource safely.\r
 451         }\r
 452     }\r
 453  }\r
 454  </pre>\r
 455  * \defgroup xSemaphoreGiveRecursive xSemaphoreGiveRecursive\r
 456  * \ingroup Semaphores\r
 457  */\r
 458 #define xSemaphoreGiveRecursive( xMutex )       xQueueGiveMutexRecursive( ( xMutex ) )\r
 459 \r
 460 /* \r
 461  * xSemaphoreAltGive() is an alternative version of xSemaphoreGive().\r
 462  *\r
 463  * The source code that implements the alternative (Alt) API is much \r
 464  * simpler      because it executes everything from within a critical section.  \r
 465  * This is      the approach taken by many other RTOSes, but FreeRTOS.org has the \r
 466  * preferred fully featured API too.  The fully featured API has more \r
 467  * complex      code that takes longer to execute, but makes much less use of \r
 468  * critical sections.  Therefore the alternative API sacrifices interrupt \r
 469  * responsiveness to gain execution speed, whereas the fully featured API\r
 470  * sacrifices execution speed to ensure better interrupt responsiveness.\r
 471  */\r
 472 #define xSemaphoreAltGive( xSemaphore )         xQueueAltGenericSend( ( xQueueHandle ) ( xSemaphore ), NULL, semGIVE_BLOCK_TIME, queueSEND_TO_BACK )\r
 473 \r
 474 /**\r
 475  * semphr. h\r
 476  * <pre>\r
 477  xSemaphoreGiveFromISR( \r
 478                           xSemaphoreHandle xSemaphore, \r
 479                           signed portBASE_TYPE *pxHigherPriorityTaskWoken\r
 480                       )</pre>\r
 481  *\r
 482  * <i>Macro</i> to  release a semaphore.  The semaphore must have previously been\r
 483  * created with a call to vSemaphoreCreateBinary() or xSemaphoreCreateCounting().\r
 484  *\r
 485  * Mutex type semaphores (those created using a call to xSemaphoreCreateMutex())\r
 486  * must not be used with this macro.\r
 487  *\r
 488  * This macro can be used from an ISR.\r
 489  *\r
 490  * @param xSemaphore A handle to the semaphore being released.  This is the\r
 491  * handle returned when the semaphore was created.\r
 492  *\r
 493  * @param pxHigherPriorityTaskWoken xSemaphoreGiveFromISR() will set\r
 494  * *pxHigherPriorityTaskWoken to pdTRUE if giving the semaphore caused a task\r
 495  * to unblock, and the unblocked task has a priority higher than the currently\r
 496  * running task.  If xSemaphoreGiveFromISR() sets this value to pdTRUE then\r
 497  * a context switch should be requested before the interrupt is exited.\r
 498  *\r
 499  * @return pdTRUE if the semaphore was successfully given, otherwise errQUEUE_FULL.\r
 500  *\r
 501  * Example usage:\r
 502  <pre>\r
 503  \#define LONG_TIME 0xffff\r
 504  \#define TICKS_TO_WAIT 10\r
 505  xSemaphoreHandle xSemaphore = NULL;\r
 506 \r
 507  // Repetitive task.\r
 508  void vATask( void * pvParameters )\r
 509  {\r
 510     for( ;; )\r
 511     {\r
 512         // We want this task to run every 10 ticks of a timer.  The semaphore \r
 513         // was created before this task was started.\r
 514 \r
 515         // Block waiting for the semaphore to become available.\r
 516         if( xSemaphoreTake( xSemaphore, LONG_TIME ) == pdTRUE )\r
 517         {\r
 518             // It is time to execute.\r
 519 \r
 520             // ...\r
 521 \r
 522             // We have finished our task.  Return to the top of the loop where\r
 523             // we will block on the semaphore until it is time to execute \r
 524             // again.  Note when using the semaphore for synchronisation with an\r
 525                         // ISR in this manner there is no need to 'give' the semaphore back.\r
 526         }\r
 527     }\r
 528  }\r
 529 \r
 530  // Timer ISR\r
 531  void vTimerISR( void * pvParameters )\r
 532  {\r
 533  static unsigned char ucLocalTickCount = 0;\r
 534  static signed portBASE_TYPE xHigherPriorityTaskWoken;\r
 535 \r
 536     // A timer tick has occurred.\r
 537 \r
 538     // ... Do other time functions.\r
 539 \r
 540     // Is it time for vATask () to run?\r
 541         xHigherPriorityTaskWoken = pdFALSE;\r
 542     ucLocalTickCount++;\r
 543     if( ucLocalTickCount >= TICKS_TO_WAIT )\r
 544     {\r
 545         // Unblock the task by releasing the semaphore.\r
 546         xSemaphoreGiveFromISR( xSemaphore, &xHigherPriorityTaskWoken );\r
 547 \r
 548         // Reset the count so we release the semaphore again in 10 ticks time.\r
 549         ucLocalTickCount = 0;\r
 550     }\r
 551 \r
 552     if( xHigherPriorityTaskWoken != pdFALSE )\r
 553     {\r
 554         // We can force a context switch here.  Context switching from an\r
 555         // ISR uses port specific syntax.  Check the demo task for your port\r
 556         // to find the syntax required.\r
 557     }\r
 558  }\r
 559  </pre>\r
 560  * \defgroup xSemaphoreGiveFromISR xSemaphoreGiveFromISR\r
 561  * \ingroup Semaphores\r
 562  */\r
 563 #define xSemaphoreGiveFromISR( xSemaphore, pxHigherPriorityTaskWoken )                  xQueueGenericSendFromISR( ( xQueueHandle ) ( xSemaphore ), NULL, ( pxHigherPriorityTaskWoken ), queueSEND_TO_BACK )\r
 564 \r
 565 /**\r
 566  * semphr. h\r
 567  * <pre>\r
 568  xSemaphoreTakeFromISR( \r
 569                           xSemaphoreHandle xSemaphore, \r
 570                           signed portBASE_TYPE *pxHigherPriorityTaskWoken\r
 571                       )</pre>\r
 572  *\r
 573  * <i>Macro</i> to  take a semaphore from an ISR.  The semaphore must have \r
 574  * previously been created with a call to vSemaphoreCreateBinary() or \r
 575  * xSemaphoreCreateCounting().\r
 576  *\r
 577  * Mutex type semaphores (those created using a call to xSemaphoreCreateMutex())\r
 578  * must not be used with this macro.\r
 579  *\r
 580  * This macro can be used from an ISR, however taking a semaphore from an ISR\r
 581  * is not a common operation.  It is likely to only be useful when taking a\r
 582  * counting semaphore when an interrupt is obtaining an object from a resource\r
 583  * pool (when the semaphore count indicates the number of resources available).\r
 584  *\r
 585  * @param xSemaphore A handle to the semaphore being taken.  This is the\r
 586  * handle returned when the semaphore was created.\r
 587  *\r
 588  * @param pxHigherPriorityTaskWoken xSemaphoreTakeFromISR() will set\r
 589  * *pxHigherPriorityTaskWoken to pdTRUE if taking the semaphore caused a task\r
 590  * to unblock, and the unblocked task has a priority higher than the currently\r
 591  * running task.  If xSemaphoreTakeFromISR() sets this value to pdTRUE then\r
 592  * a context switch should be requested before the interrupt is exited.\r
 593  *\r
 594  * @return pdTRUE if the semaphore was successfully taken, otherwise \r
 595  * pdFALSE\r
 596  */\r
 597 #define xSemaphoreTakeFromISR( xSemaphore, pxHigherPriorityTaskWoken )                  xQueueReceiveFromISR( ( xQueueHandle ) ( xSemaphore ), NULL, ( pxHigherPriorityTaskWoken ) )\r
 598 \r
 599 /**\r
 600  * semphr. h\r
 601  * <pre>xSemaphoreHandle xSemaphoreCreateMutex( void )</pre>\r
 602  *\r
 603  * <i>Macro</i> that implements a mutex semaphore by using the existing queue \r
 604  * mechanism.\r
 605  *\r
 606  * Mutexes created using this macro can be accessed using the xSemaphoreTake()\r
 607  * and xSemaphoreGive() macros.  The xSemaphoreTakeRecursive() and \r
 608  * xSemaphoreGiveRecursive() macros should not be used.\r
 609  * \r
 610  * This type of semaphore uses a priority inheritance mechanism so a task \r
 611  * 'taking' a semaphore MUST ALWAYS 'give' the semaphore back once the \r
 612  * semaphore it is no longer required.  \r
 613  *\r
 614  * Mutex type semaphores cannot be used from within interrupt service routines.  \r
 615  *\r
 616  * See vSemaphoreCreateBinary() for an alternative implementation that can be \r
 617  * used for pure synchronisation (where one task or interrupt always 'gives' the \r
 618  * semaphore and another always 'takes' the semaphore) and from within interrupt \r
 619  * service routines.\r
 620  *\r
 621  * @return xSemaphore Handle to the created mutex semaphore.  Should be of type \r
 622  *              xSemaphoreHandle.\r
 623  *\r
 624  * Example usage:\r
 625  <pre>\r
 626  xSemaphoreHandle xSemaphore;\r
 627 \r
 628  void vATask( void * pvParameters )\r
 629  {\r
 630     // Semaphore cannot be used before a call to xSemaphoreCreateMutex().\r
 631     // This is a macro so pass the variable in directly.\r
 632     xSemaphore = xSemaphoreCreateMutex();\r
 633 \r
 634     if( xSemaphore != NULL )\r
 635     {\r
 636         // The semaphore was created successfully.\r
 637         // The semaphore can now be used.  \r
 638     }\r
 639  }\r
 640  </pre>\r
 641  * \defgroup vSemaphoreCreateMutex vSemaphoreCreateMutex\r
 642  * \ingroup Semaphores\r
 643  */\r
 644 #define xSemaphoreCreateMutex() xQueueCreateMutex( queueQUEUE_TYPE_MUTEX )\r
 645 \r
 646 \r
 647 /**\r
 648  * semphr. h\r
 649  * <pre>xSemaphoreHandle xSemaphoreCreateRecursiveMutex( void )</pre>\r
 650  *\r
 651  * <i>Macro</i> that implements a recursive mutex by using the existing queue \r
 652  * mechanism.\r
 653  *\r
 654  * Mutexes created using this macro can be accessed using the \r
 655  * xSemaphoreTakeRecursive() and xSemaphoreGiveRecursive() macros.  The \r
 656  * xSemaphoreTake() and xSemaphoreGive() macros should not be used.\r
 657  *\r
 658  * A mutex used recursively can be 'taken' repeatedly by the owner. The mutex \r
 659  * doesn't become available again until the owner has called \r
 660  * xSemaphoreGiveRecursive() for each successful 'take' request.  For example, \r
 661  * if a task successfully 'takes' the same mutex 5 times then the mutex will \r
 662  * not be available to any other task until it has also  'given' the mutex back\r
 663  * exactly five times.\r
 664  * \r
 665  * This type of semaphore uses a priority inheritance mechanism so a task \r
 666  * 'taking' a semaphore MUST ALWAYS 'give' the semaphore back once the \r
 667  * semaphore it is no longer required.  \r
 668  *\r
 669  * Mutex type semaphores cannot be used from within interrupt service routines.  \r
 670  *\r
 671  * See vSemaphoreCreateBinary() for an alternative implementation that can be \r
 672  * used for pure synchronisation (where one task or interrupt always 'gives' the \r
 673  * semaphore and another always 'takes' the semaphore) and from within interrupt \r
 674  * service routines.\r
 675  *\r
 676  * @return xSemaphore Handle to the created mutex semaphore.  Should be of type \r
 677  *              xSemaphoreHandle.\r
 678  *\r
 679  * Example usage:\r
 680  <pre>\r
 681  xSemaphoreHandle xSemaphore;\r
 682 \r
 683  void vATask( void * pvParameters )\r
 684  {\r
 685     // Semaphore cannot be used before a call to xSemaphoreCreateMutex().\r
 686     // This is a macro so pass the variable in directly.\r
 687     xSemaphore = xSemaphoreCreateRecursiveMutex();\r
 688 \r
 689     if( xSemaphore != NULL )\r
 690     {\r
 691         // The semaphore was created successfully.\r
 692         // The semaphore can now be used.  \r
 693     }\r
 694  }\r
 695  </pre>\r
 696  * \defgroup vSemaphoreCreateMutex vSemaphoreCreateMutex\r
 697  * \ingroup Semaphores\r
 698  */\r
 699 #define xSemaphoreCreateRecursiveMutex() xQueueCreateMutex( queueQUEUE_TYPE_RECURSIVE_MUTEX )\r
 700 \r
 701 /**\r
 702  * semphr. h\r
 703  * <pre>xSemaphoreHandle xSemaphoreCreateCounting( unsigned portBASE_TYPE uxMaxCount, unsigned portBASE_TYPE uxInitialCount )</pre>\r
 704  *\r
 705  * <i>Macro</i> that creates a counting semaphore by using the existing \r
 706  * queue mechanism.  \r
 707  *\r
 708  * Counting semaphores are typically used for two things:\r
 709  *\r
 710  * 1) Counting events.  \r
 711  *\r
 712  *    In this usage scenario an event handler will 'give' a semaphore each time\r
 713  *    an event occurs (incrementing the semaphore count value), and a handler \r
 714  *    task will 'take' a semaphore each time it processes an event \r
 715  *    (decrementing the semaphore count value).  The count value is therefore \r
 716  *    the difference between the number of events that have occurred and the \r
 717  *    number that have been processed.  In this case it is desirable for the \r
 718  *    initial count value to be zero.\r
 719  *\r
 720  * 2) Resource management.\r
 721  *\r
 722  *    In this usage scenario the count value indicates the number of resources\r
 723  *    available.  To obtain control of a resource a task must first obtain a \r
 724  *    semaphore - decrementing the semaphore count value.  When the count value\r
 725  *    reaches zero there are no free resources.  When a task finishes with the\r
 726  *    resource it 'gives' the semaphore back - incrementing the semaphore count\r
 727  *    value.  In this case it is desirable for the initial count value to be\r
 728  *    equal to the maximum count value, indicating that all resources are free.\r
 729  *\r
 730  * @param uxMaxCount The maximum count value that can be reached.  When the \r
 731  *        semaphore reaches this value it can no longer be 'given'.\r
 732  *\r
 733  * @param uxInitialCount The count value assigned to the semaphore when it is\r
 734  *        created.\r
 735  *\r
 736  * @return Handle to the created semaphore.  Null if the semaphore could not be\r
 737  *         created.\r
 738  * \r
 739  * Example usage:\r
 740  <pre>\r
 741  xSemaphoreHandle xSemaphore;\r
 742 \r
 743  void vATask( void * pvParameters )\r
 744  {\r
 745  xSemaphoreHandle xSemaphore = NULL;\r
 746 \r
 747     // Semaphore cannot be used before a call to xSemaphoreCreateCounting().\r
 748     // The max value to which the semaphore can count should be 10, and the\r
 749     // initial value assigned to the count should be 0.\r
 750     xSemaphore = xSemaphoreCreateCounting( 10, 0 );\r
 751 \r
 752     if( xSemaphore != NULL )\r
 753     {\r
 754         // The semaphore was created successfully.\r
 755         // The semaphore can now be used.  \r
 756     }\r
 757  }\r
 758  </pre>\r
 759  * \defgroup xSemaphoreCreateCounting xSemaphoreCreateCounting\r
 760  * \ingroup Semaphores\r
 761  */\r
 762 #define xSemaphoreCreateCounting( uxMaxCount, uxInitialCount ) xQueueCreateCountingSemaphore( ( uxMaxCount ), ( uxInitialCount ) )\r
 763 \r
 764 /**\r
 765  * semphr. h\r
 766  * <pre>void vSemaphoreDelete( xSemaphoreHandle xSemaphore );</pre>\r
 767  *\r
 768  * Delete a semaphore.  This function must be used with care.  For example,\r
 769  * do not delete a mutex type semaphore if the mutex is held by a task.\r
 770  *\r
 771  * @param xSemaphore A handle to the semaphore to be deleted.\r
 772  *\r
 773  * \page vSemaphoreDelete vSemaphoreDelete\r
 774  * \ingroup Semaphores\r
 775  */\r
 776 #define vSemaphoreDelete( xSemaphore ) vQueueDelete( ( xQueueHandle ) ( xSemaphore ) )\r
 777 \r
 778 /**\r
 779  * semphr.h\r
 780  * <pre>xTaskHandle xSemaphoreGetMutexHolder( xSemaphoreHandle xMutex );</pre>\r
 781  *\r
 782  * If xMutex is indeed a mutex type semaphore, return the current mutex holder.\r
 783  * If xMutex is not a mutex type semaphore, or the mutex is available (not held\r
 784  * by a task), return NULL.\r
 785  *\r
 786  * Note: This Is is a good way of determining if the calling task is the mutex \r
 787  * holder, but not a good way of determining the identity of the mutex holder as\r
 788  * the holder may change between the function exiting and the returned value\r
 789  * being tested.\r
 790  */\r
 791 #define xSemaphoreGetMutexHolder( xSemaphore ) xQueueGetMutexHolder( ( xSemaphore ) )\r
 792 \r
 793 #endif /* SEMAPHORE_H */\r
 794 \r
 795 \r