Minor updates to comment block for xTaskCheckForTimeOut().

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

diff --git a/FreeRTOS/Source/include/task.h b/FreeRTOS/Source/include/task.h
index e05354dfa540cfa06c1a1c3ea7147e7fe7b77f14..6d9548ea18087bdefc623f6c1904a2c3cff798dd 100644 (file)
--- a/FreeRTOS/Source/include/task.h
+++ b/FreeRTOS/Source/include/task.h
@@ -2201,6 +2201,103 @@ uint32_t ulTaskNotifyTake( BaseType_t xClearCountOnExit, TickType_t xTicksToWait
  */\r
 BaseType_t xTaskNotifyStateClear( TaskHandle_t xTask );\r
 \r
  */\r
 BaseType_t xTaskNotifyStateClear( TaskHandle_t xTask );\r
 \r

+/**\r
+ * task.h\r
+ * <pre>void vTaskSetTimeOutState( TimeOut_t * const pxTimeOut )</pre>\r
+ *\r
+ * Capture the current time for future use with xTaskCheckForTimeOut().\r
+ *\r
+ * @param pxTimeOut Pointer to a timeout object into which the current time\r
+ * is to be captured.  The captured time includes the tick count and the number\r
+ * of times the tick count has overflowed since the system first booted.\r
+ * \defgroup vTaskSetTimeOutState vTaskSetTimeOutState\r
+ * \ingroup TaskCtrl\r
+ */\r
+void vTaskSetTimeOutState( TimeOut_t * const pxTimeOut ) PRIVILEGED_FUNCTION;\r
+\r
+/**\r
+ * task.h\r
+ * <pre>BaseType_t xTaskCheckForTimeOut( TimeOut_t * const pxTimeOut, TickType_t * const pxTicksToWait );</pre>\r
+ *\r
+ * Determines if pxTicksToWait ticks has passed since a time was captured\r
+ * using a call to vTaskSetTimeOutState().  The captured time includes the tick\r
+ * count and the number of times the tick count has overflowed.\r
+ *\r
+ * @param pxTimeOut The time status as captured previously using\r
+ * vTaskSetTimeOutState. If the timeout has not yet occurred, it is updated\r
+ * to reflect the current time status.\r
+ * @param pxTicksToWait The number of ticks to check for timeout i.e. if\r
+ * pxTicksToWait ticks have passed since pxTimeOut was last updated (either by\r
+ * vTaskSetTimeOutState() or xTaskCheckForTimeOut()), the timeout has occurred.\r
+ * If the timeout has not occurred, pxTIcksToWait is updated to reflect the\r
+ * number of remaining ticks.\r
+ *\r
+ * @return If timeout has occurred, pdTRUE is returned. Otherwise pdFALSE is\r
+ * returned and pxTicksToWait is updated to reflect the number of remaining\r
+ * ticks.\r
+ *\r
+ * @see https://www.freertos.org/xTaskCheckForTimeOut.html\r
+ *\r
+ * Example Usage:\r
+ * <pre>\r
+       // Driver library function used to receive uxWantedBytes from an Rx buffer\r
+       // that is filled by a UART interrupt. If there are not enough bytes in the\r
+       // Rx buffer then the task enters the Blocked state until it is notified that\r
+       // more data has been placed into the buffer. If there is still not enough\r
+       // data then the task re-enters the Blocked state, and xTaskCheckForTimeOut()\r
+       // is used to re-calculate the Block time to ensure the total amount of time\r
+       // spent in the Blocked state does not exceed MAX_TIME_TO_WAIT. This\r
+       // continues until either the buffer contains at least uxWantedBytes bytes,\r
+       // or the total amount of time spent in the Blocked state reaches\r
+       // MAX_TIME_TO_WAIT – at which point the task reads however many bytes are\r
+       // available up to a maximum of uxWantedBytes.\r
+\r
+       size_t xUART_Receive( uint8_t *pucBuffer, size_t uxWantedBytes )\r
+       {\r
+       size_t uxReceived = 0;\r
+       TickType_t xTicksToWait = MAX_TIME_TO_WAIT;\r
+       TimeOut_t xTimeOut;\r
+\r
+               // Initialize xTimeOut.  This records the time at which this function\r
+               // was entered.\r
+               vTaskSetTimeOutState( &xTimeOut );\r
+\r
+               // Loop until the buffer contains the wanted number of bytes, or a\r
+               // timeout occurs.\r
+               while( UART_bytes_in_rx_buffer( pxUARTInstance ) < uxWantedBytes )\r
+               {\r
+                       // The buffer didn't contain enough data so this task is going to\r
+                       // enter the Blocked state. Adjusting xTicksToWait to account for\r
+                       // any time that has been spent in the Blocked state within this\r
+                       // function so far to ensure the total amount of time spent in the\r
+                       // Blocked state does not exceed MAX_TIME_TO_WAIT.\r
+                       if( xTaskCheckForTimeOut( &xTimeOut, &xTicksToWait ) != pdFALSE )\r
+                       {\r
+                               //Timed out before the wanted number of bytes were available,\r
+                               // exit the loop.\r
+                               break;\r
+                       }\r
+\r
+                       // Wait for a maximum of xTicksToWait ticks to be notified that the\r
+                       // receive interrupt has placed more data into the buffer.\r
+                       ulTaskNotifyTake( pdTRUE, xTicksToWait );\r
+               }\r
+\r
+               // Attempt to read uxWantedBytes from the receive buffer into pucBuffer.\r
+               // The actual number of bytes read (which might be less than\r
+               // uxWantedBytes) is returned.\r
+               uxReceived = UART_read_from_receive_buffer( pxUARTInstance,\r
+                                                                                                       pucBuffer,\r
+                                                                                                       uxWantedBytes );\r
+\r
+               return uxReceived;\r
+       }\r
+ </pre>\r
+ * \defgroup xTaskCheckForTimeOut xTaskCheckForTimeOut\r
+ * \ingroup TaskCtrl\r
+ */\r
+BaseType_t xTaskCheckForTimeOut( TimeOut_t * const pxTimeOut, TickType_t * const pxTicksToWait ) PRIVILEGED_FUNCTION;\r
+\r

 /*-----------------------------------------------------------\r
  * SCHEDULER INTERNALS AVAILABLE FOR PORTING PURPOSES\r
  *----------------------------------------------------------*/\r
 /*-----------------------------------------------------------\r
  * SCHEDULER INTERNALS AVAILABLE FOR PORTING PURPOSES\r
  *----------------------------------------------------------*/\r


@@ -2317,90 +2414,6 @@ TickType_t uxTaskResetEventItemValue( void ) PRIVILEGED_FUNCTION;
  */\r
 TaskHandle_t xTaskGetCurrentTaskHandle( void ) PRIVILEGED_FUNCTION;\r
 \r
  */\r
 TaskHandle_t xTaskGetCurrentTaskHandle( void ) PRIVILEGED_FUNCTION;\r
 \r

-/*\r
- * Capture the current time status for future reference.\r
- *\r
- * @param[out] pxTimeOut Pointer to a timeout object into which the current\r
- * time status is to be captured.\r
- */\r
-void vTaskSetTimeOutState( TimeOut_t * const pxTimeOut ) PRIVILEGED_FUNCTION;\r
-\r
-/*\r
- * Compare the time status now with the one previously captured using\r
- * vTaskSetTimeOutState to check if the timeout has occurred.\r
- *\r
- * @param[in/out] pxTimeOut The time status as captured previously using\r
- * vTaskSetTimeOutState. If the timeout has not yet occurred, it is updated\r
- * to reflect the current time status.\r
- * @param[in/out] pxTicksToWait The number of ticks to check for timeout i.e. if\r
- * pxTicksToWait ticks have passed since pxTimeOut was last updated (either by\r
- * vTaskSetTimeOutState or xTaskCheckForTimeOut), the timeout has occurred. If\r
- * the timeout has not occurred, it is updated to reflect the number of\r
- * reamaining ticks.\r
- *\r
- * @return If timeout has occurred, pdTRUE is returned. Otherwise pdFALSE is\r
- * returned and pxTicksToWait is updated to reflect the number of remaining\r
- * ticks.\r
- *\r
- * @see https://www.freertos.org/xTaskCheckForTimeOut.html\r
- *\r
- * Example Usage:\r
- *\r
- * // Driver library function used to receive uxWantedBytes from an Rx buffer\r
- * // that is filled by a UART interrupt. If there are not enough bytes in the\r
- * // Rx buffer then the task enters the Blocked state until it is notified that\r
- * // more data has been placed into the buffer. If there is still not enough\r
- * // data then the task re-enters the Blocked state, and xTaskCheckForTimeOut()\r
- * // is used to re-calculate the Block time to ensure the total amount of time\r
- * // spent in the Blocked state does not exceed MAX_TIME_TO_WAIT. This\r
- * // continues until either the buffer contains at least uxWantedBytes bytes,\r
- * // or the total amount of time spent in the Blocked state reaches\r
- * // MAX_TIME_TO_WAIT – at which point the task reads however many bytes are\r
- * // available up to a maximum of uxWantedBytes.\r
- *\r
- * size_t xUART_Receive( uint8_t *pucBuffer, size_t uxWantedBytes )\r
- * {\r
- * size_t uxReceived = 0;\r
- * TickType_t xTicksToWait = MAX_TIME_TO_WAIT;\r
- * TimeOut_t xTimeOut;\r
- * \r
- *             // Initialize xTimeOut.  This records the time at which this function\r
- *             // was entered.\r
- *             vTaskSetTimeOutState( &xTimeOut );\r
- * \r
- *             // Loop until the buffer contains the wanted number of bytes, or a\r
- *             // timeout occurs.\r
- *             while( UART_bytes_in_rx_buffer( pxUARTInstance ) < uxWantedBytes )\r
- *             {\r
- *                     // The buffer didn't contain enough data so this task is going to\r
- *                     // enter the Blocked state. Adjusting xTicksToWait to account for\r
- *                     // any time that has been spent in the Blocked state within this\r
- *                     // function so far to ensure the total amount of time spent in the\r
- *                     // Blocked state does not exceed MAX_TIME_TO_WAIT.\r
- *                     if( xTaskCheckForTimeOut( &xTimeOut, &xTicksToWait ) != pdFALSE )\r
- *                     {\r
- *                             //Timed out before the wanted number of bytes were available,\r
- *                             // exit the loop.\r
- *                             break;\r
- *                     }\r
- *\r
- *                     // Wait for a maximum of xTicksToWait ticks to be notified that the\r
- *                     // receive interrupt has placed more data into the buffer.\r
- *                     ulTaskNotifyTake( pdTRUE, xTicksToWait );\r
- *             }\r
- * \r
- *             // Attempt to read uxWantedBytes from the receive buffer into pucBuffer.\r
- *             // The actual number of bytes read (which might be less than\r
- *             // uxWantedBytes) is returned.\r
- *             uxReceived = UART_read_from_receive_buffer( pxUARTInstance,\r
- *                                                                                                     pucBuffer,\r
- *                                                                                                     uxWantedBytes );\r
- *\r
- *             return uxReceived;\r
- * }\r
- */\r
-BaseType_t xTaskCheckForTimeOut( TimeOut_t * const pxTimeOut, TickType_t * const pxTicksToWait ) PRIVILEGED_FUNCTION;\r
-\r

 /*\r
  * Shortcut used by the queue implementation to prevent unnecessary call to\r
  * taskYIELD();\r
 /*\r
  * Shortcut used by the queue implementation to prevent unnecessary call to\r
  * taskYIELD();\r