From: rtel <rtel@1d2547de-c912-0410-9cb9-b8ca96c0e9e2>
Date: Wed, 1 Jan 2020 22:24:44 +0000 (+0000)
Subject: Minor updates to comment block for xTaskCheckForTimeOut().
X-Git-Tag: V10.3.0~32
X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=23d9c29e025cc0815ab214d11d9d37ea78b9d025;p=freertos

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