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

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