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