begriffs open source - freertos/blob - FreeRTOS/Source/include/semphr.h

   1 /*\r
   2  * FreeRTOS Kernel V10.0.0\r
   3  * Copyright (C) 2017 Amazon.com, Inc. or its affiliates.  All Rights Reserved.\r
   4  *\r
   5  * Permission is hereby granted, free of charge, to any person obtaining a copy of\r
   6  * this software and associated documentation files (the "Software"), to deal in\r
   7  * the Software without restriction, including without limitation the rights to\r
   8  * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of\r
   9  * the Software, and to permit persons to whom the Software is furnished to do so,\r
  10  * subject to the following conditions:\r
  11  *\r
  12  * The above copyright notice and this permission notice shall be included in all\r
  13  * copies or substantial portions of the Software. If you wish to use our Amazon\r
  14  * FreeRTOS name, please do so in a fair use way that does not cause confusion.\r
  15  *\r
  16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r
  17  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS\r
  18  * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR\r
  19  * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER\r
  20  * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
  21  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\r
  22  *\r
  23  * http://www.FreeRTOS.org\r
  24  * http://aws.amazon.com/freertos\r
  25  *\r
  26  * 1 tab == 4 spaces!\r
  27  */\r
  28 \r
  29 #ifndef SEMAPHORE_H\r
  30 #define SEMAPHORE_H\r
  31 \r
  32 #ifndef INC_FREERTOS_H\r
  33         #error "include FreeRTOS.h" must appear in source files before "include semphr.h"\r
  34 #endif\r
  35 \r
  36 #include "queue.h"\r
  37 \r
  38 typedef QueueHandle_t SemaphoreHandle_t;\r
  39 \r
  40 #define semBINARY_SEMAPHORE_QUEUE_LENGTH        ( ( uint8_t ) 1U )\r
  41 #define semSEMAPHORE_QUEUE_ITEM_LENGTH          ( ( uint8_t ) 0U )\r
  42 #define semGIVE_BLOCK_TIME                                      ( ( TickType_t ) 0U )\r
  43 \r
  44 \r
  45 /**\r
  46  * semphr. h\r
  47  * <pre>vSemaphoreCreateBinary( SemaphoreHandle_t xSemaphore )</pre>\r
  48  *\r
  49  * In many usage scenarios it is faster and more memory efficient to use a\r
  50  * direct to task notification in place of a binary semaphore!\r
  51  * http://www.freertos.org/RTOS-task-notifications.html\r
  52  *\r
  53  * This old vSemaphoreCreateBinary() macro is now deprecated in favour of the\r
  54  * xSemaphoreCreateBinary() function.  Note that binary semaphores created using\r
  55  * the vSemaphoreCreateBinary() macro are created in a state such that the\r
  56  * first call to 'take' the semaphore would pass, whereas binary semaphores\r
  57  * created using xSemaphoreCreateBinary() are created in a state such that the\r
  58  * the semaphore must first be 'given' before it can be 'taken'.\r
  59  *\r
  60  * <i>Macro</i> that implements a semaphore by using the existing queue mechanism.\r
  61  * The queue length is 1 as this is a binary semaphore.  The data size is 0\r
  62  * as we don't want to actually store any data - we just want to know if the\r
  63  * queue is empty or full.\r
  64  *\r
  65  * This type of semaphore can be used for pure synchronisation between tasks or\r
  66  * between an interrupt and a task.  The semaphore need not be given back once\r
  67  * obtained, so one task/interrupt can continuously 'give' the semaphore while\r
  68  * another continuously 'takes' the semaphore.  For this reason this type of\r
  69  * semaphore does not use a priority inheritance mechanism.  For an alternative\r
  70  * that does use priority inheritance see xSemaphoreCreateMutex().\r
  71  *\r
  72  * @param xSemaphore Handle to the created semaphore.  Should be of type SemaphoreHandle_t.\r
  73  *\r
  74  * Example usage:\r
  75  <pre>\r
  76  SemaphoreHandle_t xSemaphore = NULL;\r
  77 \r
  78  void vATask( void * pvParameters )\r
  79  {\r
  80     // Semaphore cannot be used before a call to vSemaphoreCreateBinary ().\r
  81     // This is a macro so pass the variable in directly.\r
  82     vSemaphoreCreateBinary( xSemaphore );\r
  83 \r
  84     if( xSemaphore != NULL )\r
  85     {\r
  86         // The semaphore was created successfully.\r
  87         // The semaphore can now be used.\r
  88     }\r
  89  }\r
  90  </pre>\r
  91  * \defgroup vSemaphoreCreateBinary vSemaphoreCreateBinary\r
  92  * \ingroup Semaphores\r
  93  */\r
  94 #if( configSUPPORT_DYNAMIC_ALLOCATION == 1 )\r
  95         #define vSemaphoreCreateBinary( xSemaphore )                                                                                                                                                                                    \\r
  96                 {                                                                                                                                                                                                                                                                       \\r
  97                         ( xSemaphore ) = xQueueGenericCreate( ( UBaseType_t ) 1, semSEMAPHORE_QUEUE_ITEM_LENGTH, queueQUEUE_TYPE_BINARY_SEMAPHORE );    \\r
  98                         if( ( xSemaphore ) != NULL )                                                                                                                                                                                                    \\r
  99                         {                                                                                                                                                                                                                                                               \\r
 100                                 ( void ) xSemaphoreGive( ( xSemaphore ) );                                                                                                                                                                      \\r
 101                         }                                                                                                                                                                                                                                                               \\r
 102                 }\r
 103 #endif\r
 104 \r
 105 /**\r
 106  * semphr. h\r
 107  * <pre>SemaphoreHandle_t xSemaphoreCreateBinary( void )</pre>\r
 108  *\r
 109  * Creates a new binary semaphore instance, and returns a handle by which the\r
 110  * new semaphore can be referenced.\r
 111  *\r
 112  * In many usage scenarios it is faster and more memory efficient to use a\r
 113  * direct to task notification in place of a binary semaphore!\r
 114  * http://www.freertos.org/RTOS-task-notifications.html\r
 115  *\r
 116  * Internally, within the FreeRTOS implementation, binary semaphores use a block\r
 117  * of memory, in which the semaphore structure is stored.  If a binary semaphore\r
 118  * is created using xSemaphoreCreateBinary() then the required memory is\r
 119  * automatically dynamically allocated inside the xSemaphoreCreateBinary()\r
 120  * function.  (see http://www.freertos.org/a00111.html).  If a binary semaphore\r
 121  * is created using xSemaphoreCreateBinaryStatic() then the application writer\r
 122  * must provide the memory.  xSemaphoreCreateBinaryStatic() therefore allows a\r
 123  * binary semaphore to be created without using any dynamic memory allocation.\r
 124  *\r
 125  * The old vSemaphoreCreateBinary() macro is now deprecated in favour of this\r
 126  * xSemaphoreCreateBinary() function.  Note that binary semaphores created using\r
 127  * the vSemaphoreCreateBinary() macro are created in a state such that the\r
 128  * first call to 'take' the semaphore would pass, whereas binary semaphores\r
 129  * created using xSemaphoreCreateBinary() are created in a state such that the\r
 130  * the semaphore must first be 'given' before it can be 'taken'.\r
 131  *\r
 132  * This type of semaphore can be used for pure synchronisation between tasks or\r
 133  * between an interrupt and a task.  The semaphore need not be given back once\r
 134  * obtained, so one task/interrupt can continuously 'give' the semaphore while\r
 135  * another continuously 'takes' the semaphore.  For this reason this type of\r
 136  * semaphore does not use a priority inheritance mechanism.  For an alternative\r
 137  * that does use priority inheritance see xSemaphoreCreateMutex().\r
 138  *\r
 139  * @return Handle to the created semaphore, or NULL if the memory required to\r
 140  * hold the semaphore's data structures could not be allocated.\r
 141  *\r
 142  * Example usage:\r
 143  <pre>\r
 144  SemaphoreHandle_t xSemaphore = NULL;\r
 145 \r
 146  void vATask( void * pvParameters )\r
 147  {\r
 148     // Semaphore cannot be used before a call to xSemaphoreCreateBinary().\r
 149     // This is a macro so pass the variable in directly.\r
 150     xSemaphore = xSemaphoreCreateBinary();\r
 151 \r
 152     if( xSemaphore != NULL )\r
 153     {\r
 154         // The semaphore was created successfully.\r
 155         // The semaphore can now be used.\r
 156     }\r
 157  }\r
 158  </pre>\r
 159  * \defgroup xSemaphoreCreateBinary xSemaphoreCreateBinary\r
 160  * \ingroup Semaphores\r
 161  */\r
 162 #if( configSUPPORT_DYNAMIC_ALLOCATION == 1 )\r
 163         #define xSemaphoreCreateBinary() xQueueGenericCreate( ( UBaseType_t ) 1, semSEMAPHORE_QUEUE_ITEM_LENGTH, queueQUEUE_TYPE_BINARY_SEMAPHORE )\r
 164 #endif\r
 165 \r
 166 /**\r
 167  * semphr. h\r
 168  * <pre>SemaphoreHandle_t xSemaphoreCreateBinaryStatic( StaticSemaphore_t *pxSemaphoreBuffer )</pre>\r
 169  *\r
 170  * Creates a new binary semaphore instance, and returns a handle by which the\r
 171  * new semaphore can be referenced.\r
 172  *\r
 173  * NOTE: In many usage scenarios it is faster and more memory efficient to use a\r
 174  * direct to task notification in place of a binary semaphore!\r
 175  * http://www.freertos.org/RTOS-task-notifications.html\r
 176  *\r
 177  * Internally, within the FreeRTOS implementation, binary semaphores use a block\r
 178  * of memory, in which the semaphore structure is stored.  If a binary semaphore\r
 179  * is created using xSemaphoreCreateBinary() then the required memory is\r
 180  * automatically dynamically allocated inside the xSemaphoreCreateBinary()\r
 181  * function.  (see http://www.freertos.org/a00111.html).  If a binary semaphore\r
 182  * is created using xSemaphoreCreateBinaryStatic() then the application writer\r
 183  * must provide the memory.  xSemaphoreCreateBinaryStatic() therefore allows a\r
 184  * binary semaphore to be created without using any dynamic memory allocation.\r
 185  *\r
 186  * This type of semaphore can be used for pure synchronisation between tasks or\r
 187  * between an interrupt and a task.  The semaphore need not be given back once\r
 188  * obtained, so one task/interrupt can continuously 'give' the semaphore while\r
 189  * another continuously 'takes' the semaphore.  For this reason this type of\r
 190  * semaphore does not use a priority inheritance mechanism.  For an alternative\r
 191  * that does use priority inheritance see xSemaphoreCreateMutex().\r
 192  *\r
 193  * @param pxSemaphoreBuffer Must point to a variable of type StaticSemaphore_t,\r
 194  * which will then be used to hold the semaphore's data structure, removing the\r
 195  * need for the memory to be allocated dynamically.\r
 196  *\r
 197  * @return If the semaphore is created then a handle to the created semaphore is\r
 198  * returned.  If pxSemaphoreBuffer is NULL then NULL is returned.\r
 199  *\r
 200  * Example usage:\r
 201  <pre>\r
 202  SemaphoreHandle_t xSemaphore = NULL;\r
 203  StaticSemaphore_t xSemaphoreBuffer;\r
 204 \r
 205  void vATask( void * pvParameters )\r
 206  {\r
 207     // Semaphore cannot be used before a call to xSemaphoreCreateBinary().\r
 208     // The semaphore's data structures will be placed in the xSemaphoreBuffer\r
 209     // variable, the address of which is passed into the function.  The\r
 210     // function's parameter is not NULL, so the function will not attempt any\r
 211     // dynamic memory allocation, and therefore the function will not return\r
 212     // return NULL.\r
 213     xSemaphore = xSemaphoreCreateBinary( &xSemaphoreBuffer );\r
 214 \r
 215     // Rest of task code goes here.\r
 216  }\r
 217  </pre>\r
 218  * \defgroup xSemaphoreCreateBinaryStatic xSemaphoreCreateBinaryStatic\r
 219  * \ingroup Semaphores\r
 220  */\r
 221 #if( configSUPPORT_STATIC_ALLOCATION == 1 )\r
 222         #define xSemaphoreCreateBinaryStatic( pxStaticSemaphore ) xQueueGenericCreateStatic( ( UBaseType_t ) 1, semSEMAPHORE_QUEUE_ITEM_LENGTH, NULL, pxStaticSemaphore, queueQUEUE_TYPE_BINARY_SEMAPHORE )\r
 223 #endif /* configSUPPORT_STATIC_ALLOCATION */\r
 224 \r
 225 /**\r
 226  * semphr. h\r
 227  * <pre>xSemaphoreTake(\r
 228  *                   SemaphoreHandle_t xSemaphore,\r
 229  *                   TickType_t xBlockTime\r
 230  *               )</pre>\r
 231  *\r
 232  * <i>Macro</i> to obtain a semaphore.  The semaphore must have previously been\r
 233  * created with a call to xSemaphoreCreateBinary(), xSemaphoreCreateMutex() or\r
 234  * xSemaphoreCreateCounting().\r
 235  *\r
 236  * @param xSemaphore A handle to the semaphore being taken - obtained when\r
 237  * the semaphore was created.\r
 238  *\r
 239  * @param xBlockTime The time in ticks to wait for the semaphore to become\r
 240  * available.  The macro portTICK_PERIOD_MS can be used to convert this to a\r
 241  * real time.  A block time of zero can be used to poll the semaphore.  A block\r
 242  * time of portMAX_DELAY can be used to block indefinitely (provided\r
 243  * INCLUDE_vTaskSuspend is set to 1 in FreeRTOSConfig.h).\r
 244  *\r
 245  * @return pdTRUE if the semaphore was obtained.  pdFALSE\r
 246  * if xBlockTime expired without the semaphore becoming available.\r
 247  *\r
 248  * Example usage:\r
 249  <pre>\r
 250  SemaphoreHandle_t xSemaphore = NULL;\r
 251 \r
 252  // A task that creates a semaphore.\r
 253  void vATask( void * pvParameters )\r
 254  {\r
 255     // Create the semaphore to guard a shared resource.\r
 256     xSemaphore = xSemaphoreCreateBinary();\r
 257  }\r
 258 \r
 259  // A task that uses the semaphore.\r
 260  void vAnotherTask( void * pvParameters )\r
 261  {\r
 262     // ... Do other things.\r
 263 \r
 264     if( xSemaphore != NULL )\r
 265     {\r
 266         // See if we can obtain the semaphore.  If the semaphore is not available\r
 267         // wait 10 ticks to see if it becomes free.\r
 268         if( xSemaphoreTake( xSemaphore, ( TickType_t ) 10 ) == pdTRUE )\r
 269         {\r
 270             // We were able to obtain the semaphore and can now access the\r
 271             // shared resource.\r
 272 \r
 273             // ...\r
 274 \r
 275             // We have finished accessing the shared resource.  Release the\r
 276             // semaphore.\r
 277             xSemaphoreGive( xSemaphore );\r
 278         }\r
 279         else\r
 280         {\r
 281             // We could not obtain the semaphore and can therefore not access\r
 282             // the shared resource safely.\r
 283         }\r
 284     }\r
 285  }\r
 286  </pre>\r
 287  * \defgroup xSemaphoreTake xSemaphoreTake\r
 288  * \ingroup Semaphores\r
 289  */\r
 290 #define xSemaphoreTake( xSemaphore, xBlockTime )                xQueueSemaphoreTake( ( xSemaphore ), ( xBlockTime ) )\r
 291 \r
 292 /**\r
 293  * semphr. h\r
 294  * xSemaphoreTakeRecursive(\r
 295  *                          SemaphoreHandle_t xMutex,\r
 296  *                          TickType_t xBlockTime\r
 297  *                        )\r
 298  *\r
 299  * <i>Macro</i> to recursively obtain, or 'take', a mutex type semaphore.\r
 300  * The mutex must have previously been created using a call to\r
 301  * xSemaphoreCreateRecursiveMutex();\r
 302  *\r
 303  * configUSE_RECURSIVE_MUTEXES must be set to 1 in FreeRTOSConfig.h for this\r
 304  * macro to be available.\r
 305  *\r
 306  * This macro must not be used on mutexes created using xSemaphoreCreateMutex().\r
 307  *\r
 308  * A mutex used recursively can be 'taken' repeatedly by the owner. The mutex\r
 309  * doesn't become available again until the owner has called\r
 310  * xSemaphoreGiveRecursive() for each successful 'take' request.  For example,\r
 311  * if a task successfully 'takes' the same mutex 5 times then the mutex will\r
 312  * not be available to any other task until it has also  'given' the mutex back\r
 313  * exactly five times.\r
 314  *\r
 315  * @param xMutex A handle to the mutex being obtained.  This is the\r
 316  * handle returned by xSemaphoreCreateRecursiveMutex();\r
 317  *\r
 318  * @param xBlockTime The time in ticks to wait for the semaphore to become\r
 319  * available.  The macro portTICK_PERIOD_MS can be used to convert this to a\r
 320  * real time.  A block time of zero can be used to poll the semaphore.  If\r
 321  * the task already owns the semaphore then xSemaphoreTakeRecursive() will\r
 322  * return immediately no matter what the value of xBlockTime.\r
 323  *\r
 324  * @return pdTRUE if the semaphore was obtained.  pdFALSE if xBlockTime\r
 325  * expired without the semaphore becoming available.\r
 326  *\r
 327  * Example usage:\r
 328  <pre>\r
 329  SemaphoreHandle_t xMutex = NULL;\r
 330 \r
 331  // A task that creates a mutex.\r
 332  void vATask( void * pvParameters )\r
 333  {\r
 334     // Create the mutex to guard a shared resource.\r
 335     xMutex = xSemaphoreCreateRecursiveMutex();\r
 336  }\r
 337 \r
 338  // A task that uses the mutex.\r
 339  void vAnotherTask( void * pvParameters )\r
 340  {\r
 341     // ... Do other things.\r
 342 \r
 343     if( xMutex != NULL )\r
 344     {\r
 345         // See if we can obtain the mutex.  If the mutex is not available\r
 346         // wait 10 ticks to see if it becomes free.\r
 347         if( xSemaphoreTakeRecursive( xSemaphore, ( TickType_t ) 10 ) == pdTRUE )\r
 348         {\r
 349             // We were able to obtain the mutex and can now access the\r
 350             // shared resource.\r
 351 \r
 352             // ...\r
 353             // For some reason due to the nature of the code further calls to\r
 354             // xSemaphoreTakeRecursive() are made on the same mutex.  In real\r
 355             // code these would not be just sequential calls as this would make\r
 356             // no sense.  Instead the calls are likely to be buried inside\r
 357             // a more complex call structure.\r
 358             xSemaphoreTakeRecursive( xMutex, ( TickType_t ) 10 );\r
 359             xSemaphoreTakeRecursive( xMutex, ( TickType_t ) 10 );\r
 360 \r
 361             // The mutex has now been 'taken' three times, so will not be\r
 362             // available to another task until it has also been given back\r
 363             // three times.  Again it is unlikely that real code would have\r
 364             // these calls sequentially, but instead buried in a more complex\r
 365             // call structure.  This is just for illustrative purposes.\r
 366             xSemaphoreGiveRecursive( xMutex );\r
 367             xSemaphoreGiveRecursive( xMutex );\r
 368             xSemaphoreGiveRecursive( xMutex );\r
 369 \r
 370             // Now the mutex can be taken by other tasks.\r
 371         }\r
 372         else\r
 373         {\r
 374             // We could not obtain the mutex and can therefore not access\r
 375             // the shared resource safely.\r
 376         }\r
 377     }\r
 378  }\r
 379  </pre>\r
 380  * \defgroup xSemaphoreTakeRecursive xSemaphoreTakeRecursive\r
 381  * \ingroup Semaphores\r
 382  */\r
 383 #if( configUSE_RECURSIVE_MUTEXES == 1 )\r
 384         #define xSemaphoreTakeRecursive( xMutex, xBlockTime )   xQueueTakeMutexRecursive( ( xMutex ), ( xBlockTime ) )\r
 385 #endif\r
 386 \r
 387 /**\r
 388  * semphr. h\r
 389  * <pre>xSemaphoreGive( SemaphoreHandle_t xSemaphore )</pre>\r
 390  *\r
 391  * <i>Macro</i> to release a semaphore.  The semaphore must have previously been\r
 392  * created with a call to xSemaphoreCreateBinary(), xSemaphoreCreateMutex() or\r
 393  * xSemaphoreCreateCounting(). and obtained using sSemaphoreTake().\r
 394  *\r
 395  * This macro must not be used from an ISR.  See xSemaphoreGiveFromISR () for\r
 396  * an alternative which can be used from an ISR.\r
 397  *\r
 398  * This macro must also not be used on semaphores created using\r
 399  * xSemaphoreCreateRecursiveMutex().\r
 400  *\r
 401  * @param xSemaphore A handle to the semaphore being released.  This is the\r
 402  * handle returned when the semaphore was created.\r
 403  *\r
 404  * @return pdTRUE if the semaphore was released.  pdFALSE if an error occurred.\r
 405  * Semaphores are implemented using queues.  An error can occur if there is\r
 406  * no space on the queue to post a message - indicating that the\r
 407  * semaphore was not first obtained correctly.\r
 408  *\r
 409  * Example usage:\r
 410  <pre>\r
 411  SemaphoreHandle_t xSemaphore = NULL;\r
 412 \r
 413  void vATask( void * pvParameters )\r
 414  {\r
 415     // Create the semaphore to guard a shared resource.\r
 416     xSemaphore = vSemaphoreCreateBinary();\r
 417 \r
 418     if( xSemaphore != NULL )\r
 419     {\r
 420         if( xSemaphoreGive( xSemaphore ) != pdTRUE )\r
 421         {\r
 422             // We would expect this call to fail because we cannot give\r
 423             // a semaphore without first "taking" it!\r
 424         }\r
 425 \r
 426         // Obtain the semaphore - don't block if the semaphore is not\r
 427         // immediately available.\r
 428         if( xSemaphoreTake( xSemaphore, ( TickType_t ) 0 ) )\r
 429         {\r
 430             // We now have the semaphore and can access the shared resource.\r
 431 \r
 432             // ...\r
 433 \r
 434             // We have finished accessing the shared resource so can free the\r
 435             // semaphore.\r
 436             if( xSemaphoreGive( xSemaphore ) != pdTRUE )\r
 437             {\r
 438                 // We would not expect this call to fail because we must have\r
 439                 // obtained the semaphore to get here.\r
 440             }\r
 441         }\r
 442     }\r
 443  }\r
 444  </pre>\r
 445  * \defgroup xSemaphoreGive xSemaphoreGive\r
 446  * \ingroup Semaphores\r
 447  */\r
 448 #define xSemaphoreGive( xSemaphore )            xQueueGenericSend( ( QueueHandle_t ) ( xSemaphore ), NULL, semGIVE_BLOCK_TIME, queueSEND_TO_BACK )\r
 449 \r
 450 /**\r
 451  * semphr. h\r
 452  * <pre>xSemaphoreGiveRecursive( SemaphoreHandle_t xMutex )</pre>\r
 453  *\r
 454  * <i>Macro</i> to recursively release, or 'give', a mutex type semaphore.\r
 455  * The mutex must have previously been created using a call to\r
 456  * xSemaphoreCreateRecursiveMutex();\r
 457  *\r
 458  * configUSE_RECURSIVE_MUTEXES must be set to 1 in FreeRTOSConfig.h for this\r
 459  * macro to be available.\r
 460  *\r
 461  * This macro must not be used on mutexes created using xSemaphoreCreateMutex().\r
 462  *\r
 463  * A mutex used recursively can be 'taken' repeatedly by the owner. The mutex\r
 464  * doesn't become available again until the owner has called\r
 465  * xSemaphoreGiveRecursive() for each successful 'take' request.  For example,\r
 466  * if a task successfully 'takes' the same mutex 5 times then the mutex will\r
 467  * not be available to any other task until it has also  'given' the mutex back\r
 468  * exactly five times.\r
 469  *\r
 470  * @param xMutex A handle to the mutex being released, or 'given'.  This is the\r
 471  * handle returned by xSemaphoreCreateMutex();\r
 472  *\r
 473  * @return pdTRUE if the semaphore was given.\r
 474  *\r
 475  * Example usage:\r
 476  <pre>\r
 477  SemaphoreHandle_t xMutex = NULL;\r
 478 \r
 479  // A task that creates a mutex.\r
 480  void vATask( void * pvParameters )\r
 481  {\r
 482     // Create the mutex to guard a shared resource.\r
 483     xMutex = xSemaphoreCreateRecursiveMutex();\r
 484  }\r
 485 \r
 486  // A task that uses the mutex.\r
 487  void vAnotherTask( void * pvParameters )\r
 488  {\r
 489     // ... Do other things.\r
 490 \r
 491     if( xMutex != NULL )\r
 492     {\r
 493         // See if we can obtain the mutex.  If the mutex is not available\r
 494         // wait 10 ticks to see if it becomes free.\r
 495         if( xSemaphoreTakeRecursive( xMutex, ( TickType_t ) 10 ) == pdTRUE )\r
 496         {\r
 497             // We were able to obtain the mutex and can now access the\r
 498             // shared resource.\r
 499 \r
 500             // ...\r
 501             // For some reason due to the nature of the code further calls to\r
 502                         // xSemaphoreTakeRecursive() are made on the same mutex.  In real\r
 503                         // code these would not be just sequential calls as this would make\r
 504                         // no sense.  Instead the calls are likely to be buried inside\r
 505                         // a more complex call structure.\r
 506             xSemaphoreTakeRecursive( xMutex, ( TickType_t ) 10 );\r
 507             xSemaphoreTakeRecursive( xMutex, ( TickType_t ) 10 );\r
 508 \r
 509             // The mutex has now been 'taken' three times, so will not be\r
 510                         // available to another task until it has also been given back\r
 511                         // three times.  Again it is unlikely that real code would have\r
 512                         // these calls sequentially, it would be more likely that the calls\r
 513                         // to xSemaphoreGiveRecursive() would be called as a call stack\r
 514                         // unwound.  This is just for demonstrative purposes.\r
 515             xSemaphoreGiveRecursive( xMutex );\r
 516                         xSemaphoreGiveRecursive( xMutex );\r
 517                         xSemaphoreGiveRecursive( xMutex );\r
 518 \r
 519                         // Now the mutex can be taken by other tasks.\r
 520         }\r
 521         else\r
 522         {\r
 523             // We could not obtain the mutex and can therefore not access\r
 524             // the shared resource safely.\r
 525         }\r
 526     }\r
 527  }\r
 528  </pre>\r
 529  * \defgroup xSemaphoreGiveRecursive xSemaphoreGiveRecursive\r
 530  * \ingroup Semaphores\r
 531  */\r
 532 #if( configUSE_RECURSIVE_MUTEXES == 1 )\r
 533         #define xSemaphoreGiveRecursive( xMutex )       xQueueGiveMutexRecursive( ( xMutex ) )\r
 534 #endif\r
 535 \r
 536 /**\r
 537  * semphr. h\r
 538  * <pre>\r
 539  xSemaphoreGiveFromISR(\r
 540                           SemaphoreHandle_t xSemaphore,\r
 541                           BaseType_t *pxHigherPriorityTaskWoken\r
 542                       )</pre>\r
 543  *\r
 544  * <i>Macro</i> to  release a semaphore.  The semaphore must have previously been\r
 545  * created with a call to xSemaphoreCreateBinary() or xSemaphoreCreateCounting().\r
 546  *\r
 547  * Mutex type semaphores (those created using a call to xSemaphoreCreateMutex())\r
 548  * must not be used with this macro.\r
 549  *\r
 550  * This macro can be used from an ISR.\r
 551  *\r
 552  * @param xSemaphore A handle to the semaphore being released.  This is the\r
 553  * handle returned when the semaphore was created.\r
 554  *\r
 555  * @param pxHigherPriorityTaskWoken xSemaphoreGiveFromISR() will set\r
 556  * *pxHigherPriorityTaskWoken to pdTRUE if giving the semaphore caused a task\r
 557  * to unblock, and the unblocked task has a priority higher than the currently\r
 558  * running task.  If xSemaphoreGiveFromISR() sets this value to pdTRUE then\r
 559  * a context switch should be requested before the interrupt is exited.\r
 560  *\r
 561  * @return pdTRUE if the semaphore was successfully given, otherwise errQUEUE_FULL.\r
 562  *\r
 563  * Example usage:\r
 564  <pre>\r
 565  \#define LONG_TIME 0xffff\r
 566  \#define TICKS_TO_WAIT 10\r
 567  SemaphoreHandle_t xSemaphore = NULL;\r
 568 \r
 569  // Repetitive task.\r
 570  void vATask( void * pvParameters )\r
 571  {\r
 572     for( ;; )\r
 573     {\r
 574         // We want this task to run every 10 ticks of a timer.  The semaphore\r
 575         // was created before this task was started.\r
 576 \r
 577         // Block waiting for the semaphore to become available.\r
 578         if( xSemaphoreTake( xSemaphore, LONG_TIME ) == pdTRUE )\r
 579         {\r
 580             // It is time to execute.\r
 581 \r
 582             // ...\r
 583 \r
 584             // We have finished our task.  Return to the top of the loop where\r
 585             // we will block on the semaphore until it is time to execute\r
 586             // again.  Note when using the semaphore for synchronisation with an\r
 587                         // ISR in this manner there is no need to 'give' the semaphore back.\r
 588         }\r
 589     }\r
 590  }\r
 591 \r
 592  // Timer ISR\r
 593  void vTimerISR( void * pvParameters )\r
 594  {\r
 595  static uint8_t ucLocalTickCount = 0;\r
 596  static BaseType_t xHigherPriorityTaskWoken;\r
 597 \r
 598     // A timer tick has occurred.\r
 599 \r
 600     // ... Do other time functions.\r
 601 \r
 602     // Is it time for vATask () to run?\r
 603         xHigherPriorityTaskWoken = pdFALSE;\r
 604     ucLocalTickCount++;\r
 605     if( ucLocalTickCount >= TICKS_TO_WAIT )\r
 606     {\r
 607         // Unblock the task by releasing the semaphore.\r
 608         xSemaphoreGiveFromISR( xSemaphore, &xHigherPriorityTaskWoken );\r
 609 \r
 610         // Reset the count so we release the semaphore again in 10 ticks time.\r
 611         ucLocalTickCount = 0;\r
 612     }\r
 613 \r
 614     if( xHigherPriorityTaskWoken != pdFALSE )\r
 615     {\r
 616         // We can force a context switch here.  Context switching from an\r
 617         // ISR uses port specific syntax.  Check the demo task for your port\r
 618         // to find the syntax required.\r
 619     }\r
 620  }\r
 621  </pre>\r
 622  * \defgroup xSemaphoreGiveFromISR xSemaphoreGiveFromISR\r
 623  * \ingroup Semaphores\r
 624  */\r
 625 #define xSemaphoreGiveFromISR( xSemaphore, pxHigherPriorityTaskWoken )  xQueueGiveFromISR( ( QueueHandle_t ) ( xSemaphore ), ( pxHigherPriorityTaskWoken ) )\r
 626 \r
 627 /**\r
 628  * semphr. h\r
 629  * <pre>\r
 630  xSemaphoreTakeFromISR(\r
 631                           SemaphoreHandle_t xSemaphore,\r
 632                           BaseType_t *pxHigherPriorityTaskWoken\r
 633                       )</pre>\r
 634  *\r
 635  * <i>Macro</i> to  take a semaphore from an ISR.  The semaphore must have\r
 636  * previously been created with a call to xSemaphoreCreateBinary() or\r
 637  * xSemaphoreCreateCounting().\r
 638  *\r
 639  * Mutex type semaphores (those created using a call to xSemaphoreCreateMutex())\r
 640  * must not be used with this macro.\r
 641  *\r
 642  * This macro can be used from an ISR, however taking a semaphore from an ISR\r
 643  * is not a common operation.  It is likely to only be useful when taking a\r
 644  * counting semaphore when an interrupt is obtaining an object from a resource\r
 645  * pool (when the semaphore count indicates the number of resources available).\r
 646  *\r
 647  * @param xSemaphore A handle to the semaphore being taken.  This is the\r
 648  * handle returned when the semaphore was created.\r
 649  *\r
 650  * @param pxHigherPriorityTaskWoken xSemaphoreTakeFromISR() will set\r
 651  * *pxHigherPriorityTaskWoken to pdTRUE if taking the semaphore caused a task\r
 652  * to unblock, and the unblocked task has a priority higher than the currently\r
 653  * running task.  If xSemaphoreTakeFromISR() sets this value to pdTRUE then\r
 654  * a context switch should be requested before the interrupt is exited.\r
 655  *\r
 656  * @return pdTRUE if the semaphore was successfully taken, otherwise\r
 657  * pdFALSE\r
 658  */\r
 659 #define xSemaphoreTakeFromISR( xSemaphore, pxHigherPriorityTaskWoken )  xQueueReceiveFromISR( ( QueueHandle_t ) ( xSemaphore ), NULL, ( pxHigherPriorityTaskWoken ) )\r
 660 \r
 661 /**\r
 662  * semphr. h\r
 663  * <pre>SemaphoreHandle_t xSemaphoreCreateMutex( void )</pre>\r
 664  *\r
 665  * Creates a new mutex type semaphore instance, and returns a handle by which\r
 666  * the new mutex can be referenced.\r
 667  *\r
 668  * Internally, within the FreeRTOS implementation, mutex semaphores use a block\r
 669  * of memory, in which the mutex structure is stored.  If a mutex is created\r
 670  * using xSemaphoreCreateMutex() then the required memory is automatically\r
 671  * dynamically allocated inside the xSemaphoreCreateMutex() function.  (see\r
 672  * http://www.freertos.org/a00111.html).  If a mutex is created using\r
 673  * xSemaphoreCreateMutexStatic() then the application writer must provided the\r
 674  * memory.  xSemaphoreCreateMutexStatic() therefore allows a mutex to be created\r
 675  * without using any dynamic memory allocation.\r
 676  *\r
 677  * Mutexes created using this function can be accessed using the xSemaphoreTake()\r
 678  * and xSemaphoreGive() macros.  The xSemaphoreTakeRecursive() and\r
 679  * xSemaphoreGiveRecursive() macros must not be used.\r
 680  *\r
 681  * This type of semaphore uses a priority inheritance mechanism so a task\r
 682  * 'taking' a semaphore MUST ALWAYS 'give' the semaphore back once the\r
 683  * semaphore it is no longer required.\r
 684  *\r
 685  * Mutex type semaphores cannot be used from within interrupt service routines.\r
 686  *\r
 687  * See xSemaphoreCreateBinary() for an alternative implementation that can be\r
 688  * used for pure synchronisation (where one task or interrupt always 'gives' the\r
 689  * semaphore and another always 'takes' the semaphore) and from within interrupt\r
 690  * service routines.\r
 691  *\r
 692  * @return If the mutex was successfully created then a handle to the created\r
 693  * semaphore is returned.  If there was not enough heap to allocate the mutex\r
 694  * data structures then NULL is returned.\r
 695  *\r
 696  * Example usage:\r
 697  <pre>\r
 698  SemaphoreHandle_t xSemaphore;\r
 699 \r
 700  void vATask( void * pvParameters )\r
 701  {\r
 702     // Semaphore cannot be used before a call to xSemaphoreCreateMutex().\r
 703     // This is a macro so pass the variable in directly.\r
 704     xSemaphore = xSemaphoreCreateMutex();\r
 705 \r
 706     if( xSemaphore != NULL )\r
 707     {\r
 708         // The semaphore was created successfully.\r
 709         // The semaphore can now be used.\r
 710     }\r
 711  }\r
 712  </pre>\r
 713  * \defgroup xSemaphoreCreateMutex xSemaphoreCreateMutex\r
 714  * \ingroup Semaphores\r
 715  */\r
 716 #if( configSUPPORT_DYNAMIC_ALLOCATION == 1 )\r
 717         #define xSemaphoreCreateMutex() xQueueCreateMutex( queueQUEUE_TYPE_MUTEX )\r
 718 #endif\r
 719 \r
 720 /**\r
 721  * semphr. h\r
 722  * <pre>SemaphoreHandle_t xSemaphoreCreateMutexStatic( StaticSemaphore_t *pxMutexBuffer )</pre>\r
 723  *\r
 724  * Creates a new mutex type semaphore instance, and returns a handle by which\r
 725  * the new mutex can be referenced.\r
 726  *\r
 727  * Internally, within the FreeRTOS implementation, mutex semaphores use a block\r
 728  * of memory, in which the mutex structure is stored.  If a mutex is created\r
 729  * using xSemaphoreCreateMutex() then the required memory is automatically\r
 730  * dynamically allocated inside the xSemaphoreCreateMutex() function.  (see\r
 731  * http://www.freertos.org/a00111.html).  If a mutex is created using\r
 732  * xSemaphoreCreateMutexStatic() then the application writer must provided the\r
 733  * memory.  xSemaphoreCreateMutexStatic() therefore allows a mutex to be created\r
 734  * without using any dynamic memory allocation.\r
 735  *\r
 736  * Mutexes created using this function can be accessed using the xSemaphoreTake()\r
 737  * and xSemaphoreGive() macros.  The xSemaphoreTakeRecursive() and\r
 738  * xSemaphoreGiveRecursive() macros must not be used.\r
 739  *\r
 740  * This type of semaphore uses a priority inheritance mechanism so a task\r
 741  * 'taking' a semaphore MUST ALWAYS 'give' the semaphore back once the\r
 742  * semaphore it is no longer required.\r
 743  *\r
 744  * Mutex type semaphores cannot be used from within interrupt service routines.\r
 745  *\r
 746  * See xSemaphoreCreateBinary() for an alternative implementation that can be\r
 747  * used for pure synchronisation (where one task or interrupt always 'gives' the\r
 748  * semaphore and another always 'takes' the semaphore) and from within interrupt\r
 749  * service routines.\r
 750  *\r
 751  * @param pxMutexBuffer Must point to a variable of type StaticSemaphore_t,\r
 752  * which will be used to hold the mutex's data structure, removing the need for\r
 753  * the memory to be allocated dynamically.\r
 754  *\r
 755  * @return If the mutex was successfully created then a handle to the created\r
 756  * mutex is returned.  If pxMutexBuffer was NULL then NULL is returned.\r
 757  *\r
 758  * Example usage:\r
 759  <pre>\r
 760  SemaphoreHandle_t xSemaphore;\r
 761  StaticSemaphore_t xMutexBuffer;\r
 762 \r
 763  void vATask( void * pvParameters )\r
 764  {\r
 765     // A mutex cannot be used before it has been created.  xMutexBuffer is\r
 766     // into xSemaphoreCreateMutexStatic() so no dynamic memory allocation is\r
 767     // attempted.\r
 768     xSemaphore = xSemaphoreCreateMutexStatic( &xMutexBuffer );\r
 769 \r
 770     // As no dynamic memory allocation was performed, xSemaphore cannot be NULL,\r
 771     // so there is no need to check it.\r
 772  }\r
 773  </pre>\r
 774  * \defgroup xSemaphoreCreateMutexStatic xSemaphoreCreateMutexStatic\r
 775  * \ingroup Semaphores\r
 776  */\r
 777  #if( configSUPPORT_STATIC_ALLOCATION == 1 )\r
 778         #define xSemaphoreCreateMutexStatic( pxMutexBuffer ) xQueueCreateMutexStatic( queueQUEUE_TYPE_MUTEX, ( pxMutexBuffer ) )\r
 779 #endif /* configSUPPORT_STATIC_ALLOCATION */\r
 780 \r
 781 \r
 782 /**\r
 783  * semphr. h\r
 784  * <pre>SemaphoreHandle_t xSemaphoreCreateRecursiveMutex( void )</pre>\r
 785  *\r
 786  * Creates a new recursive mutex type semaphore instance, and returns a handle\r
 787  * by which the new recursive mutex can be referenced.\r
 788  *\r
 789  * Internally, within the FreeRTOS implementation, recursive mutexs use a block\r
 790  * of memory, in which the mutex structure is stored.  If a recursive mutex is\r
 791  * created using xSemaphoreCreateRecursiveMutex() then the required memory is\r
 792  * automatically dynamically allocated inside the\r
 793  * xSemaphoreCreateRecursiveMutex() function.  (see\r
 794  * http://www.freertos.org/a00111.html).  If a recursive mutex is created using\r
 795  * xSemaphoreCreateRecursiveMutexStatic() then the application writer must\r
 796  * provide the memory that will get used by the mutex.\r
 797  * xSemaphoreCreateRecursiveMutexStatic() therefore allows a recursive mutex to\r
 798  * be created without using any dynamic memory allocation.\r
 799  *\r
 800  * Mutexes created using this macro can be accessed using the\r
 801  * xSemaphoreTakeRecursive() and xSemaphoreGiveRecursive() macros.  The\r
 802  * xSemaphoreTake() and xSemaphoreGive() macros must not be used.\r
 803  *\r
 804  * A mutex used recursively can be 'taken' repeatedly by the owner. The mutex\r
 805  * doesn't become available again until the owner has called\r
 806  * xSemaphoreGiveRecursive() for each successful 'take' request.  For example,\r
 807  * if a task successfully 'takes' the same mutex 5 times then the mutex will\r
 808  * not be available to any other task until it has also  'given' the mutex back\r
 809  * exactly five times.\r
 810  *\r
 811  * This type of semaphore uses a priority inheritance mechanism so a task\r
 812  * 'taking' a semaphore MUST ALWAYS 'give' the semaphore back once the\r
 813  * semaphore it is no longer required.\r
 814  *\r
 815  * Mutex type semaphores cannot be used from within interrupt service routines.\r
 816  *\r
 817  * See xSemaphoreCreateBinary() for an alternative implementation that can be\r
 818  * used for pure synchronisation (where one task or interrupt always 'gives' the\r
 819  * semaphore and another always 'takes' the semaphore) and from within interrupt\r
 820  * service routines.\r
 821  *\r
 822  * @return xSemaphore Handle to the created mutex semaphore.  Should be of type\r
 823  * SemaphoreHandle_t.\r
 824  *\r
 825  * Example usage:\r
 826  <pre>\r
 827  SemaphoreHandle_t xSemaphore;\r
 828 \r
 829  void vATask( void * pvParameters )\r
 830  {\r
 831     // Semaphore cannot be used before a call to xSemaphoreCreateMutex().\r
 832     // This is a macro so pass the variable in directly.\r
 833     xSemaphore = xSemaphoreCreateRecursiveMutex();\r
 834 \r
 835     if( xSemaphore != NULL )\r
 836     {\r
 837         // The semaphore was created successfully.\r
 838         // The semaphore can now be used.\r
 839     }\r
 840  }\r
 841  </pre>\r
 842  * \defgroup xSemaphoreCreateRecursiveMutex xSemaphoreCreateRecursiveMutex\r
 843  * \ingroup Semaphores\r
 844  */\r
 845 #if( ( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) && ( configUSE_RECURSIVE_MUTEXES == 1 ) )\r
 846         #define xSemaphoreCreateRecursiveMutex() xQueueCreateMutex( queueQUEUE_TYPE_RECURSIVE_MUTEX )\r
 847 #endif\r
 848 \r
 849 /**\r
 850  * semphr. h\r
 851  * <pre>SemaphoreHandle_t xSemaphoreCreateRecursiveMutexStatic( StaticSemaphore_t *pxMutexBuffer )</pre>\r
 852  *\r
 853  * Creates a new recursive mutex type semaphore instance, and returns a handle\r
 854  * by which the new recursive mutex can be referenced.\r
 855  *\r
 856  * Internally, within the FreeRTOS implementation, recursive mutexs use a block\r
 857  * of memory, in which the mutex structure is stored.  If a recursive mutex is\r
 858  * created using xSemaphoreCreateRecursiveMutex() then the required memory is\r
 859  * automatically dynamically allocated inside the\r
 860  * xSemaphoreCreateRecursiveMutex() function.  (see\r
 861  * http://www.freertos.org/a00111.html).  If a recursive mutex is created using\r
 862  * xSemaphoreCreateRecursiveMutexStatic() then the application writer must\r
 863  * provide the memory that will get used by the mutex.\r
 864  * xSemaphoreCreateRecursiveMutexStatic() therefore allows a recursive mutex to\r
 865  * be created without using any dynamic memory allocation.\r
 866  *\r
 867  * Mutexes created using this macro can be accessed using the\r
 868  * xSemaphoreTakeRecursive() and xSemaphoreGiveRecursive() macros.  The\r
 869  * xSemaphoreTake() and xSemaphoreGive() macros must not be used.\r
 870  *\r
 871  * A mutex used recursively can be 'taken' repeatedly by the owner. The mutex\r
 872  * doesn't become available again until the owner has called\r
 873  * xSemaphoreGiveRecursive() for each successful 'take' request.  For example,\r
 874  * if a task successfully 'takes' the same mutex 5 times then the mutex will\r
 875  * not be available to any other task until it has also  'given' the mutex back\r
 876  * exactly five times.\r
 877  *\r
 878  * This type of semaphore uses a priority inheritance mechanism so a task\r
 879  * 'taking' a semaphore MUST ALWAYS 'give' the semaphore back once the\r
 880  * semaphore it is no longer required.\r
 881  *\r
 882  * Mutex type semaphores cannot be used from within interrupt service routines.\r
 883  *\r
 884  * See xSemaphoreCreateBinary() for an alternative implementation that can be\r
 885  * used for pure synchronisation (where one task or interrupt always 'gives' the\r
 886  * semaphore and another always 'takes' the semaphore) and from within interrupt\r
 887  * service routines.\r
 888  *\r
 889  * @param pxMutexBuffer Must point to a variable of type StaticSemaphore_t,\r
 890  * which will then be used to hold the recursive mutex's data structure,\r
 891  * removing the need for the memory to be allocated dynamically.\r
 892  *\r
 893  * @return If the recursive mutex was successfully created then a handle to the\r
 894  * created recursive mutex is returned.  If pxMutexBuffer was NULL then NULL is\r
 895  * returned.\r
 896  *\r
 897  * Example usage:\r
 898  <pre>\r
 899  SemaphoreHandle_t xSemaphore;\r
 900  StaticSemaphore_t xMutexBuffer;\r
 901 \r
 902  void vATask( void * pvParameters )\r
 903  {\r
 904     // A recursive semaphore cannot be used before it is created.  Here a\r
 905     // recursive mutex is created using xSemaphoreCreateRecursiveMutexStatic().\r
 906     // The address of xMutexBuffer is passed into the function, and will hold\r
 907     // the mutexes data structures - so no dynamic memory allocation will be\r
 908     // attempted.\r
 909     xSemaphore = xSemaphoreCreateRecursiveMutexStatic( &xMutexBuffer );\r
 910 \r
 911     // As no dynamic memory allocation was performed, xSemaphore cannot be NULL,\r
 912     // so there is no need to check it.\r
 913  }\r
 914  </pre>\r
 915  * \defgroup xSemaphoreCreateRecursiveMutexStatic xSemaphoreCreateRecursiveMutexStatic\r
 916  * \ingroup Semaphores\r
 917  */\r
 918 #if( ( configSUPPORT_STATIC_ALLOCATION == 1 ) && ( configUSE_RECURSIVE_MUTEXES == 1 ) )\r
 919         #define xSemaphoreCreateRecursiveMutexStatic( pxStaticSemaphore ) xQueueCreateMutexStatic( queueQUEUE_TYPE_RECURSIVE_MUTEX, pxStaticSemaphore )\r
 920 #endif /* configSUPPORT_STATIC_ALLOCATION */\r
 921 \r
 922 /**\r
 923  * semphr. h\r
 924  * <pre>SemaphoreHandle_t xSemaphoreCreateCounting( UBaseType_t uxMaxCount, UBaseType_t uxInitialCount )</pre>\r
 925  *\r
 926  * Creates a new counting semaphore instance, and returns a handle by which the\r
 927  * new counting semaphore can be referenced.\r
 928  *\r
 929  * In many usage scenarios it is faster and more memory efficient to use a\r
 930  * direct to task notification in place of a counting semaphore!\r
 931  * http://www.freertos.org/RTOS-task-notifications.html\r
 932  *\r
 933  * Internally, within the FreeRTOS implementation, counting semaphores use a\r
 934  * block of memory, in which the counting semaphore structure is stored.  If a\r
 935  * counting semaphore is created using xSemaphoreCreateCounting() then the\r
 936  * required memory is automatically dynamically allocated inside the\r
 937  * xSemaphoreCreateCounting() function.  (see\r
 938  * http://www.freertos.org/a00111.html).  If a counting semaphore is created\r
 939  * using xSemaphoreCreateCountingStatic() then the application writer can\r
 940  * instead optionally provide the memory that will get used by the counting\r
 941  * semaphore.  xSemaphoreCreateCountingStatic() therefore allows a counting\r
 942  * semaphore to be created without using any dynamic memory allocation.\r
 943  *\r
 944  * Counting semaphores are typically used for two things:\r
 945  *\r
 946  * 1) Counting events.\r
 947  *\r
 948  *    In this usage scenario an event handler will 'give' a semaphore each time\r
 949  *    an event occurs (incrementing the semaphore count value), and a handler\r
 950  *    task will 'take' a semaphore each time it processes an event\r
 951  *    (decrementing the semaphore count value).  The count value is therefore\r
 952  *    the difference between the number of events that have occurred and the\r
 953  *    number that have been processed.  In this case it is desirable for the\r
 954  *    initial count value to be zero.\r
 955  *\r
 956  * 2) Resource management.\r
 957  *\r
 958  *    In this usage scenario the count value indicates the number of resources\r
 959  *    available.  To obtain control of a resource a task must first obtain a\r
 960  *    semaphore - decrementing the semaphore count value.  When the count value\r
 961  *    reaches zero there are no free resources.  When a task finishes with the\r
 962  *    resource it 'gives' the semaphore back - incrementing the semaphore count\r
 963  *    value.  In this case it is desirable for the initial count value to be\r
 964  *    equal to the maximum count value, indicating that all resources are free.\r
 965  *\r
 966  * @param uxMaxCount The maximum count value that can be reached.  When the\r
 967  *        semaphore reaches this value it can no longer be 'given'.\r
 968  *\r
 969  * @param uxInitialCount The count value assigned to the semaphore when it is\r
 970  *        created.\r
 971  *\r
 972  * @return Handle to the created semaphore.  Null if the semaphore could not be\r
 973  *         created.\r
 974  *\r
 975  * Example usage:\r
 976  <pre>\r
 977  SemaphoreHandle_t xSemaphore;\r
 978 \r
 979  void vATask( void * pvParameters )\r
 980  {\r
 981  SemaphoreHandle_t xSemaphore = NULL;\r
 982 \r
 983     // Semaphore cannot be used before a call to xSemaphoreCreateCounting().\r
 984     // The max value to which the semaphore can count should be 10, and the\r
 985     // initial value assigned to the count should be 0.\r
 986     xSemaphore = xSemaphoreCreateCounting( 10, 0 );\r
 987 \r
 988     if( xSemaphore != NULL )\r
 989     {\r
 990         // The semaphore was created successfully.\r
 991         // The semaphore can now be used.\r
 992     }\r
 993  }\r
 994  </pre>\r
 995  * \defgroup xSemaphoreCreateCounting xSemaphoreCreateCounting\r
 996  * \ingroup Semaphores\r
 997  */\r
 998 #if( configSUPPORT_DYNAMIC_ALLOCATION == 1 )\r
 999         #define xSemaphoreCreateCounting( uxMaxCount, uxInitialCount ) xQueueCreateCountingSemaphore( ( uxMaxCount ), ( uxInitialCount ) )\r
