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