len0rd/FreeRTOS-Kernel
1
0
Fork 0
mirror of https://github.com/FreeRTOS/FreeRTOS-Kernel.git synced 2025-04-20 05:21:59 -04:00
Code Issues Packages Projects Releases Wiki Activity

Add xSemaphoreCreateBinary() so vSemaphoreCreate() can be deprecated.

Browse source
This commit is contained in:
Richard Barry 2013-11-07 10:53:23 +00:00
parent ca2191c6ee
commit dcf261a3e6
1 changed files with 155 additions and 101 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

256
FreeRTOS/Source/include/semphr.h
View file

@ -1,5 +1,5 @@
/* /*
FreeRTOS V7.5.3 - Copyright (C) 2013 Real Time Engineers Ltd. FreeRTOS V7.5.3 - Copyright (C) 2013 Real Time Engineers Ltd.
All rights reserved All rights reserved
VISIT http://www.FreeRTOS.org TO ENSURE YOU ARE USING THE LATEST VERSION. VISIT http://www.FreeRTOS.org TO ENSURE YOU ARE USING THE LATEST VERSION.
@ -83,6 +83,13 @@ typedef xQueueHandle xSemaphoreHandle;
* semphr. h * semphr. h
* <pre>vSemaphoreCreateBinary( xSemaphoreHandle xSemaphore )</pre> * <pre>vSemaphoreCreateBinary( xSemaphoreHandle xSemaphore )</pre>
* *
* This old vSemaphoreCreateBinary() macro is now deprecated in favour of the
* xSemaphoreCreateBinary() function. Note that binary semaphores created using
* the vSemaphoreCreateBinary() macro are created in a state such that the
* first call to 'take' the semaphore would pass, whereas binary semaphores
* created using xSemaphoreCreateBinary() are created in a state such that the
* the semaphore must first be 'given' before it can be 'taken'.
*
* <i>Macro</i> that implements a semaphore by using the existing queue mechanism. * <i>Macro</i> that implements a semaphore by using the existing queue mechanism.
* The queue length is 1 as this is a binary semaphore. The data size is 0 * The queue length is 1 as this is a binary semaphore. The data size is 0
* as we don't want to actually store any data - we just want to know if the * as we don't want to actually store any data - we just want to know if the
@ -99,7 +106,7 @@ typedef xQueueHandle xSemaphoreHandle;
* *
* Example usage: * Example usage:
<pre> <pre>
xSemaphoreHandle xSemaphore; xSemaphoreHandle xSemaphore = NULL;
void vATask( void * pvParameters ) void vATask( void * pvParameters )
{ {
@ -110,7 +117,7 @@ typedef xQueueHandle xSemaphoreHandle;
if( xSemaphore != NULL ) if( xSemaphore != NULL )
{ {
// The semaphore was created successfully. // The semaphore was created successfully.
// The semaphore can now be used. // The semaphore can now be used.
} }
} }
</pre> </pre>
@ -122,15 +129,62 @@ typedef xQueueHandle xSemaphoreHandle;
( xSemaphore ) = xQueueGenericCreate( ( unsigned portBASE_TYPE ) 1, semSEMAPHORE_QUEUE_ITEM_LENGTH, queueQUEUE_TYPE_BINARY_SEMAPHORE ); \ ( xSemaphore ) = xQueueGenericCreate( ( unsigned portBASE_TYPE ) 1, semSEMAPHORE_QUEUE_ITEM_LENGTH, queueQUEUE_TYPE_BINARY_SEMAPHORE ); \
if( ( xSemaphore ) != NULL ) \ if( ( xSemaphore ) != NULL ) \
{ \ { \
( void ) xSemaphoreGive( ( xSemaphore ) ); \ ( void ) xSemaphoreGive( ( xSemaphore ) ); \
} \ } \
} }
/** /**
* semphr. h * semphr. h
* <pre>xSemaphoreTake( * <pre>xSemaphoreHandle xSemaphoreCreateBinary( void )</pre>
* xSemaphoreHandle xSemaphore, *
* portTickType xBlockTime * The old vSemaphoreCreateBinary() macro is now deprecated in favour of this
* xSemaphoreCreateBinary() function. Note that binary semaphores created using
* the vSemaphoreCreateBinary() macro are created in a state such that the
* first call to 'take' the semaphore would pass, whereas binary semaphores
* created using xSemaphoreCreateBinary() are created in a state such that the
* the semaphore must first be 'given' before it can be 'taken'.
*
* Function that creates a semaphore by using the existing queue mechanism.
* The queue length is 1 as this is a binary semaphore. The data size is 0
* as nothing is actually stored - all that is important is whether the queue is
* empty or full (the binary semaphore is available or not).
*
* This type of semaphore can be used for pure synchronisation between tasks or
* between an interrupt and a task. The semaphore need not be given back once
* obtained, so one task/interrupt can continuously 'give' the semaphore while
* another continuously 'takes' the semaphore. For this reason this type of
* semaphore does not use a priority inheritance mechanism. For an alternative
* that does use priority inheritance see xSemaphoreCreateMutex().
*
* @return Handle to the created semaphore.
*
* Example usage:
<pre>
xSemaphoreHandle xSemaphore = NULL;
void vATask( void * pvParameters )
{
// Semaphore cannot be used before a call to vSemaphoreCreateBinary ().
// This is a macro so pass the variable in directly.
xSemaphore = xSemaphoreCreateBinary();
if( xSemaphore != NULL )
{
// The semaphore was created successfully.
// The semaphore can now be used.
}
}
</pre>
* \defgroup vSemaphoreCreateBinary vSemaphoreCreateBinary
* \ingroup Semaphores
*/
#define xSemaphoreCreateBinary() xQueueGenericCreate( ( unsigned portBASE_TYPE ) 1, semSEMAPHORE_QUEUE_ITEM_LENGTH, queueQUEUE_TYPE_BINARY_SEMAPHORE )
/**
* semphr. h
* <pre>xSemaphoreTake(
* xSemaphoreHandle xSemaphore,
* portTickType xBlockTime
* )</pre> * )</pre>
* *
* <i>Macro</i> to obtain a semaphore. The semaphore must have previously been * <i>Macro</i> to obtain a semaphore. The semaphore must have previously been
@ -168,7 +222,7 @@ typedef xQueueHandle xSemaphoreHandle;
if( xSemaphore != NULL ) if( xSemaphore != NULL )
{ {
// See if we can obtain the semaphore. If the semaphore is not available // See if we can obtain the semaphore. If the semaphore is not available
// wait 10 ticks to see if it becomes free. // wait 10 ticks to see if it becomes free.
if( xSemaphoreTake( xSemaphore, ( portTickType ) 10 ) == pdTRUE ) if( xSemaphoreTake( xSemaphore, ( portTickType ) 10 ) == pdTRUE )
{ {
// We were able to obtain the semaphore and can now access the // We were able to obtain the semaphore and can now access the
@ -176,7 +230,7 @@ typedef xQueueHandle xSemaphoreHandle;
// ... // ...
// We have finished accessing the shared resource. Release the // We have finished accessing the shared resource. Release the
// semaphore. // semaphore.
xSemaphoreGive( xSemaphore ); xSemaphoreGive( xSemaphore );
} }
@ -195,24 +249,24 @@ typedef xQueueHandle xSemaphoreHandle;
/** /**
* semphr. h * semphr. h
* xSemaphoreTakeRecursive( * xSemaphoreTakeRecursive(
* xSemaphoreHandle xMutex, * xSemaphoreHandle xMutex,
* portTickType xBlockTime * portTickType xBlockTime
* ) * )
* *
* <i>Macro</i> to recursively obtain, or 'take', a mutex type semaphore. * <i>Macro</i> to recursively obtain, or 'take', a mutex type semaphore.
* The mutex must have previously been created using a call to * The mutex must have previously been created using a call to
* xSemaphoreCreateRecursiveMutex(); * xSemaphoreCreateRecursiveMutex();
* *
* configUSE_RECURSIVE_MUTEXES must be set to 1 in FreeRTOSConfig.h for this * configUSE_RECURSIVE_MUTEXES must be set to 1 in FreeRTOSConfig.h for this
* macro to be available. * macro to be available.
* *
* This macro must not be used on mutexes created using xSemaphoreCreateMutex(). * This macro must not be used on mutexes created using xSemaphoreCreateMutex().
* *
* A mutex used recursively can be 'taken' repeatedly by the owner. The mutex * A mutex used recursively can be 'taken' repeatedly by the owner. The mutex
* doesn't become available again until the owner has called * doesn't become available again until the owner has called
* xSemaphoreGiveRecursive() for each successful 'take' request. For example, * xSemaphoreGiveRecursive() for each successful 'take' request. For example,
* if a task successfully 'takes' the same mutex 5 times then the mutex will * if a task successfully 'takes' the same mutex 5 times then the mutex will
* not be available to any other task until it has also 'given' the mutex back * not be available to any other task until it has also 'given' the mutex back
* exactly five times. * exactly five times.
* *
@ -223,7 +277,7 @@ typedef xQueueHandle xSemaphoreHandle;
* available. The macro portTICK_RATE_MS can be used to convert this to a * available. The macro portTICK_RATE_MS can be used to convert this to a
* real time. A block time of zero can be used to poll the semaphore. If * real time. A block time of zero can be used to poll the semaphore. If
* the task already owns the semaphore then xSemaphoreTakeRecursive() will * the task already owns the semaphore then xSemaphoreTakeRecursive() will
* return immediately no matter what the value of xBlockTime. * return immediately no matter what the value of xBlockTime.
* *
* @return pdTRUE if the semaphore was obtained. pdFALSE if xBlockTime * @return pdTRUE if the semaphore was obtained. pdFALSE if xBlockTime
* expired without the semaphore becoming available. * expired without the semaphore becoming available.
@ -247,14 +301,14 @@ typedef xQueueHandle xSemaphoreHandle;
if( xMutex != NULL ) if( xMutex != NULL )
{ {
// See if we can obtain the mutex. If the mutex is not available // See if we can obtain the mutex. If the mutex is not available
// wait 10 ticks to see if it becomes free. // wait 10 ticks to see if it becomes free.
if( xSemaphoreTakeRecursive( xSemaphore, ( portTickType ) 10 ) == pdTRUE ) if( xSemaphoreTakeRecursive( xSemaphore, ( portTickType ) 10 ) == pdTRUE )
{ {
// We were able to obtain the mutex and can now access the // We were able to obtain the mutex and can now access the
// shared resource. // shared resource.
// ... // ...
// For some reason due to the nature of the code further calls to // For some reason due to the nature of the code further calls to
// xSemaphoreTakeRecursive() are made on the same mutex. In real // xSemaphoreTakeRecursive() are made on the same mutex. In real
// code these would not be just sequential calls as this would make // code these would not be just sequential calls as this would make
// no sense. Instead the calls are likely to be buried inside // no sense. Instead the calls are likely to be buried inside
@ -262,7 +316,7 @@ typedef xQueueHandle xSemaphoreHandle;
xSemaphoreTakeRecursive( xMutex, ( portTickType ) 10 ); xSemaphoreTakeRecursive( xMutex, ( portTickType ) 10 );
xSemaphoreTakeRecursive( xMutex, ( portTickType ) 10 ); xSemaphoreTakeRecursive( xMutex, ( portTickType ) 10 );
// The mutex has now been 'taken' three times, so will not be // The mutex has now been 'taken' three times, so will not be
// available to another task until it has also been given back // available to another task until it has also been given back
// three times. Again it is unlikely that real code would have // three times. Again it is unlikely that real code would have
// these calls sequentially, but instead buried in a more complex // these calls sequentially, but instead buried in a more complex
@ -287,15 +341,15 @@ typedef xQueueHandle xSemaphoreHandle;
#define xSemaphoreTakeRecursive( xMutex, xBlockTime ) xQueueTakeMutexRecursive( ( xMutex ), ( xBlockTime ) ) #define xSemaphoreTakeRecursive( xMutex, xBlockTime ) xQueueTakeMutexRecursive( ( xMutex ), ( xBlockTime ) )
/* /*
* xSemaphoreAltTake() is an alternative version of xSemaphoreTake(). * xSemaphoreAltTake() is an alternative version of xSemaphoreTake().
* *
* The source code that implements the alternative (Alt) API is much * The source code that implements the alternative (Alt) API is much
* simpler because it executes everything from within a critical section. * simpler because it executes everything from within a critical section.
* This is the approach taken by many other RTOSes, but FreeRTOS.org has the * This is the approach taken by many other RTOSes, but FreeRTOS.org has the
* preferred fully featured API too. The fully featured API has more * preferred fully featured API too. The fully featured API has more
* complex code that takes longer to execute, but makes much less use of * complex code that takes longer to execute, but makes much less use of
* critical sections. Therefore the alternative API sacrifices interrupt * critical sections. Therefore the alternative API sacrifices interrupt
* responsiveness to gain execution speed, whereas the fully featured API * responsiveness to gain execution speed, whereas the fully featured API
* sacrifices execution speed to ensure better interrupt responsiveness. * sacrifices execution speed to ensure better interrupt responsiveness.
*/ */
@ -312,7 +366,7 @@ typedef xQueueHandle xSemaphoreHandle;
* This macro must not be used from an ISR. See xSemaphoreGiveFromISR () for * This macro must not be used from an ISR. See xSemaphoreGiveFromISR () for
* an alternative which can be used from an ISR. * an alternative which can be used from an ISR.
* *
* This macro must also not be used on semaphores created using * This macro must also not be used on semaphores created using
* xSemaphoreCreateRecursiveMutex(). * xSemaphoreCreateRecursiveMutex().
* *
* @param xSemaphore A handle to the semaphore being released. This is the * @param xSemaphore A handle to the semaphore being released. This is the
@ -320,7 +374,7 @@ typedef xQueueHandle xSemaphoreHandle;
* *
* @return pdTRUE if the semaphore was released. pdFALSE if an error occurred. * @return pdTRUE if the semaphore was released. pdFALSE if an error occurred.
* Semaphores are implemented using queues. An error can occur if there is * Semaphores are implemented using queues. An error can occur if there is
* no space on the queue to post a message - indicating that the * no space on the queue to post a message - indicating that the
* semaphore was not first obtained correctly. * semaphore was not first obtained correctly.
* *
* Example usage: * Example usage:
@ -369,18 +423,18 @@ typedef xQueueHandle xSemaphoreHandle;
* <pre>xSemaphoreGiveRecursive( xSemaphoreHandle xMutex )</pre> * <pre>xSemaphoreGiveRecursive( xSemaphoreHandle xMutex )</pre>
* *
* <i>Macro</i> to recursively release, or 'give', a mutex type semaphore. * <i>Macro</i> to recursively release, or 'give', a mutex type semaphore.
* The mutex must have previously been created using a call to * The mutex must have previously been created using a call to
* xSemaphoreCreateRecursiveMutex(); * xSemaphoreCreateRecursiveMutex();
* *
* configUSE_RECURSIVE_MUTEXES must be set to 1 in FreeRTOSConfig.h for this * configUSE_RECURSIVE_MUTEXES must be set to 1 in FreeRTOSConfig.h for this
* macro to be available. * macro to be available.
* *
* This macro must not be used on mutexes created using xSemaphoreCreateMutex(). * This macro must not be used on mutexes created using xSemaphoreCreateMutex().
* *
* A mutex used recursively can be 'taken' repeatedly by the owner. The mutex * A mutex used recursively can be 'taken' repeatedly by the owner. The mutex
* doesn't become available again until the owner has called * doesn't become available again until the owner has called
* xSemaphoreGiveRecursive() for each successful 'take' request. For example, * xSemaphoreGiveRecursive() for each successful 'take' request. For example,
* if a task successfully 'takes' the same mutex 5 times then the mutex will * if a task successfully 'takes' the same mutex 5 times then the mutex will
* not be available to any other task until it has also 'given' the mutex back * not be available to any other task until it has also 'given' the mutex back
* exactly five times. * exactly five times.
* *
@ -408,14 +462,14 @@ typedef xQueueHandle xSemaphoreHandle;
if( xMutex != NULL ) if( xMutex != NULL )
{ {
// See if we can obtain the mutex. If the mutex is not available // See if we can obtain the mutex. If the mutex is not available
// wait 10 ticks to see if it becomes free. // wait 10 ticks to see if it becomes free.
if( xSemaphoreTakeRecursive( xMutex, ( portTickType ) 10 ) == pdTRUE ) if( xSemaphoreTakeRecursive( xMutex, ( portTickType ) 10 ) == pdTRUE )
{ {
// We were able to obtain the mutex and can now access the // We were able to obtain the mutex and can now access the
// shared resource. // shared resource.
// ... // ...
// For some reason due to the nature of the code further calls to // For some reason due to the nature of the code further calls to
// xSemaphoreTakeRecursive() are made on the same mutex. In real // xSemaphoreTakeRecursive() are made on the same mutex. In real
// code these would not be just sequential calls as this would make // code these would not be just sequential calls as this would make
// no sense. Instead the calls are likely to be buried inside // no sense. Instead the calls are likely to be buried inside
@ -423,7 +477,7 @@ typedef xQueueHandle xSemaphoreHandle;
xSemaphoreTakeRecursive( xMutex, ( portTickType ) 10 ); xSemaphoreTakeRecursive( xMutex, ( portTickType ) 10 );
xSemaphoreTakeRecursive( xMutex, ( portTickType ) 10 ); xSemaphoreTakeRecursive( xMutex, ( portTickType ) 10 );
// The mutex has now been 'taken' three times, so will not be // The mutex has now been 'taken' three times, so will not be
// available to another task until it has also been given back // available to another task until it has also been given back
// three times. Again it is unlikely that real code would have // three times. Again it is unlikely that real code would have
// these calls sequentially, it would be more likely that the calls // these calls sequentially, it would be more likely that the calls
@ -448,15 +502,15 @@ typedef xQueueHandle xSemaphoreHandle;
*/ */
#define xSemaphoreGiveRecursive( xMutex ) xQueueGiveMutexRecursive( ( xMutex ) ) #define xSemaphoreGiveRecursive( xMutex ) xQueueGiveMutexRecursive( ( xMutex ) )
/* /*
* xSemaphoreAltGive() is an alternative version of xSemaphoreGive(). * xSemaphoreAltGive() is an alternative version of xSemaphoreGive().
* *
* The source code that implements the alternative (Alt) API is much * The source code that implements the alternative (Alt) API is much
* simpler because it executes everything from within a critical section. * simpler because it executes everything from within a critical section.
* This is the approach taken by many other RTOSes, but FreeRTOS.org has the * This is the approach taken by many other RTOSes, but FreeRTOS.org has the
* preferred fully featured API too. The fully featured API has more * preferred fully featured API too. The fully featured API has more
* complex code that takes longer to execute, but makes much less use of * complex code that takes longer to execute, but makes much less use of
* critical sections. Therefore the alternative API sacrifices interrupt * critical sections. Therefore the alternative API sacrifices interrupt
* responsiveness to gain execution speed, whereas the fully featured API * responsiveness to gain execution speed, whereas the fully featured API
* sacrifices execution speed to ensure better interrupt responsiveness. * sacrifices execution speed to ensure better interrupt responsiveness.
*/ */
@ -465,8 +519,8 @@ typedef xQueueHandle xSemaphoreHandle;
/** /**
* semphr. h * semphr. h
* <pre> * <pre>
xSemaphoreGiveFromISR( xSemaphoreGiveFromISR(
xSemaphoreHandle xSemaphore, xSemaphoreHandle xSemaphore,
signed portBASE_TYPE *pxHigherPriorityTaskWoken signed portBASE_TYPE *pxHigherPriorityTaskWoken
)</pre> )</pre>
* *
@ -500,7 +554,7 @@ typedef xQueueHandle xSemaphoreHandle;
{ {
for( ;; ) for( ;; )
{ {
// We want this task to run every 10 ticks of a timer. The semaphore // We want this task to run every 10 ticks of a timer. The semaphore
// was created before this task was started. // was created before this task was started.
// Block waiting for the semaphore to become available. // Block waiting for the semaphore to become available.
@ -511,7 +565,7 @@ typedef xQueueHandle xSemaphoreHandle;
// ... // ...
// We have finished our task. Return to the top of the loop where // We have finished our task. Return to the top of the loop where
// we will block on the semaphore until it is time to execute // we will block on the semaphore until it is time to execute
// again. Note when using the semaphore for synchronisation with an // again. Note when using the semaphore for synchronisation with an
// ISR in this manner there is no need to 'give' the semaphore back. // ISR in this manner there is no need to 'give' the semaphore back.
} }
@ -556,13 +610,13 @@ typedef xQueueHandle xSemaphoreHandle;
/** /**
* semphr. h * semphr. h
* <pre> * <pre>
xSemaphoreTakeFromISR( xSemaphoreTakeFromISR(
xSemaphoreHandle xSemaphore, xSemaphoreHandle xSemaphore,
signed portBASE_TYPE *pxHigherPriorityTaskWoken signed portBASE_TYPE *pxHigherPriorityTaskWoken
)</pre> )</pre>
* *
* <i>Macro</i> to take a semaphore from an ISR. The semaphore must have * <i>Macro</i> to take a semaphore from an ISR. The semaphore must have
* previously been created with a call to vSemaphoreCreateBinary() or * previously been created with a call to vSemaphoreCreateBinary() or
* xSemaphoreCreateCounting(). * xSemaphoreCreateCounting().
* *
* Mutex type semaphores (those created using a call to xSemaphoreCreateMutex()) * Mutex type semaphores (those created using a call to xSemaphoreCreateMutex())
@ -582,7 +636,7 @@ typedef xQueueHandle xSemaphoreHandle;
* running task. If xSemaphoreTakeFromISR() sets this value to pdTRUE then * running task. If xSemaphoreTakeFromISR() sets this value to pdTRUE then
* a context switch should be requested before the interrupt is exited. * a context switch should be requested before the interrupt is exited.
* *
* @return pdTRUE if the semaphore was successfully taken, otherwise * @return pdTRUE if the semaphore was successfully taken, otherwise
* pdFALSE * pdFALSE
*/ */
#define xSemaphoreTakeFromISR( xSemaphore, pxHigherPriorityTaskWoken ) xQueueReceiveFromISR( ( xQueueHandle ) ( xSemaphore ), NULL, ( pxHigherPriorityTaskWoken ) ) #define xSemaphoreTakeFromISR( xSemaphore, pxHigherPriorityTaskWoken ) xQueueReceiveFromISR( ( xQueueHandle ) ( xSemaphore ), NULL, ( pxHigherPriorityTaskWoken ) )
@ -591,25 +645,25 @@ typedef xQueueHandle xSemaphoreHandle;
* semphr. h * semphr. h
* <pre>xSemaphoreHandle xSemaphoreCreateMutex( void )</pre> * <pre>xSemaphoreHandle xSemaphoreCreateMutex( void )</pre>
* *
* <i>Macro</i> that implements a mutex semaphore by using the existing queue * <i>Macro</i> that implements a mutex semaphore by using the existing queue
* mechanism. * mechanism.
* *
* Mutexes created using this macro can be accessed using the xSemaphoreTake() * Mutexes created using this macro can be accessed using the xSemaphoreTake()
* and xSemaphoreGive() macros. The xSemaphoreTakeRecursive() and * and xSemaphoreGive() macros. The xSemaphoreTakeRecursive() and
* xSemaphoreGiveRecursive() macros should not be used. * xSemaphoreGiveRecursive() macros should not be used.
*
* This type of semaphore uses a priority inheritance mechanism so a task
* 'taking' a semaphore MUST ALWAYS 'give' the semaphore back once the
* semaphore it is no longer required.
* *
* Mutex type semaphores cannot be used from within interrupt service routines. * This type of semaphore uses a priority inheritance mechanism so a task
* 'taking' a semaphore MUST ALWAYS 'give' the semaphore back once the
* semaphore it is no longer required.
* *
* See vSemaphoreCreateBinary() for an alternative implementation that can be * Mutex type semaphores cannot be used from within interrupt service routines.
* used for pure synchronisation (where one task or interrupt always 'gives' the *
* semaphore and another always 'takes' the semaphore) and from within interrupt * See vSemaphoreCreateBinary() for an alternative implementation that can be
* used for pure synchronisation (where one task or interrupt always 'gives' the
* semaphore and another always 'takes' the semaphore) and from within interrupt
* service routines. * service routines.
* *
* @return xSemaphore Handle to the created mutex semaphore. Should be of type * @return xSemaphore Handle to the created mutex semaphore. Should be of type
* xSemaphoreHandle. * xSemaphoreHandle.
* *
* Example usage: * Example usage:
@ -625,7 +679,7 @@ typedef xQueueHandle xSemaphoreHandle;
if( xSemaphore != NULL ) if( xSemaphore != NULL )
{ {
// The semaphore was created successfully. // The semaphore was created successfully.
// The semaphore can now be used. // The semaphore can now be used.
} }
} }
</pre> </pre>
@ -639,32 +693,32 @@ typedef xQueueHandle xSemaphoreHandle;
* semphr. h * semphr. h
* <pre>xSemaphoreHandle xSemaphoreCreateRecursiveMutex( void )</pre> * <pre>xSemaphoreHandle xSemaphoreCreateRecursiveMutex( void )</pre>
* *
* <i>Macro</i> that implements a recursive mutex by using the existing queue * <i>Macro</i> that implements a recursive mutex by using the existing queue
* mechanism. * mechanism.
* *
* Mutexes created using this macro can be accessed using the * Mutexes created using this macro can be accessed using the
* xSemaphoreTakeRecursive() and xSemaphoreGiveRecursive() macros. The * xSemaphoreTakeRecursive() and xSemaphoreGiveRecursive() macros. The
* xSemaphoreTake() and xSemaphoreGive() macros should not be used. * xSemaphoreTake() and xSemaphoreGive() macros should not be used.
* *
* A mutex used recursively can be 'taken' repeatedly by the owner. The mutex * A mutex used recursively can be 'taken' repeatedly by the owner. The mutex
* doesn't become available again until the owner has called * doesn't become available again until the owner has called
* xSemaphoreGiveRecursive() for each successful 'take' request. For example, * xSemaphoreGiveRecursive() for each successful 'take' request. For example,
* if a task successfully 'takes' the same mutex 5 times then the mutex will * if a task successfully 'takes' the same mutex 5 times then the mutex will
* not be available to any other task until it has also 'given' the mutex back * not be available to any other task until it has also 'given' the mutex back
* exactly five times. * exactly five times.
*
* This type of semaphore uses a priority inheritance mechanism so a task
* 'taking' a semaphore MUST ALWAYS 'give' the semaphore back once the
* semaphore it is no longer required.
* *
* Mutex type semaphores cannot be used from within interrupt service routines. * This type of semaphore uses a priority inheritance mechanism so a task
* 'taking' a semaphore MUST ALWAYS 'give' the semaphore back once the
* semaphore it is no longer required.
* *
* See vSemaphoreCreateBinary() for an alternative implementation that can be * Mutex type semaphores cannot be used from within interrupt service routines.
* used for pure synchronisation (where one task or interrupt always 'gives' the *
* semaphore and another always 'takes' the semaphore) and from within interrupt * See vSemaphoreCreateBinary() for an alternative implementation that can be
* used for pure synchronisation (where one task or interrupt always 'gives' the
* semaphore and another always 'takes' the semaphore) and from within interrupt
* service routines. * service routines.
* *
* @return xSemaphore Handle to the created mutex semaphore. Should be of type * @return xSemaphore Handle to the created mutex semaphore. Should be of type
* xSemaphoreHandle. * xSemaphoreHandle.
* *
* Example usage: * Example usage:
@ -680,7 +734,7 @@ typedef xQueueHandle xSemaphoreHandle;
if( xSemaphore != NULL ) if( xSemaphore != NULL )
{ {
// The semaphore was created successfully. // The semaphore was created successfully.
// The semaphore can now be used. // The semaphore can now be used.
} }
} }
</pre> </pre>
@ -693,32 +747,32 @@ typedef xQueueHandle xSemaphoreHandle;
* semphr. h * semphr. h
* <pre>xSemaphoreHandle xSemaphoreCreateCounting( unsigned portBASE_TYPE uxMaxCount, unsigned portBASE_TYPE uxInitialCount )</pre> * <pre>xSemaphoreHandle xSemaphoreCreateCounting( unsigned portBASE_TYPE uxMaxCount, unsigned portBASE_TYPE uxInitialCount )</pre>
* *
* <i>Macro</i> that creates a counting semaphore by using the existing * <i>Macro</i> that creates a counting semaphore by using the existing
* queue mechanism. * queue mechanism.
* *
* Counting semaphores are typically used for two things: * Counting semaphores are typically used for two things:
* *
* 1) Counting events. * 1) Counting events.
* *
* In this usage scenario an event handler will 'give' a semaphore each time * In this usage scenario an event handler will 'give' a semaphore each time
* an event occurs (incrementing the semaphore count value), and a handler * an event occurs (incrementing the semaphore count value), and a handler
* task will 'take' a semaphore each time it processes an event * task will 'take' a semaphore each time it processes an event
* (decrementing the semaphore count value). The count value is therefore * (decrementing the semaphore count value). The count value is therefore
* the difference between the number of events that have occurred and the * the difference between the number of events that have occurred and the
* number that have been processed. In this case it is desirable for the * number that have been processed. In this case it is desirable for the
* initial count value to be zero. * initial count value to be zero.
* *
* 2) Resource management. * 2) Resource management.
* *
* In this usage scenario the count value indicates the number of resources * In this usage scenario the count value indicates the number of resources
* available. To obtain control of a resource a task must first obtain a * available. To obtain control of a resource a task must first obtain a
* semaphore - decrementing the semaphore count value. When the count value * semaphore - decrementing the semaphore count value. When the count value
* reaches zero there are no free resources. When a task finishes with the * reaches zero there are no free resources. When a task finishes with the
* resource it 'gives' the semaphore back - incrementing the semaphore count * resource it 'gives' the semaphore back - incrementing the semaphore count
* value. In this case it is desirable for the initial count value to be * value. In this case it is desirable for the initial count value to be
* equal to the maximum count value, indicating that all resources are free. * equal to the maximum count value, indicating that all resources are free.
* *
* @param uxMaxCount The maximum count value that can be reached. When the * @param uxMaxCount The maximum count value that can be reached. When the
* semaphore reaches this value it can no longer be 'given'. * semaphore reaches this value it can no longer be 'given'.
* *
* @param uxInitialCount The count value assigned to the semaphore when it is * @param uxInitialCount The count value assigned to the semaphore when it is
@ -726,7 +780,7 @@ typedef xQueueHandle xSemaphoreHandle;
* *
* @return Handle to the created semaphore. Null if the semaphore could not be * @return Handle to the created semaphore. Null if the semaphore could not be
* created. * created.
* *
* Example usage: * Example usage:
<pre> <pre>
xSemaphoreHandle xSemaphore; xSemaphoreHandle xSemaphore;
@ -743,7 +797,7 @@ typedef xQueueHandle xSemaphoreHandle;
if( xSemaphore != NULL ) if( xSemaphore != NULL )
{ {
// The semaphore was created successfully. // The semaphore was created successfully.
// The semaphore can now be used. // The semaphore can now be used.
} }
} }
</pre> </pre>
@ -774,7 +828,7 @@ typedef xQueueHandle xSemaphoreHandle;
* If xMutex is not a mutex type semaphore, or the mutex is available (not held * If xMutex is not a mutex type semaphore, or the mutex is available (not held
* by a task), return NULL. * by a task), return NULL.
* *
* Note: This Is is a good way of determining if the calling task is the mutex * Note: This Is is a good way of determining if the calling task is the mutex
* holder, but not a good way of determining the identity of the mutex holder as * holder, but not a good way of determining the identity of the mutex holder as
* the holder may change between the function exiting and the returned value * the holder may change between the function exiting and the returned value
* being tested. * being tested.