1000 #endif\r
1001 \r
1002 /**\r
1003  * semphr. h\r
1004  * <pre>SemaphoreHandle_t xSemaphoreCreateCountingStatic( UBaseType_t uxMaxCount, UBaseType_t uxInitialCount, StaticSemaphore_t *pxSemaphoreBuffer )</pre>\r
1005  *\r
1006  * Creates a new counting semaphore instance, and returns a handle by which the\r
1007  * new counting semaphore can be referenced.\r
1008  *\r
1009  * In many usage scenarios it is faster and more memory efficient to use a\r
1010  * direct to task notification in place of a counting semaphore!\r
1011  * http://www.freertos.org/RTOS-task-notifications.html\r
1012  *\r
1013  * Internally, within the FreeRTOS implementation, counting semaphores use a\r
1014  * block of memory, in which the counting semaphore structure is stored.  If a\r
1015  * counting semaphore is created using xSemaphoreCreateCounting() then the\r
1016  * required memory is automatically dynamically allocated inside the\r
1017  * xSemaphoreCreateCounting() function.  (see\r
1018  * http://www.freertos.org/a00111.html).  If a counting semaphore is created\r
1019  * using xSemaphoreCreateCountingStatic() then the application writer must\r
1020  * provide the memory.  xSemaphoreCreateCountingStatic() therefore allows a\r
1021  * counting semaphore to be created without using any dynamic memory allocation.\r
1022  *\r
1023  * Counting semaphores are typically used for two things:\r
1024  *\r
1025  * 1) Counting events.\r
1026  *\r
1027  *    In this usage scenario an event handler will 'give' a semaphore each time\r
1028  *    an event occurs (incrementing the semaphore count value), and a handler\r
1029  *    task will 'take' a semaphore each time it processes an event\r
1030  *    (decrementing the semaphore count value).  The count value is therefore\r
1031  *    the difference between the number of events that have occurred and the\r
1032  *    number that have been processed.  In this case it is desirable for the\r
1033  *    initial count value to be zero.\r
1034  *\r
1035  * 2) Resource management.\r
1036  *\r
1037  *    In this usage scenario the count value indicates the number of resources\r
1038  *    available.  To obtain control of a resource a task must first obtain a\r
1039  *    semaphore - decrementing the semaphore count value.  When the count value\r
1040  *    reaches zero there are no free resources.  When a task finishes with the\r
1041  *    resource it 'gives' the semaphore back - incrementing the semaphore count\r
1042  *    value.  In this case it is desirable for the initial count value to be\r
1043  *    equal to the maximum count value, indicating that all resources are free.\r
1044  *\r
1045  * @param uxMaxCount The maximum count value that can be reached.  When the\r
1046  *        semaphore reaches this value it can no longer be 'given'.\r
1047  *\r
1048  * @param uxInitialCount The count value assigned to the semaphore when it is\r
1049  *        created.\r
1050  *\r
1051  * @param pxSemaphoreBuffer Must point to a variable of type StaticSemaphore_t,\r
1052  * which will then be used to hold the semaphore's data structure, removing the\r
1053  * need for the memory to be allocated dynamically.\r
1054  *\r
1055  * @return If the counting semaphore was successfully created then a handle to\r
1056  * the created counting semaphore is returned.  If pxSemaphoreBuffer was NULL\r
1057  * then NULL is returned.\r
1058  *\r
1059  * Example usage:\r
1060  <pre>\r
1061  SemaphoreHandle_t xSemaphore;\r
1062  StaticSemaphore_t xSemaphoreBuffer;\r
1063 \r
1064  void vATask( void * pvParameters )\r
1065  {\r
1066  SemaphoreHandle_t xSemaphore = NULL;\r
1067 \r
1068     // Counting semaphore cannot be used before they have been created.  Create\r
1069     // a counting semaphore using xSemaphoreCreateCountingStatic().  The max\r
1070     // value to which the semaphore can count is 10, and the initial value\r
1071     // assigned to the count will be 0.  The address of xSemaphoreBuffer is\r
1072     // passed in and will be used to hold the semaphore structure, so no dynamic\r
1073     // memory allocation will be used.\r
1074     xSemaphore = xSemaphoreCreateCounting( 10, 0, &xSemaphoreBuffer );\r
1075 \r
1076     // No memory allocation was attempted so xSemaphore cannot be NULL, so there\r
1077     // is no need to check its value.\r
1078  }\r
1079  </pre>\r
1080  * \defgroup xSemaphoreCreateCountingStatic xSemaphoreCreateCountingStatic\r
1081  * \ingroup Semaphores\r
1082  */\r
1083 #if( configSUPPORT_STATIC_ALLOCATION == 1 )\r
1084         #define xSemaphoreCreateCountingStatic( uxMaxCount, uxInitialCount, pxSemaphoreBuffer ) xQueueCreateCountingSemaphoreStatic( ( uxMaxCount ), ( uxInitialCount ), ( pxSemaphoreBuffer ) )\r
1085 #endif /* configSUPPORT_STATIC_ALLOCATION */\r
1086 \r
1087 /**\r
1088  * semphr. h\r
1089  * <pre>void vSemaphoreDelete( SemaphoreHandle_t xSemaphore );</pre>\r
1090  *\r
1091  * Delete a semaphore.  This function must be used with care.  For example,\r
1092  * do not delete a mutex type semaphore if the mutex is held by a task.\r
1093  *\r
1094  * @param xSemaphore A handle to the semaphore to be deleted.\r
1095  *\r
1096  * \defgroup vSemaphoreDelete vSemaphoreDelete\r
1097  * \ingroup Semaphores\r
1098  */\r
1099 #define vSemaphoreDelete( xSemaphore ) vQueueDelete( ( QueueHandle_t ) ( xSemaphore ) )\r
1100 \r
1101 /**\r
1102  * semphr.h\r
1103  * <pre>TaskHandle_t xSemaphoreGetMutexHolder( SemaphoreHandle_t xMutex );</pre>\r
1104  *\r
1105  * If xMutex is indeed a mutex type semaphore, return the current mutex holder.\r
1106  * If xMutex is not a mutex type semaphore, or the mutex is available (not held\r
1107  * by a task), return NULL.\r
1108  *\r
1109  * Note: This is a good way of determining if the calling task is the mutex\r
1110  * holder, but not a good way of determining the identity of the mutex holder as\r
1111  * the holder may change between the function exiting and the returned value\r
1112  * being tested.\r
1113  */\r
1114 #define xSemaphoreGetMutexHolder( xSemaphore ) xQueueGetMutexHolder( ( xSemaphore ) )\r
1115 \r
1116 /**\r
1117  * semphr.h\r
1118  * <pre>TaskHandle_t xSemaphoreGetMutexHolderFromISR( SemaphoreHandle_t xMutex );</pre>\r
1119  *\r
1120  * If xMutex is indeed a mutex type semaphore, return the current mutex holder.\r
1121  * If xMutex is not a mutex type semaphore, or the mutex is available (not held\r
1122  * by a task), return NULL.\r
1123  *\r
1124  */\r
1125 #define xSemaphoreGetMutexHolderFromISR( xSemaphore ) xQueueGetMutexHolderFromISR( ( xSemaphore ) )\r
1126 \r
1127 /**\r
1128  * semphr.h\r
1129  * <pre>UBaseType_t uxSemaphoreGetCount( SemaphoreHandle_t xSemaphore );</pre>\r
1130  *\r
1131  * If the semaphore is a counting semaphore then uxSemaphoreGetCount() returns\r
1132  * its current count value.  If the semaphore is a binary semaphore then\r
1133  * uxSemaphoreGetCount() returns 1 if the semaphore is available, and 0 if the\r
1134  * semaphore is not available.\r
1135  *\r
1136  */\r
1137 #define uxSemaphoreGetCount( xSemaphore ) uxQueueMessagesWaiting( ( QueueHandle_t ) ( xSemaphore ) )\r
1138 \r
1139 #endif /* SEMAPHORE_H */\r
1140 \r
1141 \r