/*\r
- FreeRTOS.org V4.1.0 - Copyright (C) 2003-2006 Richard Barry.\r
-\r
- This file is part of the FreeRTOS.org distribution.\r
-\r
- FreeRTOS.org is free software; you can redistribute it and/or modify\r
- it under the terms of the GNU General Public License as published by\r
- the Free Software Foundation; either version 2 of the License, or\r
- (at your option) any later version.\r
-\r
- FreeRTOS.org is distributed in the hope that it will be useful,\r
- but WITHOUT ANY WARRANTY; without even the implied warranty of\r
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\r
- GNU General Public License for more details.\r
-\r
- You should have received a copy of the GNU General Public License\r
- along with FreeRTOS.org; if not, write to the Free Software\r
- Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA\r
-\r
- A special exception to the GPL can be applied should you wish to distribute\r
- a combined work that includes FreeRTOS.org, without being obliged to provide\r
- the source code for any proprietary components. See the licensing section \r
- of http://www.FreeRTOS.org for full details of how and when the exception\r
- can be applied.\r
-\r
- ***************************************************************************\r
- See http://www.FreeRTOS.org for documentation, latest information, license \r
- and contact details. Please ensure to read the configuration and relevant \r
- port sections of the online documentation.\r
- ***************************************************************************\r
+ FreeRTOS V7.1.1 - Copyright (C) 2012 Real Time Engineers Ltd.\r
+\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
+\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
+ >>>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. FreeRTOS is distributed in the hope that it will be useful, but\r
+ WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY\r
+ or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for\r
+ more details. You should have received a copy of the GNU General Public\r
+ License and the FreeRTOS license exception along with FreeRTOS; if not it\r
+ can be viewed here: http://www.freertos.org/a00114.html and also obtained\r
+ by writing to Richard Barry, contact details for whom are available on the\r
+ FreeRTOS WEB site.\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
+ * *\r
+ * http://www.FreeRTOS.org/FAQHelp.html *\r
+ * *\r
+ ***************************************************************************\r
+\r
+ \r
+ http://www.FreeRTOS.org - Documentation, training, latest information, \r
+ license and contact details.\r
+ \r
+ http://www.FreeRTOS.org/plus - A selection of FreeRTOS ecosystem products,\r
+ including FreeRTOS+Trace - an indispensable productivity tool.\r
+\r
+ Real Time Engineers ltd license FreeRTOS to High Integrity Systems, who sell \r
+ the code with commercial support, indemnification, and middleware, under \r
+ the OpenRTOS brand: http://www.OpenRTOS.com. High Integrity Systems also\r
+ provide a safety engineered and independently SIL3 certified version under \r
+ the SafeRTOS brand: http://www.SafeRTOS.com.\r
*/\r
\r
-#include "queue.h"\r
-\r
#ifndef SEMAPHORE_H\r
#define SEMAPHORE_H\r
\r
+#ifndef INC_FREERTOS_H\r
+ #error "include FreeRTOS.h" must appear in source files before "include semphr.h"\r
+#endif\r
+\r
+#include "queue.h"\r
+\r
typedef xQueueHandle xSemaphoreHandle;\r
\r
-#define semBINARY_SEMAPHORE_QUEUE_LENGTH ( ( unsigned portCHAR ) 1 )\r
-#define semSEMAPHORE_QUEUE_ITEM_LENGTH ( ( unsigned portCHAR ) 0 )\r
-#define semGIVE_BLOCK_TIME ( ( portTickType ) 0 )\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
\r
\r
/**\r
* as we don't want to actually store any data - we just want to know if the\r
* queue is empty or full.\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 xSemaphore Handle to the created semaphore. Should be of type xSemaphoreHandle.\r
*\r
* Example usage:\r
* \defgroup vSemaphoreCreateBinary vSemaphoreCreateBinary\r
* \ingroup Semaphores\r
*/\r
-#define vSemaphoreCreateBinary( xSemaphore ) { \\r
- xSemaphore = xQueueCreate( ( unsigned portCHAR ) 1, semSEMAPHORE_QUEUE_ITEM_LENGTH ); \\r
- if( xSemaphore != NULL ) \\r
- { \\r
- xSemaphoreGive( xSemaphore ); \\r
- } \\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
\r
/**\r
* semphr. h\r
- * xSemaphoreTake( \r
+ * <pre>xSemaphoreTake( \r
* xSemaphoreHandle xSemaphore, \r
* portTickType xBlockTime \r
* )</pre>\r
*\r
- * <i>Macro</i> to obtain a semaphore. The semaphore must of been created using \r
- * vSemaphoreCreateBinary ().\r
+ * <i>Macro</i> to obtain a semaphore. The semaphore must have previously been\r
+ * created with a call to vSemaphoreCreateBinary(), xSemaphoreCreateMutex() or\r
+ * xSemaphoreCreateCounting().\r
*\r
- * @param xSemaphore A handle to the semaphore being obtained. This is the\r
- * handle returned by vSemaphoreCreateBinary ();\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
- * real time. A block time of zero can be used to poll the semaphore.\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
- * @return pdTRUE if the semaphore was obtained. pdFALSE if xBlockTime\r
- * expired without the semaphore becoming available.\r
+ * @return pdTRUE if the semaphore was obtained. pdFALSE\r
+ * if xBlockTime expired without the semaphore becoming available.\r
*\r
* Example usage:\r
<pre>\r
* \defgroup xSemaphoreTake xSemaphoreTake\r
* \ingroup Semaphores\r
*/\r
-#define xSemaphoreTake( xSemaphore, xBlockTime ) xQueueReceive( ( xQueueHandle ) xSemaphore, NULL, xBlockTime )\r
+#define xSemaphoreTake( xSemaphore, xBlockTime ) xQueueGenericReceive( ( xQueueHandle ) ( xSemaphore ), NULL, ( xBlockTime ), pdFALSE )\r
+\r
+/**\r
+ * semphr. h\r
+ * xSemaphoreTakeRecursive( \r
+ * xSemaphoreHandle xMutex, \r
+ * portTickType xBlockTime \r
+ * )\r
+ *\r
+ * <i>Macro</i> to recursively obtain, or 'take', a mutex type semaphore. \r
+ * The mutex must have previously been created using a call to \r
+ * xSemaphoreCreateRecursiveMutex();\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
+ * not be available to any other task until it has also 'given' the mutex back\r
+ * exactly five times.\r
+ *\r
+ * @param xMutex A handle to the mutex being obtained. This is the\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
+ * 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
+ *\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
+\r
+ // A task that creates a mutex.\r
+ void vATask( void * pvParameters )\r
+ {\r
+ // Create the mutex to guard a shared resource.\r
+ xMutex = xSemaphoreCreateRecursiveMutex();\r
+ }\r
+\r
+ // A task that uses the mutex.\r
+ void vAnotherTask( void * pvParameters )\r
+ {\r
+ // ... Do other things.\r
+\r
+ if( xMutex != NULL )\r
+ {\r
+ // See if we can obtain the mutex. If the mutex is not available\r
+ // wait 10 ticks to see if it becomes free. \r
+ if( xSemaphoreTakeRecursive( xSemaphore, ( portTickType ) 10 ) == pdTRUE )\r
+ {\r
+ // We were able to obtain the mutex and can now access the\r
+ // shared resource.\r
+\r
+ // ...\r
+ // For some reason due to the nature of the code further calls to \r
+ // 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
+\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
+ // call structure. This is just for illustrative purposes.\r
+ xSemaphoreGiveRecursive( xMutex );\r
+ xSemaphoreGiveRecursive( xMutex );\r
+ xSemaphoreGiveRecursive( xMutex );\r
+\r
+ // Now the mutex can be taken by other tasks.\r
+ }\r
+ else\r
+ {\r
+ // We could not obtain the mutex and can therefore not access\r
+ // the shared resource safely.\r
+ }\r
+ }\r
+ }\r
+ </pre>\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( ( xQueueHandle ) ( xSemaphore ), NULL, ( xBlockTime ), pdFALSE )\r
\r
/**\r
* semphr. h\r
* <pre>xSemaphoreGive( xSemaphoreHandle xSemaphore )</pre>\r
*\r
- * <i>Macro</i> to release a semaphore. The semaphore must of been created using \r
- * vSemaphoreCreateBinary (), and obtained using sSemaphoreTake ().\r
+ * <i>Macro</i> to release a semaphore. The semaphore must have previously been\r
+ * created with a call to vSemaphoreCreateBinary(), xSemaphoreCreateMutex() or\r
+ * xSemaphoreCreateCounting(). and obtained using sSemaphoreTake().\r
*\r
- * This must not be used from an ISR. See xSemaphoreGiveFromISR () for\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
+ * xSemaphoreCreateRecursiveMutex().\r
+ *\r
* @param xSemaphore A handle to the semaphore being released. This is the\r
- * handle returned by vSemaphoreCreateBinary ();\r
+ * handle returned when the semaphore was created.\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
* \defgroup xSemaphoreGive xSemaphoreGive\r
* \ingroup Semaphores\r
*/\r
-#define xSemaphoreGive( xSemaphore ) xQueueSend( ( xQueueHandle ) xSemaphore, NULL, semGIVE_BLOCK_TIME )\r
+#define xSemaphoreGive( xSemaphore ) xQueueGenericSend( ( xQueueHandle ) ( xSemaphore ), NULL, semGIVE_BLOCK_TIME, queueSEND_TO_BACK )\r
+\r
+/**\r
+ * semphr. h\r
+ * <pre>xSemaphoreGiveRecursive( xSemaphoreHandle xMutex )</pre>\r
+ *\r
+ * <i>Macro</i> to recursively release, or 'give', a mutex type semaphore.\r
+ * The mutex must have previously been created using a call to \r
+ * xSemaphoreCreateRecursiveMutex();\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
+ * not be available to any other task until it has also 'given' the mutex back\r
+ * exactly five times.\r
+ *\r
+ * @param xMutex A handle to the mutex being released, or 'given'. This is the\r
+ * handle returned by xSemaphoreCreateMutex();\r
+ *\r
+ * @return pdTRUE if the semaphore was given.\r
+ *\r
+ * Example usage:\r
+ <pre>\r
+ xSemaphoreHandle xMutex = NULL;\r
+\r
+ // A task that creates a mutex.\r
+ void vATask( void * pvParameters )\r
+ {\r
+ // Create the mutex to guard a shared resource.\r
+ xMutex = xSemaphoreCreateRecursiveMutex();\r
+ }\r
+\r
+ // A task that uses the mutex.\r
+ void vAnotherTask( void * pvParameters )\r
+ {\r
+ // ... Do other things.\r
+\r
+ if( xMutex != NULL )\r
+ {\r
+ // See if we can obtain the mutex. If the mutex is not available\r
+ // wait 10 ticks to see if it becomes free. \r
+ if( xSemaphoreTakeRecursive( xMutex, ( portTickType ) 10 ) == pdTRUE )\r
+ {\r
+ // We were able to obtain the mutex and can now access the\r
+ // shared resource.\r
+\r
+ // ...\r
+ // For some reason due to the nature of the code further calls to \r
+ // 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
+\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
+ // to xSemaphoreGiveRecursive() would be called as a call stack\r
+ // unwound. This is just for demonstrative purposes.\r
+ xSemaphoreGiveRecursive( xMutex );\r
+ xSemaphoreGiveRecursive( xMutex );\r
+ xSemaphoreGiveRecursive( xMutex );\r
+\r
+ // Now the mutex can be taken by other tasks.\r
+ }\r
+ else\r
+ {\r
+ // We could not obtain the mutex and can therefore not access\r
+ // the shared resource safely.\r
+ }\r
+ }\r
+ }\r
+ </pre>\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( ( xQueueHandle ) ( xSemaphore ), NULL, semGIVE_BLOCK_TIME, queueSEND_TO_BACK )\r
\r
/**\r
* semphr. h\r
* <pre>\r
xSemaphoreGiveFromISR( \r
xSemaphoreHandle xSemaphore, \r
- portSHORT sTaskPreviouslyWoken \r
+ signed portBASE_TYPE *pxHigherPriorityTaskWoken\r
)</pre>\r
*\r
- * <i>Macro</i> to release a semaphore. The semaphore must of been created using \r
- * vSemaphoreCreateBinary (), and obtained using xSemaphoreTake ().\r
+ * <i>Macro</i> to release a semaphore. The semaphore must have previously been\r
+ * created with a call to vSemaphoreCreateBinary() or xSemaphoreCreateCounting().\r
+ *\r
+ * Mutex type semaphores (those created using a call to xSemaphoreCreateMutex())\r
+ * must not be used with this macro.\r
*\r
* This macro can be used from an ISR.\r
*\r
* @param xSemaphore A handle to the semaphore being released. This is the\r
- * handle returned by vSemaphoreCreateBinary ();\r
+ * handle returned when the semaphore was created.\r
*\r
- * @param sTaskPreviouslyWoken This is included so an ISR can make multiple calls\r
- * to xSemaphoreGiveFromISR () from a single interrupt. The first call\r
- * should always pass in pdFALSE. Subsequent calls should pass in\r
- * the value returned from the previous call. See the file serial .c in the\r
- * PC port for a good example of using xSemaphoreGiveFromISR ().\r
+ * @param pxHigherPriorityTaskWoken xSemaphoreGiveFromISR() will set\r
+ * *pxHigherPriorityTaskWoken to pdTRUE if giving the semaphore caused a task\r
+ * to unblock, and the unblocked task has a priority higher than the currently\r
+ * running task. If xSemaphoreGiveFromISR() sets this value to pdTRUE then\r
+ * a context switch should be requested before the interrupt is exited.\r
*\r
- * @return pdTRUE if a task was woken by releasing the semaphore. This is \r
- * used by the ISR to determine if a context switch may be required following\r
- * the ISR.\r
+ * @return pdTRUE if the semaphore was successfully given, otherwise errQUEUE_FULL.\r
*\r
* Example usage:\r
<pre>\r
- #define LONG_TIME 0xffff\r
- #define TICKS_TO_WAIT 10\r
+ \#define LONG_TIME 0xffff\r
+ \#define TICKS_TO_WAIT 10\r
xSemaphoreHandle xSemaphore = NULL;\r
\r
// Repetitive task.\r
{\r
for( ;; )\r
{\r
- // We want this task to run every 10 ticks or a timer. The semaphore \r
- // was created before this task was started\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
if( xSemaphoreTake( xSemaphore, LONG_TIME ) == pdTRUE )\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
- // again.\r
+ // again. Note when using the semaphore for synchronisation with an\r
+ // ISR in this manner there is no need to 'give' the semaphore back.\r
}\r
}\r
}\r
// Timer ISR\r
void vTimerISR( void * pvParameters )\r
{\r
- static unsigned portCHAR ucLocalTickCount = 0;\r
+ static unsigned char ucLocalTickCount = 0;\r
+ static signed portBASE_TYPE xHigherPriorityTaskWoken;\r
\r
// A timer tick has occurred.\r
\r
// ... Do other time functions.\r
\r
// Is it time for vATask () to run?\r
+ xHigherPriorityTaskWoken = pdFALSE;\r
ucLocalTickCount++;\r
if( ucLocalTickCount >= TICKS_TO_WAIT )\r
{\r
// Unblock the task by releasing the semaphore.\r
- xSemaphoreGive( xSemaphore );\r
+ xSemaphoreGiveFromISR( xSemaphore, &xHigherPriorityTaskWoken );\r
\r
// Reset the count so we release the semaphore again in 10 ticks time.\r
ucLocalTickCount = 0;\r
}\r
+\r
+ if( xHigherPriorityTaskWoken != pdFALSE )\r
+ {\r
+ // We can force a context switch here. Context switching from an\r
+ // ISR uses port specific syntax. Check the demo task for your port\r
+ // to find the syntax required.\r
+ }\r
}\r
</pre>\r
* \defgroup xSemaphoreGiveFromISR xSemaphoreGiveFromISR\r
* \ingroup Semaphores\r
*/\r
-#define xSemaphoreGiveFromISR( xSemaphore, xTaskPreviouslyWoken ) xQueueSendFromISR( ( xQueueHandle ) xSemaphore, NULL, xTaskPreviouslyWoken )\r
+#define xSemaphoreGiveFromISR( xSemaphore, pxHigherPriorityTaskWoken ) xQueueGenericSendFromISR( ( xQueueHandle ) ( xSemaphore ), NULL, ( pxHigherPriorityTaskWoken ), queueSEND_TO_BACK )\r
\r
+/**\r
+ * semphr. h\r
+ * <pre>\r
+ xSemaphoreTakeFromISR( \r
+ xSemaphoreHandle xSemaphore, \r
+ signed portBASE_TYPE *pxHigherPriorityTaskWoken\r
+ )</pre>\r
+ *\r
+ * <i>Macro</i> to take a semaphore from an ISR. The semaphore must have \r
+ * previously been created with a call to vSemaphoreCreateBinary() or \r
+ * xSemaphoreCreateCounting().\r
+ *\r
+ * Mutex type semaphores (those created using a call to xSemaphoreCreateMutex())\r
+ * must not be used with this macro.\r
+ *\r
+ * This macro can be used from an ISR, however taking a semaphore from an ISR\r
+ * is not a common operation. It is likely to only be useful when taking a\r
+ * counting semaphore when an interrupt is obtaining an object from a resource\r
+ * pool (when the semaphore count indicates the number of resources available).\r
+ *\r
+ * @param xSemaphore A handle to the semaphore being taken. This is the\r
+ * handle returned when the semaphore was created.\r
+ *\r
+ * @param pxHigherPriorityTaskWoken xSemaphoreTakeFromISR() will set\r
+ * *pxHigherPriorityTaskWoken to pdTRUE if taking the semaphore caused a task\r
+ * to unblock, and the unblocked task has a priority higher than the currently\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
+ * pdFALSE\r
+ */\r
+#define xSemaphoreTakeFromISR( xSemaphore, pxHigherPriorityTaskWoken ) xQueueReceiveFromISR( ( xQueueHandle ) ( xSemaphore ), NULL, ( pxHigherPriorityTaskWoken ) )\r
+\r
+/**\r
+ * semphr. h\r
+ * <pre>xSemaphoreHandle xSemaphoreCreateMutex( void )</pre>\r
+ *\r
+ * <i>Macro</i> that implements a mutex semaphore by using the existing queue \r
+ * mechanism.\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
+ *\r
+ * Mutex type semaphores cannot be used from within interrupt service routines. \r
+ *\r
+ * See vSemaphoreCreateBinary() for an alternative implementation that can be \r
+ * used for pure synchronisation (where one task or interrupt always 'gives' the \r
+ * semaphore and another always 'takes' the semaphore) and from within interrupt \r
+ * service routines.\r
+ *\r
+ * @return xSemaphore Handle to the created mutex semaphore. Should be of type \r
+ * xSemaphoreHandle.\r
+ *\r
+ * Example usage:\r
+ <pre>\r
+ xSemaphoreHandle xSemaphore;\r
+\r
+ void vATask( void * pvParameters )\r
+ {\r
+ // Semaphore cannot be used before a call to xSemaphoreCreateMutex().\r
+ // This is a macro so pass the variable in directly.\r
+ xSemaphore = xSemaphoreCreateMutex();\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 vSemaphoreCreateMutex vSemaphoreCreateMutex\r
+ * \ingroup Semaphores\r
+ */\r
+#define xSemaphoreCreateMutex() xQueueCreateMutex( queueQUEUE_TYPE_MUTEX )\r
+\r
+\r
+/**\r
+ * semphr. h\r
+ * <pre>xSemaphoreHandle xSemaphoreCreateRecursiveMutex( void )</pre>\r
+ *\r
+ * <i>Macro</i> that implements a recursive mutex by using the existing queue \r
+ * mechanism.\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
+ *\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 vSemaphoreCreateBinary() for an alternative implementation that can be \r
+ * used for pure synchronisation (where one task or interrupt always 'gives' the \r
+ * semaphore and another always 'takes' the semaphore) and from within interrupt \r
+ * service routines.\r
+ *\r
+ * @return xSemaphore Handle to the created mutex semaphore. Should be of type \r
+ * xSemaphoreHandle.\r
+ *\r
+ * Example usage:\r
+ <pre>\r
+ xSemaphoreHandle xSemaphore;\r
+\r
+ void vATask( void * pvParameters )\r
+ {\r
+ // Semaphore cannot be used before a call to xSemaphoreCreateMutex().\r
+ // This is a macro so pass the variable in directly.\r
+ xSemaphore = xSemaphoreCreateRecursiveMutex();\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 vSemaphoreCreateMutex vSemaphoreCreateMutex\r
+ * \ingroup Semaphores\r
+ */\r
+#define xSemaphoreCreateRecursiveMutex() xQueueCreateMutex( queueQUEUE_TYPE_RECURSIVE_MUTEX )\r
+\r
+/**\r
+ * semphr. h\r
+ * <pre>xSemaphoreHandle xSemaphoreCreateCounting( unsigned portBASE_TYPE uxMaxCount, unsigned portBASE_TYPE uxInitialCount )</pre>\r
+ *\r
+ * <i>Macro</i> that creates a counting semaphore by using the existing \r
+ * queue mechanism. \r
+ *\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
+ * @return Handle to the created semaphore. Null if the semaphore could not be\r
+ * created.\r
+ * \r
+ * Example usage:\r
+ <pre>\r
+ xSemaphoreHandle xSemaphore;\r
+\r
+ void vATask( void * pvParameters )\r
+ {\r
+ xSemaphoreHandle 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
+ // initial value assigned to the count should be 0.\r
+ xSemaphore = xSemaphoreCreateCounting( 10, 0 );\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 xSemaphoreCreateCounting xSemaphoreCreateCounting\r
+ * \ingroup Semaphores\r
+ */\r
+#define xSemaphoreCreateCounting( uxMaxCount, uxInitialCount ) xQueueCreateCountingSemaphore( ( uxMaxCount ), ( uxInitialCount ) )\r
+\r
+/**\r
+ * semphr. h\r
+ * <pre>void vSemaphoreDelete( xSemaphoreHandle 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
+ * \ingroup Semaphores\r
+ */\r
+#define vSemaphoreDelete( xSemaphore ) vQueueDelete( ( xQueueHandle ) ( xSemaphore ) )\r
+\r
+/**\r
+ * semphr.h\r
+ * <pre>xTaskHandle xSemaphoreGetMutexHolder( xSemaphoreHandle 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
+ * 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
+#endif /* SEMAPHORE_H */\r
\r
-#endif\r
\r
projects / freertos / blobdiff