/*\r
- FreeRTOS V7.4.0 - Copyright (C) 2013 Real Time Engineers Ltd.\r
-\r
- FEATURES AND PORTS ARE ADDED TO FREERTOS ALL THE TIME. PLEASE VISIT\r
- http://www.FreeRTOS.org TO ENSURE YOU ARE USING THE LATEST VERSION.\r
-\r
- ***************************************************************************\r
- * *\r
- * FreeRTOS tutorial books are available in pdf and paperback. *\r
- * Complete, revised, and edited pdf reference manuals are also *\r
- * available. *\r
- * *\r
- * Purchasing FreeRTOS documentation will not only help you, by *\r
- * ensuring you get running as quickly as possible and with an *\r
- * in-depth knowledge of how to use FreeRTOS, it will also help *\r
- * the FreeRTOS project to continue with its mission of providing *\r
- * professional grade, cross platform, de facto standard solutions *\r
- * for microcontrollers - completely free of charge! *\r
- * *\r
- * >>> See http://www.FreeRTOS.org/Documentation for details. <<< *\r
- * *\r
- * Thank you for using FreeRTOS, and thank you for your support! *\r
- * *\r
- ***************************************************************************\r
+ FreeRTOS V9.0.0rc1 - 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
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
- >>>>>>NOTE<<<<<< The modification to the GPL is included to allow you to\r
- distribute a combined work that includes FreeRTOS without being obliged to\r
- provide the source code for proprietary components outside of the FreeRTOS\r
- kernel.\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. See the GNU General Public License for more\r
- details. You should have received a copy of the GNU General Public License\r
- and the FreeRTOS license exception along with FreeRTOS; if not itcan be\r
- viewed here: http://www.freertos.org/a00114.html and also obtained by\r
- writing to Real Time Engineers Ltd., contact details for whom are available\r
- on the FreeRTOS WEB site.\r
-\r
- 1 tab == 4 spaces!\r
+ FOR A PARTICULAR PURPOSE. Full license text is available on the following\r
+ link: http://www.freertos.org/a00114.html\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/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 - Documentation, books, training, latest versions, \r
- license and Real Time Engineers Ltd. contact details.\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, and our new\r
- fully thread aware and reentrant UDP/IP stack.\r
-\r
- http://www.OpenRTOS.com - Real Time Engineers ltd license FreeRTOS to High \r
- Integrity Systems, who sell the code with commercial support, \r
- indemnification and middleware, under the OpenRTOS brand.\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
+ 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.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
mission critical applications that require provable dependability.\r
+\r
+ 1 tab == 4 spaces!\r
*/\r
\r
#ifndef SEMAPHORE_H\r
\r
#include "queue.h"\r
\r
-typedef xQueueHandle xSemaphoreHandle;\r
+typedef QueueHandle_t SemaphoreHandle_t;\r
\r
-#define semBINARY_SEMAPHORE_QUEUE_LENGTH ( ( unsigned char ) 1U )\r
-#define semSEMAPHORE_QUEUE_ITEM_LENGTH ( ( unsigned char ) 0U )\r
-#define semGIVE_BLOCK_TIME ( ( portTickType ) 0U )\r
+#define semBINARY_SEMAPHORE_QUEUE_LENGTH ( ( uint8_t ) 1U )\r
+#define semSEMAPHORE_QUEUE_ITEM_LENGTH ( ( uint8_t ) 0U )\r
+#define semGIVE_BLOCK_TIME ( ( TickType_t ) 0U )\r
\r
\r
/**\r
* semphr. h\r
- * <pre>vSemaphoreCreateBinary( xSemaphoreHandle xSemaphore )</pre>\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
+ * 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
* semaphore does not use a priority inheritance mechanism. For an alternative\r
* that does use priority inheritance see xSemaphoreCreateMutex().\r
*\r
- * @param xSemaphore Handle to the created semaphore. Should be of type xSemaphoreHandle.\r
+ * @param xSemaphore Handle to the created semaphore. Should be of type SemaphoreHandle_t.\r
*\r
* Example usage:\r
<pre>\r
- xSemaphoreHandle xSemaphore;\r
+ SemaphoreHandle_t 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
* \defgroup vSemaphoreCreateBinary vSemaphoreCreateBinary\r
* \ingroup Semaphores\r
*/\r
-#define vSemaphoreCreateBinary( xSemaphore ) \\r
- { \\r
- ( xSemaphore ) = xQueueGenericCreate( ( unsigned portBASE_TYPE ) 1, semSEMAPHORE_QUEUE_ITEM_LENGTH, queueQUEUE_TYPE_BINARY_SEMAPHORE ); \\r
- if( ( xSemaphore ) != NULL ) \\r
- { \\r
- 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
+ * 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
+ * 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, 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
+ SemaphoreHandle_t xSemaphore = NULL;\r
+\r
+ void vATask( void * pvParameters )\r
+ {\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
+ if( xSemaphore != NULL )\r
+ {\r
+ // The semaphore was created successfully.\r
+ // The semaphore can now be used.\r
+ }\r
+ }\r
+ </pre>\r
+ * \defgroup xSemaphoreCreateBinary xSemaphoreCreateBinary\r
+ * \ingroup Semaphores\r
+ */\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>xSemaphoreTake( \r
- * xSemaphoreHandle xSemaphore, \r
- * portTickType xBlockTime \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>xSemaphoreTake(\r
+ * SemaphoreHandle_t xSemaphore,\r
+ * TickType_t xBlockTime\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
* the semaphore was created.\r
*\r
* @param xBlockTime The time in ticks to wait for the semaphore to become\r
- * available. The macro portTICK_RATE_MS can be used to convert this to a\r
+ * available. The macro portTICK_PERIOD_MS can be used to convert this to a\r
* real time. A block time of zero can be used to poll the semaphore. A block\r
* time of portMAX_DELAY can be used to block indefinitely (provided\r
* INCLUDE_vTaskSuspend is set to 1 in FreeRTOSConfig.h).\r
*\r
* Example usage:\r
<pre>\r
- xSemaphoreHandle xSemaphore = NULL;\r
+ SemaphoreHandle_t xSemaphore = NULL;\r
\r
// A task that creates a semaphore.\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
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
- if( xSemaphoreTake( xSemaphore, ( portTickType ) 10 ) == pdTRUE )\r
+ // wait 10 ticks to see if it becomes free.\r
+ if( xSemaphoreTake( xSemaphore, ( TickType_t ) 10 ) == pdTRUE )\r
{\r
// We were able to obtain the semaphore and can now access the\r
// shared resource.\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
* \defgroup xSemaphoreTake xSemaphoreTake\r
* \ingroup Semaphores\r
*/\r
-#define xSemaphoreTake( xSemaphore, xBlockTime ) xQueueGenericReceive( ( xQueueHandle ) ( xSemaphore ), NULL, ( xBlockTime ), pdFALSE )\r
+#define xSemaphoreTake( xSemaphore, xBlockTime ) xQueueGenericReceive( ( QueueHandle_t ) ( xSemaphore ), NULL, ( xBlockTime ), pdFALSE )\r
\r
/**\r
* semphr. h\r
- * xSemaphoreTakeRecursive( \r
- * xSemaphoreHandle xMutex, \r
- * portTickType xBlockTime \r
+ * xSemaphoreTakeRecursive(\r
+ * SemaphoreHandle_t xMutex,\r
+ * TickType_t 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
* handle returned by xSemaphoreCreateRecursiveMutex();\r
*\r
* @param xBlockTime The time in ticks to wait for the semaphore to become\r
- * available. The macro portTICK_RATE_MS can be used to convert this to a\r
+ * available. The macro portTICK_PERIOD_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
*\r
* Example usage:\r
<pre>\r
- xSemaphoreHandle xMutex = NULL;\r
+ SemaphoreHandle_t xMutex = NULL;\r
\r
// A task that creates a mutex.\r
void vATask( void * pvParameters )\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
- if( xSemaphoreTakeRecursive( xSemaphore, ( portTickType ) 10 ) == pdTRUE )\r
+ // wait 10 ticks to see if it becomes free.\r
+ if( xSemaphoreTakeRecursive( xSemaphore, ( TickType_t ) 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
// a more complex call structure.\r
- xSemaphoreTakeRecursive( xMutex, ( portTickType ) 10 );\r
- xSemaphoreTakeRecursive( xMutex, ( portTickType ) 10 );\r
+ xSemaphoreTakeRecursive( xMutex, ( TickType_t ) 10 );\r
+ xSemaphoreTakeRecursive( xMutex, ( TickType_t ) 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
*/\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( ( xQueueHandle ) ( xSemaphore ), NULL, ( xBlockTime ), pdFALSE )\r
-\r
/**\r
* semphr. h\r
- * <pre>xSemaphoreGive( xSemaphoreHandle xSemaphore )</pre>\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
* 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>\r
- xSemaphoreHandle xSemaphore = NULL;\r
+ SemaphoreHandle_t xSemaphore = NULL;\r
\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
\r
// Obtain the semaphore - don't block if the semaphore is not\r
// immediately available.\r
- if( xSemaphoreTake( xSemaphore, ( portTickType ) 0 ) )\r
+ if( xSemaphoreTake( xSemaphore, ( TickType_t ) 0 ) )\r
{\r
// We now have the semaphore and can access the shared resource.\r
\r
* \defgroup xSemaphoreGive xSemaphoreGive\r
* \ingroup Semaphores\r
*/\r
-#define xSemaphoreGive( xSemaphore ) xQueueGenericSend( ( xQueueHandle ) ( xSemaphore ), NULL, semGIVE_BLOCK_TIME, queueSEND_TO_BACK )\r
+#define xSemaphoreGive( xSemaphore ) xQueueGenericSend( ( QueueHandle_t ) ( xSemaphore ), NULL, semGIVE_BLOCK_TIME, queueSEND_TO_BACK )\r
\r
/**\r
* semphr. h\r
- * <pre>xSemaphoreGiveRecursive( xSemaphoreHandle xMutex )</pre>\r
+ * <pre>xSemaphoreGiveRecursive( SemaphoreHandle_t 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
*\r
* Example usage:\r
<pre>\r
- xSemaphoreHandle xMutex = NULL;\r
+ SemaphoreHandle_t xMutex = NULL;\r
\r
// A task that creates a mutex.\r
void vATask( void * pvParameters )\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
- if( xSemaphoreTakeRecursive( xMutex, ( portTickType ) 10 ) == pdTRUE )\r
+ // wait 10 ticks to see if it becomes free.\r
+ if( xSemaphoreTakeRecursive( xMutex, ( TickType_t ) 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
// a more complex call structure.\r
- xSemaphoreTakeRecursive( xMutex, ( portTickType ) 10 );\r
- xSemaphoreTakeRecursive( xMutex, ( portTickType ) 10 );\r
+ xSemaphoreTakeRecursive( xMutex, ( TickType_t ) 10 );\r
+ xSemaphoreTakeRecursive( xMutex, ( TickType_t ) 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
- * 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( ( xQueueHandle ) ( xSemaphore ), NULL, semGIVE_BLOCK_TIME, queueSEND_TO_BACK )\r
-\r
/**\r
* semphr. h\r
* <pre>\r
- xSemaphoreGiveFromISR( \r
- xSemaphoreHandle xSemaphore, \r
- signed portBASE_TYPE *pxHigherPriorityTaskWoken\r
+ xSemaphoreGiveFromISR(\r
+ SemaphoreHandle_t xSemaphore,\r
+ BaseType_t *pxHigherPriorityTaskWoken\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
<pre>\r
\#define LONG_TIME 0xffff\r
\#define TICKS_TO_WAIT 10\r
- xSemaphoreHandle xSemaphore = NULL;\r
+ SemaphoreHandle_t xSemaphore = NULL;\r
\r
// Repetitive task.\r
void vATask( void * pvParameters )\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
// Timer ISR\r
void vTimerISR( void * pvParameters )\r
{\r
- static unsigned char ucLocalTickCount = 0;\r
- static signed portBASE_TYPE xHigherPriorityTaskWoken;\r
+ static uint8_t ucLocalTickCount = 0;\r
+ static BaseType_t xHigherPriorityTaskWoken;\r
\r
// A timer tick has occurred.\r
\r
* \defgroup xSemaphoreGiveFromISR xSemaphoreGiveFromISR\r
* \ingroup Semaphores\r
*/\r
-#define xSemaphoreGiveFromISR( xSemaphore, pxHigherPriorityTaskWoken ) xQueueGenericSendFromISR( ( xQueueHandle ) ( xSemaphore ), NULL, ( pxHigherPriorityTaskWoken ), queueSEND_TO_BACK )\r
+#define xSemaphoreGiveFromISR( xSemaphore, pxHigherPriorityTaskWoken ) xQueueGiveFromISR( ( QueueHandle_t ) ( xSemaphore ), ( pxHigherPriorityTaskWoken ) )\r
\r
/**\r
* semphr. h\r
* <pre>\r
- xSemaphoreTakeFromISR( \r
- xSemaphoreHandle xSemaphore, \r
- signed portBASE_TYPE *pxHigherPriorityTaskWoken\r
+ xSemaphoreTakeFromISR(\r
+ SemaphoreHandle_t xSemaphore,\r
+ BaseType_t *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 xSemaphoreCreateBinary() 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
+#define xSemaphoreTakeFromISR( xSemaphore, pxHigherPriorityTaskWoken ) xQueueReceiveFromISR( ( QueueHandle_t ) ( xSemaphore ), NULL, ( pxHigherPriorityTaskWoken ) )\r
\r
/**\r
* semphr. h\r
- * <pre>xSemaphoreHandle xSemaphoreCreateMutex( void )</pre>\r
+ * <pre>SemaphoreHandle_t xSemaphoreCreateMutex( void )</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
- * <i>Macro</i> that implements a mutex semaphore by using the existing queue \r
- * mechanism.\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
- * 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
+ * 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
- * 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 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
- * xSemaphoreHandle.\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
- xSemaphoreHandle xSemaphore;\r
+ SemaphoreHandle_t xSemaphore;\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
- * \defgroup vSemaphoreCreateMutex vSemaphoreCreateMutex\r
+ * \defgroup xSemaphoreCreateMutex xSemaphoreCreateMutex\r
* \ingroup Semaphores\r
*/\r
-#define xSemaphoreCreateMutex() xQueueCreateMutex( queueQUEUE_TYPE_MUTEX )\r
-\r
+#if( configSUPPORT_DYNAMIC_ALLOCATION == 1 )\r
+ #define xSemaphoreCreateMutex() xQueueCreateMutex( queueQUEUE_TYPE_MUTEX )\r
+#endif\r
\r
/**\r
* semphr. h\r
- * <pre>xSemaphoreHandle xSemaphoreCreateRecursiveMutex( void )</pre>\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
- * <i>Macro</i> that implements a recursive mutex by using the existing queue \r
- * mechanism.\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
- * 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
+ * @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
- * 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
+ * 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
+ * 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
+ * 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 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
- * xSemaphoreHandle.\r
+ * @return xSemaphore Handle to the created mutex semaphore. Should be of type\r
+ * SemaphoreHandle_t.\r
*\r
* Example usage:\r
<pre>\r
- xSemaphoreHandle xSemaphore;\r
+ SemaphoreHandle_t xSemaphore;\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
- * \defgroup vSemaphoreCreateMutex vSemaphoreCreateMutex\r
+ * \defgroup xSemaphoreCreateRecursiveMutex xSemaphoreCreateRecursiveMutex\r
* \ingroup Semaphores\r
*/\r
-#define xSemaphoreCreateRecursiveMutex() xQueueCreateMutex( queueQUEUE_TYPE_RECURSIVE_MUTEX )\r
+#if( configSUPPORT_DYNAMIC_ALLOCATION == 1 )\r
+ #define xSemaphoreCreateRecursiveMutex() xQueueCreateMutex( queueQUEUE_TYPE_RECURSIVE_MUTEX )\r
+#endif\r
\r
/**\r
* semphr. h\r
- * <pre>xSemaphoreHandle xSemaphoreCreateCounting( unsigned portBASE_TYPE uxMaxCount, unsigned portBASE_TYPE uxInitialCount )</pre>\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
- * <i>Macro</i> that creates a counting semaphore by using the existing \r
- * queue mechanism. \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
+#if( configSUPPORT_STATIC_ALLOCATION == 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
+ * 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
- * 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
+ SemaphoreHandle_t xSemaphore;\r
\r
void vATask( void * pvParameters )\r
{\r
- xSemaphoreHandle xSemaphore = NULL;\r
+ SemaphoreHandle_t xSemaphore = NULL;\r
\r
// Semaphore cannot be used before a call to xSemaphoreCreateCounting().\r
// The max value to which the semaphore can count should be 10, and the\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
* \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>void vSemaphoreDelete( xSemaphoreHandle xSemaphore );</pre>\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
+ * <pre>void vSemaphoreDelete( SemaphoreHandle_t xSemaphore );</pre>\r
*\r
* Delete a semaphore. This function must be used with care. For example,\r
* do not delete a mutex type semaphore if the mutex is held by a task.\r
*\r
* @param xSemaphore A handle to the semaphore to be deleted.\r
*\r
- * \page vSemaphoreDelete vSemaphoreDelete\r
+ * \defgroup vSemaphoreDelete vSemaphoreDelete\r
* \ingroup Semaphores\r
*/\r
-#define vSemaphoreDelete( xSemaphore ) vQueueDelete( ( xQueueHandle ) ( xSemaphore ) )\r
+#define vSemaphoreDelete( xSemaphore ) vQueueDelete( ( QueueHandle_t ) ( xSemaphore ) )\r
\r
/**\r
* semphr.h\r
- * <pre>xTaskHandle xSemaphoreGetMutexHolder( xSemaphoreHandle xMutex );</pre>\r
+ * <pre>TaskHandle_t xSemaphoreGetMutexHolder( 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
- * Note: This Is is a good way of determining if the calling task is the mutex \r
+ * Note: This 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
*/\r
#define xSemaphoreGetMutexHolder( xSemaphore ) xQueueGetMutexHolder( ( xSemaphore ) )\r
\r
+/**\r
+ * semphr.h\r
+ * <pre>UBaseType_t uxSemaphoreGetCount( SemaphoreHandle_t xMutex );</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