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