Update documentation of xTaskCheckForTimeOut function to reflect the

intended use of this API.

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

diff --git a/FreeRTOS/Source/include/task.h b/FreeRTOS/Source/include/task.h
index b4e246fb9bddcfbbe0ea9e034d35325b65601aa7..e05354dfa540cfa06c1a1c3ea7147e7fe7b77f14 100644 (file)
--- a/FreeRTOS/Source/include/task.h
+++ b/FreeRTOS/Source/include/task.h
@@ -314,13 +314,13 @@ is used in assert() statements. */
         // an automatic stack variable it might no longer exist, or at least have been corrupted, by the time\r
         // the new task attempts to access it.\r
         xTaskCreate( vTaskCode, "NAME", STACK_SIZE, &ucParameterToPass, tskIDLE_PRIORITY, &xHandle );\r
-     configASSERT( xHandle );\r
+        configASSERT( xHandle );\r
 \r
         // Use the handle to delete the task.\r
-     if( xHandle != NULL )\r
-     {\r
-            vTaskDelete( xHandle );\r
-     }\r
+        if( xHandle != NULL )\r
+        {\r
+               vTaskDelete( xHandle );\r
+        }\r
  }\r
    </pre>\r
  * \defgroup xTaskCreate xTaskCreate\r
@@ -498,9 +498,9 @@ static const TaskParameters_t xCheckTaskParameters =
        // for full information.\r
        {\r
                // Base address                                 Length  Parameters\r
-        { cReadWriteArray,                             32,             portMPU_REGION_READ_WRITE },\r
-        { cReadOnlyArray,                              32,             portMPU_REGION_READ_ONLY },\r
-        { cPrivilegedOnlyAccessArray,  128,    portMPU_REGION_PRIVILEGED_READ_WRITE }\r
+               { cReadWriteArray,                              32,             portMPU_REGION_READ_WRITE },\r
+               { cReadOnlyArray,                               32,             portMPU_REGION_READ_ONLY },\r
+               { cPrivilegedOnlyAccessArray,   128,    portMPU_REGION_PRIVILEGED_READ_WRITE }\r
        }\r
 };\r
 \r
@@ -584,9 +584,9 @@ static const TaskParameters_t xCheckTaskParameters =
        // for full information.\r
        {\r
                // Base address                                 Length  Parameters\r
-        { cReadWriteArray,                             32,             portMPU_REGION_READ_WRITE },\r
-        { cReadOnlyArray,                              32,             portMPU_REGION_READ_ONLY },\r
-        { cPrivilegedOnlyAccessArray,  128,    portMPU_REGION_PRIVILEGED_READ_WRITE }\r
+               { cReadWriteArray,                              32,             portMPU_REGION_READ_WRITE },\r
+               { cReadOnlyArray,                               32,             portMPU_REGION_READ_ONLY },\r
+               { cPrivilegedOnlyAccessArray,   128,    portMPU_REGION_PRIVILEGED_READ_WRITE }\r
        }\r
 \r
        &xTaskBuffer; // Holds the task's data structure.\r
@@ -2319,12 +2319,85 @@ TaskHandle_t xTaskGetCurrentTaskHandle( void ) PRIVILEGED_FUNCTION;
 \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 that previously captured to see if the\r
- * timeout has expired.\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