/*\r
- FreeRTOS V8.1.2 - Copyright (C) 2014 Real Time Engineers Ltd.\r
+ FreeRTOS V9.0.0 - Copyright (C) 2016 Real Time Engineers Ltd.\r
All rights reserved\r
\r
VISIT http://www.FreeRTOS.org TO ENSURE YOU ARE USING THE LATEST VERSION.\r
\r
- ***************************************************************************\r
- * *\r
- * FreeRTOS provides completely free yet professionally developed, *\r
- * robust, strictly quality controlled, supported, and cross *\r
- * platform software that has become a de facto standard. *\r
- * *\r
- * Help yourself get started quickly and support the FreeRTOS *\r
- * project by purchasing a FreeRTOS tutorial book, reference *\r
- * manual, or both from: http://www.FreeRTOS.org/Documentation *\r
- * *\r
- * Thank you! *\r
- * *\r
- ***************************************************************************\r
-\r
This file is part of the FreeRTOS distribution.\r
\r
FreeRTOS is free software; you can redistribute it and/or modify it under\r
the terms of the GNU General Public License (version 2) as published by the\r
- Free Software Foundation >>!AND MODIFIED BY!<< the FreeRTOS exception.\r
+ Free Software Foundation >>>> AND MODIFIED BY <<<< the FreeRTOS exception.\r
\r
+ ***************************************************************************\r
>>! NOTE: The modification to the GPL is included to allow you to !<<\r
>>! distribute a combined work that includes FreeRTOS without being !<<\r
>>! obliged to provide the source code for proprietary components !<<\r
>>! outside of the FreeRTOS kernel. !<<\r
+ ***************************************************************************\r
\r
FreeRTOS is distributed in the hope that it will be useful, but WITHOUT ANY\r
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS\r
- FOR A PARTICULAR PURPOSE. Full license text is available from the following\r
+ FOR A PARTICULAR PURPOSE. Full license text is available on the following\r
link: http://www.freertos.org/a00114.html\r
\r
- 1 tab == 4 spaces!\r
-\r
***************************************************************************\r
* *\r
- * Having a problem? Start by reading the FAQ "My application does *\r
- * not run, what could be wrong?" *\r
+ * FreeRTOS provides completely free yet professionally developed, *\r
+ * robust, strictly quality controlled, supported, and cross *\r
+ * platform software that is more than just the market leader, it *\r
+ * is the industry's de facto standard. *\r
* *\r
- * http://www.FreeRTOS.org/FAQHelp.html *\r
+ * Help yourself get started quickly while simultaneously helping *\r
+ * to support the FreeRTOS project by purchasing a FreeRTOS *\r
+ * tutorial book, reference manual, or both: *\r
+ * http://www.FreeRTOS.org/Documentation *\r
* *\r
***************************************************************************\r
\r
- http://www.FreeRTOS.org - Documentation, books, training, latest versions,\r
- license and Real Time Engineers Ltd. contact details.\r
+ http://www.FreeRTOS.org/FAQHelp.html - Having a problem? Start by reading\r
+ the FAQ page "My application does not run, what could be wrong?". Have you\r
+ defined configASSERT()?\r
+\r
+ http://www.FreeRTOS.org/support - In return for receiving this top quality\r
+ embedded software for free we request you assist our global community by\r
+ participating in the support forum.\r
+\r
+ http://www.FreeRTOS.org/training - Investing in training allows your team to\r
+ be as productive as possible as early as possible. Now you can receive\r
+ FreeRTOS training directly from Richard Barry, CEO of Real Time Engineers\r
+ Ltd, and the world's leading authority on the world's leading RTOS.\r
\r
http://www.FreeRTOS.org/plus - A selection of FreeRTOS ecosystem products,\r
including FreeRTOS+Trace - an indispensable productivity tool, a DOS\r
compatible FAT file system, and our tiny thread aware UDP/IP stack.\r
\r
- http://www.OpenRTOS.com - Real Time Engineers ltd license FreeRTOS to High\r
- Integrity Systems to sell under the OpenRTOS brand. Low cost OpenRTOS\r
- licenses offer ticketed support, indemnification and middleware.\r
+ http://www.FreeRTOS.org/labs - Where new FreeRTOS products go to incubate.\r
+ Come and try FreeRTOS+TCP, our new open source TCP/IP stack for FreeRTOS.\r
+\r
+ http://www.OpenRTOS.com - Real Time Engineers ltd. license FreeRTOS to High\r
+ Integrity Systems ltd. to sell under the OpenRTOS brand. Low cost OpenRTOS\r
+ licenses offer ticketed support, indemnification and commercial middleware.\r
\r
http://www.SafeRTOS.com - High Integrity Systems also provide a safety\r
engineered and independently SIL3 certified version for use in safety and\r
* semphr. h\r
* <pre>vSemaphoreCreateBinary( SemaphoreHandle_t xSemaphore )</pre>\r
*\r
+ * In many usage scenarios it is faster and more memory efficient to use a\r
+ * direct to task notification in place of a binary semaphore!\r
+ * http://www.freertos.org/RTOS-task-notifications.html\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
* \defgroup vSemaphoreCreateBinary vSemaphoreCreateBinary\r
* \ingroup Semaphores\r
*/\r
-#define vSemaphoreCreateBinary( xSemaphore ) \\r
- { \\r
- ( xSemaphore ) = xQueueGenericCreate( ( UBaseType_t ) 1, semSEMAPHORE_QUEUE_ITEM_LENGTH, queueQUEUE_TYPE_BINARY_SEMAPHORE ); \\r
- if( ( xSemaphore ) != NULL ) \\r
- { \\r
- ( void ) xSemaphoreGive( ( xSemaphore ) ); \\r
- } \\r
- }\r
+#if( configSUPPORT_DYNAMIC_ALLOCATION == 1 )\r
+ #define vSemaphoreCreateBinary( xSemaphore ) \\r
+ { \\r
+ ( xSemaphore ) = xQueueGenericCreate( ( UBaseType_t ) 1, semSEMAPHORE_QUEUE_ITEM_LENGTH, queueQUEUE_TYPE_BINARY_SEMAPHORE ); \\r
+ if( ( xSemaphore ) != NULL ) \\r
+ { \\r
+ ( void ) xSemaphoreGive( ( xSemaphore ) ); \\r
+ } \\r
+ }\r
+#endif\r
\r
/**\r
* semphr. h\r
* <pre>SemaphoreHandle_t xSemaphoreCreateBinary( void )</pre>\r
*\r
+ * Creates a new binary semaphore instance, and returns a handle by which the\r
+ * new semaphore can be referenced.\r
+ *\r
+ * In many usage scenarios it is faster and more memory efficient to use a\r
+ * direct to task notification in place of a binary semaphore!\r
+ * http://www.freertos.org/RTOS-task-notifications.html\r
+ *\r
+ * Internally, within the FreeRTOS implementation, binary semaphores use a block\r
+ * of memory, in which the semaphore structure is stored. If a binary semaphore\r
+ * is created using xSemaphoreCreateBinary() then the required memory is\r
+ * automatically dynamically allocated inside the xSemaphoreCreateBinary()\r
+ * function. (see http://www.freertos.org/a00111.html). If a binary semaphore\r
+ * is created using xSemaphoreCreateBinaryStatic() then the application writer\r
+ * must provide the memory. xSemaphoreCreateBinaryStatic() therefore allows a\r
+ * binary semaphore to be created without using any dynamic memory allocation.\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
* 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
* 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
+ * @return Handle to the created semaphore, or NULL if the memory required to\r
+ * hold the semaphore's data structures could not be allocated.\r
*\r
* Example usage:\r
<pre>\r
\r
void vATask( void * pvParameters )\r
{\r
- // Semaphore cannot be used before a call to vSemaphoreCreateBinary ().\r
+ // Semaphore cannot be used before a call to xSemaphoreCreateBinary().\r
// This is a macro so pass the variable in directly.\r
xSemaphore = xSemaphoreCreateBinary();\r
\r
}\r
}\r
</pre>\r
- * \defgroup vSemaphoreCreateBinary vSemaphoreCreateBinary\r
+ * \defgroup xSemaphoreCreateBinary xSemaphoreCreateBinary\r
* \ingroup Semaphores\r
*/\r
-#define xSemaphoreCreateBinary() xQueueGenericCreate( ( UBaseType_t ) 1, semSEMAPHORE_QUEUE_ITEM_LENGTH, queueQUEUE_TYPE_BINARY_SEMAPHORE )\r
+#if( configSUPPORT_DYNAMIC_ALLOCATION == 1 )\r
+ #define xSemaphoreCreateBinary() xQueueGenericCreate( ( UBaseType_t ) 1, semSEMAPHORE_QUEUE_ITEM_LENGTH, queueQUEUE_TYPE_BINARY_SEMAPHORE )\r
+#endif\r
+\r
+/**\r
+ * semphr. h\r
+ * <pre>SemaphoreHandle_t xSemaphoreCreateBinaryStatic( StaticSemaphore_t *pxSemaphoreBuffer )</pre>\r
+ *\r
+ * Creates a new binary semaphore instance, and returns a handle by which the\r
+ * new semaphore can be referenced.\r
+ *\r
+ * NOTE: In many usage scenarios it is faster and more memory efficient to use a\r
+ * direct to task notification in place of a binary semaphore!\r
+ * http://www.freertos.org/RTOS-task-notifications.html\r
+ *\r
+ * Internally, within the FreeRTOS implementation, binary semaphores use a block\r
+ * of memory, in which the semaphore structure is stored. If a binary semaphore\r
+ * is created using xSemaphoreCreateBinary() then the required memory is\r
+ * automatically dynamically allocated inside the xSemaphoreCreateBinary()\r
+ * function. (see http://www.freertos.org/a00111.html). If a binary semaphore\r
+ * is created using xSemaphoreCreateBinaryStatic() then the application writer\r
+ * must provide the memory. xSemaphoreCreateBinaryStatic() therefore allows a\r
+ * binary semaphore to be created without using any dynamic memory allocation.\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
+ * @param pxSemaphoreBuffer Must point to a variable of type StaticSemaphore_t,\r
+ * which will then be used to hold the semaphore's data structure, removing the\r
+ * need for the memory to be allocated dynamically.\r
+ *\r
+ * @return If the semaphore is created then a handle to the created semaphore is\r
+ * returned. If pxSemaphoreBuffer is NULL then NULL is returned.\r
+ *\r
+ * Example usage:\r
+ <pre>\r
+ SemaphoreHandle_t xSemaphore = NULL;\r
+ StaticSemaphore_t xSemaphoreBuffer;\r
+\r
+ void vATask( void * pvParameters )\r
+ {\r
+ // Semaphore cannot be used before a call to xSemaphoreCreateBinary().\r
+ // The semaphore's data structures will be placed in the xSemaphoreBuffer\r
+ // variable, the address of which is passed into the function. The\r
+ // function's parameter is not NULL, so the function will not attempt any\r
+ // dynamic memory allocation, and therefore the function will not return\r
+ // return NULL.\r
+ xSemaphore = xSemaphoreCreateBinary( &xSemaphoreBuffer );\r
+\r
+ // Rest of task code goes here.\r
+ }\r
+ </pre>\r
+ * \defgroup xSemaphoreCreateBinaryStatic xSemaphoreCreateBinaryStatic\r
+ * \ingroup Semaphores\r
+ */\r
+#if( configSUPPORT_STATIC_ALLOCATION == 1 )\r
+ #define xSemaphoreCreateBinaryStatic( pxStaticSemaphore ) xQueueGenericCreateStatic( ( UBaseType_t ) 1, semSEMAPHORE_QUEUE_ITEM_LENGTH, NULL, pxStaticSemaphore, queueQUEUE_TYPE_BINARY_SEMAPHORE )\r
+#endif /* configSUPPORT_STATIC_ALLOCATION */\r
\r
/**\r
* semphr. h\r
* )</pre>\r
*\r
* <i>Macro</i> to obtain a semaphore. The semaphore must have previously been\r
- * created with a call to vSemaphoreCreateBinary(), xSemaphoreCreateMutex() or\r
+ * created with a call to xSemaphoreCreateBinary(), xSemaphoreCreateMutex() or\r
* xSemaphoreCreateCounting().\r
*\r
* @param xSemaphore A handle to the semaphore being taken - obtained when\r
void vATask( void * pvParameters )\r
{\r
// Create the semaphore to guard a shared resource.\r
- vSemaphoreCreateBinary( xSemaphore );\r
+ xSemaphore = xSemaphoreCreateBinary();\r
}\r
\r
// A task that uses the semaphore.\r
* \defgroup xSemaphoreTakeRecursive xSemaphoreTakeRecursive\r
* \ingroup Semaphores\r
*/\r
-#define xSemaphoreTakeRecursive( xMutex, xBlockTime ) xQueueTakeMutexRecursive( ( xMutex ), ( xBlockTime ) )\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
- * responsiveness to gain execution speed, whereas the fully featured API\r
- * sacrifices execution speed to ensure better interrupt responsiveness.\r
- */\r
-#define xSemaphoreAltTake( xSemaphore, xBlockTime ) xQueueAltGenericReceive( ( QueueHandle_t ) ( xSemaphore ), NULL, ( xBlockTime ), pdFALSE )\r
+#if( configUSE_RECURSIVE_MUTEXES == 1 )\r
+ #define xSemaphoreTakeRecursive( xMutex, xBlockTime ) xQueueTakeMutexRecursive( ( xMutex ), ( xBlockTime ) )\r
+#endif\r
\r
/**\r
* semphr. h\r
* <pre>xSemaphoreGive( SemaphoreHandle_t xSemaphore )</pre>\r
*\r
* <i>Macro</i> to release a semaphore. The semaphore must have previously been\r
- * created with a call to vSemaphoreCreateBinary(), xSemaphoreCreateMutex() or\r
+ * created with a call to xSemaphoreCreateBinary(), xSemaphoreCreateMutex() or\r
* xSemaphoreCreateCounting(). and obtained using sSemaphoreTake().\r
*\r
* This macro must not be used from an ISR. See xSemaphoreGiveFromISR () for\r
void vATask( void * pvParameters )\r
{\r
// Create the semaphore to guard a shared resource.\r
- vSemaphoreCreateBinary( xSemaphore );\r
+ xSemaphore = vSemaphoreCreateBinary();\r
\r
if( xSemaphore != NULL )\r
{\r
* \defgroup xSemaphoreGiveRecursive xSemaphoreGiveRecursive\r
* \ingroup Semaphores\r
*/\r
-#define xSemaphoreGiveRecursive( xMutex ) xQueueGiveMutexRecursive( ( xMutex ) )\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
- * responsiveness to gain execution speed, whereas the fully featured API\r
- * sacrifices execution speed to ensure better interrupt responsiveness.\r
- */\r
-#define xSemaphoreAltGive( xSemaphore ) xQueueAltGenericSend( ( QueueHandle_t ) ( xSemaphore ), NULL, semGIVE_BLOCK_TIME, queueSEND_TO_BACK )\r
+#if( configUSE_RECURSIVE_MUTEXES == 1 )\r
+ #define xSemaphoreGiveRecursive( xMutex ) xQueueGiveMutexRecursive( ( xMutex ) )\r
+#endif\r
\r
/**\r
* semphr. h\r
)</pre>\r
*\r
* <i>Macro</i> to release a semaphore. The semaphore must have previously been\r
- * created with a call to vSemaphoreCreateBinary() or xSemaphoreCreateCounting().\r
+ * created with a call to xSemaphoreCreateBinary() or xSemaphoreCreateCounting().\r
*\r
* Mutex type semaphores (those created using a call to xSemaphoreCreateMutex())\r
* must not be used with this macro.\r
* \defgroup xSemaphoreGiveFromISR xSemaphoreGiveFromISR\r
* \ingroup Semaphores\r
*/\r
-#define xSemaphoreGiveFromISR( xSemaphore, pxHigherPriorityTaskWoken ) xQueueGenericGiveFromISR( ( QueueHandle_t ) ( xSemaphore ), ( pxHigherPriorityTaskWoken ) )\r
+#define xSemaphoreGiveFromISR( xSemaphore, pxHigherPriorityTaskWoken ) xQueueGiveFromISR( ( QueueHandle_t ) ( xSemaphore ), ( pxHigherPriorityTaskWoken ) )\r
\r
/**\r
* semphr. h\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
+ * previously been created with a call to xSemaphoreCreateBinary() or\r
* xSemaphoreCreateCounting().\r
*\r
* Mutex type semaphores (those created using a call to xSemaphoreCreateMutex())\r
* semphr. h\r
* <pre>SemaphoreHandle_t xSemaphoreCreateMutex( void )</pre>\r
*\r
- * <i>Macro</i> that implements a mutex semaphore by using the existing queue\r
- * mechanism.\r
+ * Creates a new mutex type semaphore instance, and returns a handle by which\r
+ * the new mutex can be referenced.\r
+ *\r
+ * Internally, within the FreeRTOS implementation, mutex semaphores use a block\r
+ * of memory, in which the mutex structure is stored. If a mutex is created\r
+ * using xSemaphoreCreateMutex() then the required memory is automatically\r
+ * dynamically allocated inside the xSemaphoreCreateMutex() function. (see\r
+ * http://www.freertos.org/a00111.html). If a mutex is created using\r
+ * xSemaphoreCreateMutexStatic() then the application writer must provided the\r
+ * memory. xSemaphoreCreateMutexStatic() therefore allows a mutex to be created\r
+ * without using any dynamic memory allocation.\r
*\r
- * Mutexes created using this macro can be accessed using the xSemaphoreTake()\r
+ * Mutexes created using this function can be accessed using the xSemaphoreTake()\r
* and xSemaphoreGive() macros. The xSemaphoreTakeRecursive() and\r
- * xSemaphoreGiveRecursive() macros should not be used.\r
+ * xSemaphoreGiveRecursive() macros must 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
*\r
* Mutex type semaphores cannot be used from within interrupt service routines.\r
*\r
- * See vSemaphoreCreateBinary() for an alternative implementation that can be\r
+ * See xSemaphoreCreateBinary() 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
- * SemaphoreHandle_t.\r
+ * @return If the mutex was successfully created then a handle to the created\r
+ * semaphore is returned. If there was not enough heap to allocate the mutex\r
+ * data structures then NULL is returned.\r
*\r
* Example usage:\r
<pre>\r
}\r
}\r
</pre>\r
- * \defgroup vSemaphoreCreateMutex vSemaphoreCreateMutex\r
+ * \defgroup xSemaphoreCreateMutex xSemaphoreCreateMutex\r
* \ingroup Semaphores\r
*/\r
-#define xSemaphoreCreateMutex() xQueueCreateMutex( queueQUEUE_TYPE_MUTEX )\r
+#if( configSUPPORT_DYNAMIC_ALLOCATION == 1 )\r
+ #define xSemaphoreCreateMutex() xQueueCreateMutex( queueQUEUE_TYPE_MUTEX )\r
+#endif\r
+\r
+/**\r
+ * semphr. h\r
+ * <pre>SemaphoreHandle_t xSemaphoreCreateMutexStatic( StaticSemaphore_t *pxMutexBuffer )</pre>\r
+ *\r
+ * Creates a new mutex type semaphore instance, and returns a handle by which\r
+ * the new mutex can be referenced.\r
+ *\r
+ * Internally, within the FreeRTOS implementation, mutex semaphores use a block\r
+ * of memory, in which the mutex structure is stored. If a mutex is created\r
+ * using xSemaphoreCreateMutex() then the required memory is automatically\r
+ * dynamically allocated inside the xSemaphoreCreateMutex() function. (see\r
+ * http://www.freertos.org/a00111.html). If a mutex is created using\r
+ * xSemaphoreCreateMutexStatic() then the application writer must provided the\r
+ * memory. xSemaphoreCreateMutexStatic() therefore allows a mutex to be created\r
+ * without using any dynamic memory allocation.\r
+ *\r
+ * Mutexes created using this function can be accessed using the xSemaphoreTake()\r
+ * and xSemaphoreGive() macros. The xSemaphoreTakeRecursive() and\r
+ * xSemaphoreGiveRecursive() macros must 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
+ *\r
+ * See xSemaphoreCreateBinary() 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
+ * @param pxMutexBuffer Must point to a variable of type StaticSemaphore_t,\r
+ * which will be used to hold the mutex's data structure, removing the need for\r
+ * the memory to be allocated dynamically.\r
+ *\r
+ * @return If the mutex was successfully created then a handle to the created\r
+ * mutex is returned. If pxMutexBuffer was NULL then NULL is returned.\r
+ *\r
+ * Example usage:\r
+ <pre>\r
+ SemaphoreHandle_t xSemaphore;\r
+ StaticSemaphore_t xMutexBuffer;\r
+\r
+ void vATask( void * pvParameters )\r
+ {\r
+ // A mutex cannot be used before it has been created. xMutexBuffer is\r
+ // into xSemaphoreCreateMutexStatic() so no dynamic memory allocation is\r
+ // attempted.\r
+ xSemaphore = xSemaphoreCreateMutexStatic( &xMutexBuffer );\r
+\r
+ // As no dynamic memory allocation was performed, xSemaphore cannot be NULL,\r
+ // so there is no need to check it.\r
+ }\r
+ </pre>\r
+ * \defgroup xSemaphoreCreateMutexStatic xSemaphoreCreateMutexStatic\r
+ * \ingroup Semaphores\r
+ */\r
+ #if( configSUPPORT_STATIC_ALLOCATION == 1 )\r
+ #define xSemaphoreCreateMutexStatic( pxMutexBuffer ) xQueueCreateMutexStatic( queueQUEUE_TYPE_MUTEX, ( pxMutexBuffer ) )\r
+#endif /* configSUPPORT_STATIC_ALLOCATION */\r
\r
\r
/**\r
* semphr. h\r
* <pre>SemaphoreHandle_t xSemaphoreCreateRecursiveMutex( void )</pre>\r
*\r
- * <i>Macro</i> that implements a recursive mutex by using the existing queue\r
- * mechanism.\r
+ * Creates a new recursive mutex type semaphore instance, and returns a handle\r
+ * by which the new recursive mutex can be referenced.\r
+ *\r
+ * Internally, within the FreeRTOS implementation, recursive mutexs use a block\r
+ * of memory, in which the mutex structure is stored. If a recursive mutex is\r
+ * created using xSemaphoreCreateRecursiveMutex() then the required memory is\r
+ * automatically dynamically allocated inside the\r
+ * xSemaphoreCreateRecursiveMutex() function. (see\r
+ * http://www.freertos.org/a00111.html). If a recursive mutex is created using\r
+ * xSemaphoreCreateRecursiveMutexStatic() then the application writer must\r
+ * provide the memory that will get used by the mutex.\r
+ * xSemaphoreCreateRecursiveMutexStatic() therefore allows a recursive mutex to\r
+ * be created without using any dynamic memory allocation.\r
*\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
+ * xSemaphoreTake() and xSemaphoreGive() macros must 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
*\r
* Mutex type semaphores cannot be used from within interrupt service routines.\r
*\r
- * See vSemaphoreCreateBinary() for an alternative implementation that can be\r
+ * See xSemaphoreCreateBinary() 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
- * SemaphoreHandle_t.\r
+ * SemaphoreHandle_t.\r
*\r
* Example usage:\r
<pre>\r
}\r
}\r
</pre>\r
- * \defgroup vSemaphoreCreateMutex vSemaphoreCreateMutex\r
+ * \defgroup xSemaphoreCreateRecursiveMutex xSemaphoreCreateRecursiveMutex\r
+ * \ingroup Semaphores\r
+ */\r
+#if( ( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) && ( configUSE_RECURSIVE_MUTEXES == 1 ) )\r
+ #define xSemaphoreCreateRecursiveMutex() xQueueCreateMutex( queueQUEUE_TYPE_RECURSIVE_MUTEX )\r
+#endif\r
+\r
+/**\r
+ * semphr. h\r
+ * <pre>SemaphoreHandle_t xSemaphoreCreateRecursiveMutexStatic( StaticSemaphore_t *pxMutexBuffer )</pre>\r
+ *\r
+ * Creates a new recursive mutex type semaphore instance, and returns a handle\r
+ * by which the new recursive mutex can be referenced.\r
+ *\r
+ * Internally, within the FreeRTOS implementation, recursive mutexs use a block\r
+ * of memory, in which the mutex structure is stored. If a recursive mutex is\r
+ * created using xSemaphoreCreateRecursiveMutex() then the required memory is\r
+ * automatically dynamically allocated inside the\r
+ * xSemaphoreCreateRecursiveMutex() function. (see\r
+ * http://www.freertos.org/a00111.html). If a recursive mutex is created using\r
+ * xSemaphoreCreateRecursiveMutexStatic() then the application writer must\r
+ * provide the memory that will get used by the mutex.\r
+ * xSemaphoreCreateRecursiveMutexStatic() therefore allows a recursive mutex to\r
+ * be created without using any dynamic memory allocation.\r
+ *\r
+ * Mutexes created using this macro can be accessed using the\r
+ * xSemaphoreTakeRecursive() and xSemaphoreGiveRecursive() macros. The\r
+ * xSemaphoreTake() and xSemaphoreGive() macros must 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
+ * 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
+ *\r
+ * See xSemaphoreCreateBinary() 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
+ * @param pxMutexBuffer Must point to a variable of type StaticSemaphore_t,\r
+ * which will then be used to hold the recursive mutex's data structure,\r
+ * removing the need for the memory to be allocated dynamically.\r
+ *\r
+ * @return If the recursive mutex was successfully created then a handle to the\r
+ * created recursive mutex is returned. If pxMutexBuffer was NULL then NULL is\r
+ * returned.\r
+ *\r
+ * Example usage:\r
+ <pre>\r
+ SemaphoreHandle_t xSemaphore;\r
+ StaticSemaphore_t xMutexBuffer;\r
+\r
+ void vATask( void * pvParameters )\r
+ {\r
+ // A recursive semaphore cannot be used before it is created. Here a\r
+ // recursive mutex is created using xSemaphoreCreateRecursiveMutexStatic().\r
+ // The address of xMutexBuffer is passed into the function, and will hold\r
+ // the mutexes data structures - so no dynamic memory allocation will be\r
+ // attempted.\r
+ xSemaphore = xSemaphoreCreateRecursiveMutexStatic( &xMutexBuffer );\r
+\r
+ // As no dynamic memory allocation was performed, xSemaphore cannot be NULL,\r
+ // so there is no need to check it.\r
+ }\r
+ </pre>\r
+ * \defgroup xSemaphoreCreateRecursiveMutexStatic xSemaphoreCreateRecursiveMutexStatic\r
* \ingroup Semaphores\r
*/\r
-#define xSemaphoreCreateRecursiveMutex() xQueueCreateMutex( queueQUEUE_TYPE_RECURSIVE_MUTEX )\r
+#if( ( configSUPPORT_STATIC_ALLOCATION == 1 ) && ( configUSE_RECURSIVE_MUTEXES == 1 ) )\r
+ #define xSemaphoreCreateRecursiveMutexStatic( pxStaticSemaphore ) xQueueCreateMutexStatic( queueQUEUE_TYPE_RECURSIVE_MUTEX, pxStaticSemaphore )\r
+#endif /* configSUPPORT_STATIC_ALLOCATION */\r
\r
/**\r
* semphr. h\r
* <pre>SemaphoreHandle_t xSemaphoreCreateCounting( UBaseType_t uxMaxCount, UBaseType_t uxInitialCount )</pre>\r
*\r
- * <i>Macro</i> that creates a counting semaphore by using the existing\r
- * queue mechanism.\r
+ * Creates a new counting semaphore instance, and returns a handle by which the\r
+ * new counting semaphore can be referenced.\r
+ *\r
+ * In many usage scenarios it is faster and more memory efficient to use a\r
+ * direct to task notification in place of a counting semaphore!\r
+ * http://www.freertos.org/RTOS-task-notifications.html\r
+ *\r
+ * Internally, within the FreeRTOS implementation, counting semaphores use a\r
+ * block of memory, in which the counting semaphore structure is stored. If a\r
+ * counting semaphore is created using xSemaphoreCreateCounting() then the\r
+ * required memory is automatically dynamically allocated inside the\r
+ * xSemaphoreCreateCounting() function. (see\r
+ * http://www.freertos.org/a00111.html). If a counting semaphore is created\r
+ * using xSemaphoreCreateCountingStatic() then the application writer can\r
+ * instead optionally provide the memory that will get used by the counting\r
+ * semaphore. xSemaphoreCreateCountingStatic() therefore allows a counting\r
+ * semaphore to be created without using any dynamic memory allocation.\r
*\r
* Counting semaphores are typically used for two things:\r
*\r
* \defgroup xSemaphoreCreateCounting xSemaphoreCreateCounting\r
* \ingroup Semaphores\r
*/\r
-#define xSemaphoreCreateCounting( uxMaxCount, uxInitialCount ) xQueueCreateCountingSemaphore( ( uxMaxCount ), ( uxInitialCount ) )\r
+#if( configSUPPORT_DYNAMIC_ALLOCATION == 1 )\r
+ #define xSemaphoreCreateCounting( uxMaxCount, uxInitialCount ) xQueueCreateCountingSemaphore( ( uxMaxCount ), ( uxInitialCount ) )\r
+#endif\r
+\r
+/**\r
+ * semphr. h\r
+ * <pre>SemaphoreHandle_t xSemaphoreCreateCountingStatic( UBaseType_t uxMaxCount, UBaseType_t uxInitialCount, StaticSemaphore_t *pxSemaphoreBuffer )</pre>\r
+ *\r
+ * Creates a new counting semaphore instance, and returns a handle by which the\r
+ * new counting semaphore can be referenced.\r
+ *\r
+ * In many usage scenarios it is faster and more memory efficient to use a\r
+ * direct to task notification in place of a counting semaphore!\r
+ * http://www.freertos.org/RTOS-task-notifications.html\r
+ *\r
+ * Internally, within the FreeRTOS implementation, counting semaphores use a\r
+ * block of memory, in which the counting semaphore structure is stored. If a\r
+ * counting semaphore is created using xSemaphoreCreateCounting() then the\r
+ * required memory is automatically dynamically allocated inside the\r
+ * xSemaphoreCreateCounting() function. (see\r
+ * http://www.freertos.org/a00111.html). If a counting semaphore is created\r
+ * using xSemaphoreCreateCountingStatic() then the application writer must\r
+ * provide the memory. xSemaphoreCreateCountingStatic() therefore allows a\r
+ * counting semaphore to be created without using any dynamic memory allocation.\r
+ *\r
+ * Counting semaphores are typically used for two things:\r
+ *\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
+ * 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
+ * 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
+ * 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
+ * created.\r
+ *\r
+ * @param pxSemaphoreBuffer Must point to a variable of type StaticSemaphore_t,\r
+ * which will then be used to hold the semaphore's data structure, removing the\r
+ * need for the memory to be allocated dynamically.\r
+ *\r
+ * @return If the counting semaphore was successfully created then a handle to\r
+ * the created counting semaphore is returned. If pxSemaphoreBuffer was NULL\r
+ * then NULL is returned.\r
+ *\r
+ * Example usage:\r
+ <pre>\r
+ SemaphoreHandle_t xSemaphore;\r
+ StaticSemaphore_t xSemaphoreBuffer;\r
+\r
+ void vATask( void * pvParameters )\r
+ {\r
+ SemaphoreHandle_t xSemaphore = NULL;\r
+\r
+ // Counting semaphore cannot be used before they have been created. Create\r
+ // a counting semaphore using xSemaphoreCreateCountingStatic(). The max\r
+ // value to which the semaphore can count is 10, and the initial value\r
+ // assigned to the count will be 0. The address of xSemaphoreBuffer is\r
+ // passed in and will be used to hold the semaphore structure, so no dynamic\r
+ // memory allocation will be used.\r
+ xSemaphore = xSemaphoreCreateCounting( 10, 0, &xSemaphoreBuffer );\r
+\r
+ // No memory allocation was attempted so xSemaphore cannot be NULL, so there\r
+ // is no need to check its value.\r
+ }\r
+ </pre>\r
+ * \defgroup xSemaphoreCreateCountingStatic xSemaphoreCreateCountingStatic\r
+ * \ingroup Semaphores\r
+ */\r
+#if( configSUPPORT_STATIC_ALLOCATION == 1 )\r
+ #define xSemaphoreCreateCountingStatic( uxMaxCount, uxInitialCount, pxSemaphoreBuffer ) xQueueCreateCountingSemaphoreStatic( ( uxMaxCount ), ( uxInitialCount ), ( pxSemaphoreBuffer ) )\r
+#endif /* configSUPPORT_STATIC_ALLOCATION */\r
\r
/**\r
* semphr. h\r
*/\r
#define xSemaphoreGetMutexHolder( xSemaphore ) xQueueGetMutexHolder( ( xSemaphore ) )\r
\r
+/**\r
+ * semphr.h\r
+ * <pre>TaskHandle_t xSemaphoreGetMutexHolderFromISR( SemaphoreHandle_t xMutex );</pre>\r
+ *\r
+ * If xMutex is indeed a mutex type semaphore, return the current mutex holder.\r
+ * If xMutex is not a mutex type semaphore, or the mutex is available (not held\r
+ * by a task), return NULL.\r
+ *\r
+ */\r
+#define xSemaphoreGetMutexHolderFromISR( xSemaphore ) xQueueGetMutexHolderFromISR( ( xSemaphore ) )\r
+\r
+/**\r
+ * semphr.h\r
+ * <pre>UBaseType_t uxSemaphoreGetCount( SemaphoreHandle_t xSemaphore );</pre>\r
+ *\r
+ * If the semaphore is a counting semaphore then uxSemaphoreGetCount() returns\r
+ * its current count value. If the semaphore is a binary semaphore then\r
+ * uxSemaphoreGetCount() returns 1 if the semaphore is available, and 0 if the\r
+ * semaphore is not available.\r
+ *\r
+ */\r
+#define uxSemaphoreGetCount( xSemaphore ) uxQueueMessagesWaiting( ( QueueHandle_t ) ( xSemaphore ) )\r
+\r
#endif /* SEMAPHORE_H */\r
\r
\r
projects / freertos / blobdiff