granicus.if.org Git - esp-idf/blob - components/freertos/include/freertos/semphr.h

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