From 02f9d89ef7e1b5a737a8f7cacbb64c33ed5bc27e Mon Sep 17 00:00:00 2001 From: richardbarry Date: Thu, 7 Nov 2013 10:53:23 +0000 Subject: [PATCH] Add xSemaphoreCreateBinary() so vSemaphoreCreate() can be deprecated. git-svn-id: https://svn.code.sf.net/p/freertos/code/trunk@2084 1d2547de-c912-0410-9cb9-b8ca96c0e9e2 --- FreeRTOS/Source/include/semphr.h | 256 +++++++++++++++++++------------ 1 file changed, 155 insertions(+), 101 deletions(-) diff --git a/FreeRTOS/Source/include/semphr.h b/FreeRTOS/Source/include/semphr.h index 2d77c020b..792ab77a7 100644 --- a/FreeRTOS/Source/include/semphr.h +++ b/FreeRTOS/Source/include/semphr.h @@ -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 VISIT http://www.FreeRTOS.org TO ENSURE YOU ARE USING THE LATEST VERSION. @@ -83,6 +83,13 @@ typedef xQueueHandle xSemaphoreHandle; * semphr. h *
vSemaphoreCreateBinary( xSemaphoreHandle xSemaphore )
* + * 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'. + * * Macro 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 * 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:
- xSemaphoreHandle xSemaphore;
+ xSemaphoreHandle xSemaphore = NULL;
 
  void vATask( void * pvParameters )
  {
@@ -110,7 +117,7 @@ typedef xQueueHandle xSemaphoreHandle;
     if( xSemaphore != NULL )
     {
         // The semaphore was created successfully.
-        // The semaphore can now be used.  
+        // The semaphore can now be used.
     }
  }
  
@@ -122,15 +129,62 @@ typedef xQueueHandle xSemaphoreHandle; ( xSemaphore ) = xQueueGenericCreate( ( unsigned portBASE_TYPE ) 1, semSEMAPHORE_QUEUE_ITEM_LENGTH, queueQUEUE_TYPE_BINARY_SEMAPHORE ); \ if( ( xSemaphore ) != NULL ) \ { \ - ( void ) xSemaphoreGive( ( xSemaphore ) ); \ + ( void ) xSemaphoreGive( ( xSemaphore ) ); \ } \ } /** * semphr. h - *
xSemaphoreTake( 
- *                   xSemaphoreHandle xSemaphore, 
- *                   portTickType xBlockTime 
+ * 
xSemaphoreHandle xSemaphoreCreateBinary( void )
+ * + * 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: +
+ 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.
+    }
+ }
+ 
+ * \defgroup vSemaphoreCreateBinary vSemaphoreCreateBinary + * \ingroup Semaphores + */ +#define xSemaphoreCreateBinary() xQueueGenericCreate( ( unsigned portBASE_TYPE ) 1, semSEMAPHORE_QUEUE_ITEM_LENGTH, queueQUEUE_TYPE_BINARY_SEMAPHORE ) + +/** + * semphr. h + *
xSemaphoreTake(
+ *                   xSemaphoreHandle xSemaphore,
+ *                   portTickType xBlockTime
  *               )
