Changes to comments only.

git-svn-id: https://svn.code.sf.net/p/freertos/code/trunk@1989 1d2547de-c912-0410-9cb9-b8ca96c0e9e2

diff --git a/FreeRTOS/Source/include/queue.h b/FreeRTOS/Source/include/queue.h
index 50110f9c358a7447a9d71072ba45bbd75b4ba9ac..0f12794b7cb1c1597adca85e58b4ffe8042be9e9 100644 (file)
--- a/FreeRTOS/Source/include/queue.h
+++ b/FreeRTOS/Source/include/queue.h
@@ -420,19 +420,20 @@ typedef void * xQueueSetMemberHandle;
  * <pre>\r
  portBASE_TYPE xQueueOverwrite(\r
                                                          xQueueHandle xQueue,\r
-                                                         const void * pvItemToQueue,\r
+                                                         const void * pvItemToQueue\r
                                                 );\r
  * </pre>\r
  *\r
- * Only for use with queues that can hold a single item - so the queue is either\r
+ * Only for use with queues that have a length of one - so the queue is either\r
  * empty or full.\r
  *\r
  * Post an item on a queue.  If the queue is already full then overwrite the\r
  * value held in the queue.  The item is queued by copy, not by reference.\r
+ *\r
  * This function must not be called from an interrupt service routine.\r
  * See xQueueOverwriteFromISR () for an alternative which may be used in an ISR.\r
  *\r
- * @param xQueue The handle to the queue on which the item is to be posted.\r
+ * @param xQueue The handle of the queue to which the data is being sent.\r
  *\r
  * @param pvItemToQueue A pointer to the item that is to be placed on the\r
  * queue.  The size of the items the queue will hold was defined when the\r
@@ -440,9 +441,9 @@ typedef void * xQueueSetMemberHandle;
  * into the queue storage area.\r
  *\r
  * @return xQueueOverwrite() is a macro that calls xQueueGenericSend(), and\r
- * therefore has the same return values as xQueueSendToFront().  However, as\r
- * xQueueOverwrite() will write to the queue even when the queue is full pdPASS\r
- * will be returned in all cases (errQUEUE_FULL will never be returned).\r
+ * therefore has the same return values as xQueueSendToFront().  However, pdPASS\r
+ * is the only value that can be returned because xQueueOverwrite() will write\r
+ * to the queue even when the queue is already full.\r
  *\r
  * Example usage:\r
    <pre>\r
@@ -470,7 +471,7 @@ typedef void * xQueueSetMemberHandle;
 \r
        if( ulValReceived != 10 )\r
        {\r
-               // Error!\r
+               // Error unless the item was removed by a different task.\r
        }\r
 \r
        // The queue is still full.  Use xQueueOverwrite() to overwrite the\r
@@ -1086,7 +1087,7 @@ void vQueueDelete( xQueueHandle xQueue ) PRIVILEGED_FUNCTION;
                                                 );\r
  * </pre>\r
  *\r
- * A version of xQueueOverwrite() that can be used from an interrupt service\r
+ * A version of xQueueOverwrite() that can be used in an interrupt service\r
  * routine (ISR).\r
  *\r
  * Only for use with queues that can hold a single item - so the queue is either\r
@@ -1105,14 +1106,14 @@ void vQueueDelete( xQueueHandle xQueue ) PRIVILEGED_FUNCTION;
  * @param pxHigherPriorityTaskWoken xQueueOverwriteFromISR() will set\r
  * *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task\r
  * to unblock, and the unblocked task has a priority higher than the currently\r
- * running task.  If xQueueSendFromISR() sets this value to pdTRUE then\r
+ * running task.  If xQueueOverwriteFromISR() sets this value to pdTRUE then\r
  * a context switch should be requested before the interrupt is exited.\r
  *\r
- * @return xQueueOverwriteFromISR() is a macro that calls \r
- * xQueueGenericSendFromISR(), and therefore has the same return values as \r
- * xQueueSendToFrontFromISR().  However, as xQueueOverwriteFromISR() will write \r
- * to the queue even when the queue is full pdPASS will be returned in all cases \r
- * (errQUEUE_FULL will never be returned).\r
+ * @return xQueueOverwriteFromISR() is a macro that calls\r
+ * xQueueGenericSendFromISR(), and therefore has the same return values as\r
+ * xQueueSendToFrontFromISR().  However, pdPASS is the only value that can be\r
+ * returned because xQueueOverwriteFromISR() will write to the queue even when\r
+ * the queue is already full.\r
  *\r
  * Example usage:\r
    <pre>\r
@@ -1122,7 +1123,7 @@ void vQueueDelete( xQueueHandle xQueue ) PRIVILEGED_FUNCTION;
  void vFunction( void *pvParameters )\r
  {\r
        // Create a queue to hold one unsigned long value.  It is strongly\r
-       // recommended *not* to use xQueueOverwrite() on queues that can\r
+       // recommended *not* to use xQueueOverwriteFromISR() on queues that can\r
        // contain more than one value, and doing so will trigger an assertion\r
        // if configASSERT() is defined.\r
        xQueue = xQueueCreate( 1, sizeof( unsigned long ) );\r
@@ -1142,11 +1143,20 @@ unsigned long ulVarToSend, ulValReceived;
        // pass because the value held in the queue will be overwritten with the\r
        // new value.\r
        ulVarToSend = 100;\r
-       xQueueOverwrite( xQueue, &ulVarToSend, &xHigherPriorityTaskWoken );\r
+       xQueueOverwriteFromISR( xQueue, &ulVarToSend, &xHigherPriorityTaskWoken );\r
 \r
        // Reading from the queue will now return 100.\r
 \r
        // ...\r
+       \r
+       if( xHigherPrioritytaskWoken == pdTRUE )\r
+       {\r
+               // Writing to the queue caused a task to unblock and the unblocked task\r
+               // has a priority higher than or equal to the priority of the currently\r
+               // executing task (the task this interrupt interrupted).  Perform a context\r
+               // switch so this interrupt returns directly to the unblocked task.\r
+               portYIELD_FROM_ISR(); // or portEND_SWITCHING_ISR() depending on the port.\r
+       }\r
 }\r
  </pre>\r
  * \defgroup xQueueOverwriteFromISR xQueueOverwriteFromISR\r