* * Macro to obtain a semaphore. The semaphore must have previously been @@ -168,7 +222,7 @@ typedef xQueueHandle xSemaphoreHandle; if( xSemaphore != NULL ) { // 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 ) { // 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. xSemaphoreGive( xSemaphore ); } @@ -195,24 +249,24 @@ typedef xQueueHandle xSemaphoreHandle; /** * semphr. h - * xSemaphoreTakeRecursive( - * xSemaphoreHandle xMutex, - * portTickType xBlockTime + * xSemaphoreTakeRecursive( + * xSemaphoreHandle xMutex, + * portTickType xBlockTime * ) * - * Macro to recursively obtain, or 'take', a mutex type semaphore. - * The mutex must have previously been created using a call to + * Macro to recursively obtain, or 'take', a mutex type semaphore. + * The mutex must have previously been created using a call to * xSemaphoreCreateRecursiveMutex(); - * + * * configUSE_RECURSIVE_MUTEXES must be set to 1 in FreeRTOSConfig.h for this * macro to be available. - * + * * This macro must not be used on mutexes created using xSemaphoreCreateMutex(). * - * A mutex used recursively can be 'taken' repeatedly by the owner. The mutex - * doesn't become available again until the owner has called - * xSemaphoreGiveRecursive() for each successful 'take' request. For example, - * if a task successfully 'takes' the same mutex 5 times then the mutex will + * A mutex used recursively can be 'taken' repeatedly by the owner. The mutex + * doesn't become available again until the owner has called + * xSemaphoreGiveRecursive() for each successful 'take' request. For example, + * 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 * exactly five times. * @@ -223,7 +277,7 @@ typedef xQueueHandle xSemaphoreHandle; * 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 * 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 * expired without the semaphore becoming available. @@ -247,14 +301,14 @@ typedef xQueueHandle xSemaphoreHandle; if( xMutex != NULL ) { // 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 ) { // We were able to obtain the mutex and can now access the // 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 // code these would not be just sequential calls as this would make // 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 ); - // 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 // three times. Again it is unlikely that real code would have // these calls sequentially, but instead buried in a more complex @@ -287,15 +341,15 @@ typedef xQueueHandle xSemaphoreHandle; #define xSemaphoreTakeRecursive( xMutex, xBlockTime ) xQueueTakeMutexRecursive( ( xMutex ), ( xBlockTime ) ) -/* +/* * xSemaphoreAltTake() is an alternative version of xSemaphoreTake(). * - * The source code that implements the alternative (Alt) API is much - * simpler because it executes everything from within a critical section. - * 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 - * complex code that takes longer to execute, but makes much less use of - * critical sections. Therefore the alternative API sacrifices interrupt + * The source code that implements the alternative (Alt) API is much + * simpler because it executes everything from within a critical section. + * 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 + * complex code that takes longer to execute, but makes much less use of + * critical sections. Therefore the alternative API sacrifices interrupt * responsiveness to gain execution speed, whereas the fully featured API * 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 * 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(). * * @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. * 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. * * Example usage: @@ -369,18 +423,18 @@ typedef xQueueHandle xSemaphoreHandle; *
xSemaphoreGiveRecursive( xSemaphoreHandle xMutex )
* * Macro 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(); - * + * * configUSE_RECURSIVE_MUTEXES must be set to 1 in FreeRTOSConfig.h for this * macro to be available. * * This macro must not be used on mutexes created using xSemaphoreCreateMutex(). - * - * A mutex used recursively can be 'taken' repeatedly by the owner. The mutex - * doesn't become available again until the owner has called - * xSemaphoreGiveRecursive() for each successful 'take' request. For example, - * if a task successfully 'takes' the same mutex 5 times then the mutex will + * + * A mutex used recursively can be 'taken' repeatedly by the owner. The mutex + * doesn't become available again until the owner has called + * xSemaphoreGiveRecursive() for each successful 'take' request. For example, + * 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 * exactly five times. * @@ -408,14 +462,14 @@ typedef xQueueHandle xSemaphoreHandle; if( xMutex != NULL ) { // 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 ) { // We were able to obtain the mutex and can now access the // 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 // code these would not be just sequential calls as this would make // 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 ); - // 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 // three times. Again it is unlikely that real code would have // these calls sequentially, it would be more likely that the calls @@ -448,15 +502,15 @@ typedef xQueueHandle xSemaphoreHandle; */ #define xSemaphoreGiveRecursive( xMutex ) xQueueGiveMutexRecursive( ( xMutex ) ) -/* +/* * xSemaphoreAltGive() is an alternative version of xSemaphoreGive(). * - * The source code that implements the alternative (Alt) API is much - * simpler because it executes everything from within a critical section. - * 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 - * complex code that takes longer to execute, but makes much less use of - * critical sections. Therefore the alternative API sacrifices interrupt + * The source code that implements the alternative (Alt) API is much + * simpler because it executes everything from within a critical section. + * 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 + * complex code that takes longer to execute, but makes much less use of + * critical sections. Therefore the alternative API sacrifices interrupt * responsiveness to gain execution speed, whereas the fully featured API * sacrifices execution speed to ensure better interrupt responsiveness. */ @@ -465,8 +519,8 @@ typedef xQueueHandle xSemaphoreHandle; /** * semphr. h *
- xSemaphoreGiveFromISR( 
-                          xSemaphoreHandle xSemaphore, 
+ xSemaphoreGiveFromISR(
+                          xSemaphoreHandle xSemaphore,
                           signed portBASE_TYPE *pxHigherPriorityTaskWoken
                       )
* @@ -500,7 +554,7 @@ typedef xQueueHandle xSemaphoreHandle; { 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. // 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 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 // ISR in this manner there is no need to 'give' the semaphore back. } @@ -556,13 +610,13 @@ typedef xQueueHandle xSemaphoreHandle; /** * semphr. h *
- xSemaphoreTakeFromISR( 
-                          xSemaphoreHandle xSemaphore, 
+ xSemaphoreTakeFromISR(
+                          xSemaphoreHandle xSemaphore,
                           signed portBASE_TYPE *pxHigherPriorityTaskWoken
                       )
* - * Macro to take a semaphore from an ISR. The semaphore must have - * previously been created with a call to vSemaphoreCreateBinary() or + * Macro to take a semaphore from an ISR. The semaphore must have + * previously been created with a call to vSemaphoreCreateBinary() or * xSemaphoreCreateCounting(). * * 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 * 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 */ #define xSemaphoreTakeFromISR( xSemaphore, pxHigherPriorityTaskWoken ) xQueueReceiveFromISR( ( xQueueHandle ) ( xSemaphore ), NULL, ( pxHigherPriorityTaskWoken ) ) @@ -591,25 +645,25 @@ typedef xQueueHandle xSemaphoreHandle; * semphr. h *
xSemaphoreHandle xSemaphoreCreateMutex( void )
* - * Macro that implements a mutex semaphore by using the existing queue + * Macro that implements a mutex semaphore by using the existing queue * mechanism. * * 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. - * - * 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. + * + * Mutex type semaphores cannot be used from within interrupt service routines. * - * 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 + * 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. * - * @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. * * Example usage: @@ -625,7 +679,7 @@ typedef xQueueHandle xSemaphoreHandle; if( xSemaphore != NULL ) { // The semaphore was created successfully. - // The semaphore can now be used. + // The semaphore can now be used. } }
@@ -639,32 +693,32 @@ typedef xQueueHandle xSemaphoreHandle; * semphr. h *
xSemaphoreHandle xSemaphoreCreateRecursiveMutex( void )
* - * Macro that implements a recursive mutex by using the existing queue + * Macro that implements a recursive mutex by using the existing queue * mechanism. * - * Mutexes created using this macro can be accessed using the - * xSemaphoreTakeRecursive() and xSemaphoreGiveRecursive() macros. The + * Mutexes created using this macro can be accessed using the + * xSemaphoreTakeRecursive() and xSemaphoreGiveRecursive() macros. The * xSemaphoreTake() and xSemaphoreGive() macros should not be used. * - * A mutex used recursively can be 'taken' repeatedly by the owner. The mutex - * doesn't become available again until the owner has called - * xSemaphoreGiveRecursive() for each successful 'take' request. For example, - * if a task successfully 'takes' the same mutex 5 times then the mutex will + * A mutex used recursively can be 'taken' repeatedly by the owner. The mutex + * doesn't become available again until the owner has called + * xSemaphoreGiveRecursive() for each successful 'take' request. For example, + * 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 * 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 - * used for pure synchronisation (where one task or interrupt always 'gives' the - * semaphore and another always 'takes' the semaphore) and from within interrupt + * Mutex type semaphores cannot be used from within interrupt service routines. + * + * 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. * - * @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. * * Example usage: @@ -680,7 +734,7 @@ typedef xQueueHandle xSemaphoreHandle; if( xSemaphore != NULL ) { // The semaphore was created successfully. - // The semaphore can now be used. + // The semaphore can now be used. } } @@ -693,32 +747,32 @@ typedef xQueueHandle xSemaphoreHandle; * semphr. h *
xSemaphoreHandle xSemaphoreCreateCounting( unsigned portBASE_TYPE uxMaxCount, unsigned portBASE_TYPE uxInitialCount )
* - * Macro that creates a counting semaphore by using the existing - * queue mechanism. + * Macro that creates a counting semaphore by using the existing + * queue mechanism. * * 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 - * an event occurs (incrementing the semaphore count value), and a handler - * task will 'take' a semaphore each time it processes an event - * (decrementing the semaphore count value). The count value is therefore - * 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 + * an event occurs (incrementing the semaphore count value), and a handler + * task will 'take' a semaphore each time it processes an event + * (decrementing the semaphore count value). The count value is therefore + * 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 * initial count value to be zero. * * 2) Resource management. * * 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 * reaches zero there are no free resources. When a task finishes with the * resource it 'gives' the semaphore back - incrementing the semaphore count * 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. * - * @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'. * * @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 * created. - * + * * Example usage:
  xSemaphoreHandle xSemaphore;
@@ -743,7 +797,7 @@ typedef xQueueHandle xSemaphoreHandle;
     if( xSemaphore != NULL )
     {
         // The semaphore was created successfully.
-        // The semaphore can now be used.  
+        // The semaphore can now be used.
     }
  }
  
@@ -774,7 +828,7 @@ typedef xQueueHandle xSemaphoreHandle; * If xMutex is not a mutex type semaphore, or the mutex is available (not held * 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 * the holder may change between the function exiting and the returned value * being tested. -- 2.39.5